Developer Setup Guide

Install Development Tools

Chocolately is a package manager for windows applications. It is a handy tool for getting common applications installed and keeping them current on your developer machine. We will be using it to install most Agent requirements.

Install Chocolately

From an administrative cmd.exe command prompt execute the following.

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

From the same shell now you should be able to run Chocolately install commands.

Add packages required by Agent

These packages are required for doing Agent development.

choco install ruby
choco install git

Handy package to have for zip file handling.

choco install 7zip

It is also handy to add browsers you'll be developing with. You should at least update IE to 10 or 11 as Visual Studio is happier with those versions installed.

choco install ie11
choco install GoogleChrome
choco install Firefox

Install Node.js

choco install nodejs-lts

OR

Go to https://nodejs.org/ and download the latest LTS (different from "Stable") installer. Run it to install Node.js.

[Optional] Install Yarn Package Manager

Yarn is a drop-in replacement for npm as a javascript package manager. It supports a determinent installation of dependencies and caches packages so that consecutive installations are much faster. Any common npm command can be run by simply substituting "yarn" for "npm" in the command. For example, npm install would become yarn install. This is optional as npm will also allow for installing javascript dependencies and comes pre-packaged with Node.js.

choco install yarn

OR

Go to https://yarnpkg.com/en/docs/install and download the Windows Installer for yarn, and then run the installer.

Install Required IIS Features

Windows Authentication

If you plan on using Windows Authentication (Active Directory integration) you'll need to configure IIS for this.

Under World Wide Web Services open Security and select Windows Authorization

Install Dovetail SDK

Download and run the installer for your platform from Dovetail Support.

Install Dovetail Seeker

Agent will not work properly without Dovetail's search product Dovetail Seeker as many object pickers are really using search under the hood.

Add MSMQ Support

Install Seeker

It may take a little while for your search index to get created after starting the indexing service.

Install Schema Editor

Install Visual Studio

I installed Visual Studio 2015 or higher from MSDN. I unselected all options but web development. Sit back. This install takes a long time.

Maybe you can get some other install tasks done in the meanwhile.

Using Chocolately to install Visual Studio

Another way to get Visual Studio installed is to use Chocolately. 

choco install visualstudio2017enterprise

If you need to find the package name for a different SKU or version of Visual Studio, try the Chocolately Gallery.

Building Agent from source code

You are done installing a lot of software and now we are ready to work with Agent.

Get the source

Setup your development database

You can manually apply schema changes and import data files. If you like.

Because during development these things can change a lot we have provided automation which will apply schema changes and data to your development database. You will need to do this before your application will build or run properly.

This automation uses our products Dovetail SchemaEditor and Archive Manager (Diet) to apply schema changes and import data files. Both applications are licensed products, and require a license file or key to function.

Edit Developer Configuration settings

Default database and typical application settings are sourced from configuration files in the /config directory.

Database settings

Open ./config/app{db}Settings.rb for your desired database platform in your favorite editor.

Notice how the database variables get used to build a connection string. These variables are used in other scripts so be sure to setup all the DATABASE variables do not just edit the DATABASE_CONNECTION.

Database platform and other settings

Open ./config/appSettings.rb and ensure the correct database platform is selected. Also make sure the other settings are as you like.

How are these settings used?

Database and common development centric application settings are controlled with these .rb files. rake setup:* and rake package:* tasks will use these settings to update the application configuration settings.

Diet license

Edit the DIET_LICENSE variable to have the correct ArchiveManager (Diet) license.

If you do not wish to put this license in your source code repository you can alternatively set an environment variable DIET_LICENSE with the correct key.

Other configuration

Please ensure the SEEKER_URL is set to where your Dovetail Seeker web service is installed.

Also ensure that your ATTACHMENT_PATH is correct if you are sharing a development database across users this maybe a UNC windows share.

Seeker Agent specifications

There are a few Seeker document specification XML fragments in the directory config/seeker.config which need to be applied to your Seeker document specification.

We have automation which will do this for you when Seeker is installed locally.

rake setup:switch_seeker

Finally

We are done making sure all the configuration is set. It is time to setup your development database.

rake setup:db

Note If each time a rake command is run, the output is the same and is something along the lines of

Using rake 10.5.0
Using bottles 2.1.0.584
Using fubudocs 0.9.9.297
Using ripple-cli 2.3.4.151
Using rubyzip 1.2.1
Using bundler 1.14.6
Using fuburake 0.9.5.37
Bundle complete! 4 Gemfile dependencies, 7 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
Bundler and all the gems need to be installed prior to running this rake script. Installing...

this is an indication that you have multiple versions of rake installed. To rectify this, run gem uninstall rake. It should present a prompt asking which version to uninstall. Agent uses v10.x, so select the other version(s) to uninstall. To confirm this was effective, run

$rake --version
rake, version 10.5.0

$ bundle exec rake --version
rake, version 10.5.0

The important thing is that the versions match. Now running any rake command should succeed.

Building Agent from the command line

There are steps to build Agent that need occur outside of Visual Studio. This is handled using Rake.

Build Dependencies

Our source code has a few different package manager dependencies integrated with the build.

These dependencies are are retrieved at build time and are all automated.

Dovetail Nugets

Agent source projects take dependencies on non-public Nugets. These non-public Nugets are released to a private feed to which your organization will receive a unique private URL. You need to update the file ripple.config to use this feed.

Private Feed URL

To obtain your private Nuget feed URL login into our support website. The support home page should have a Nuget Feed entry under Your URLs. If you do not see this entry please create a support case and we will setup a private feed for your organization.

Edit ripple.config

Once you have obtained your private Nuget feed URL you need to edit ripple.config at the root of your source directory. This file contains XML. The first <Feed> element is a placeholder for your private Nuget feed.

Build and test

Invoking Rake by itself will build, and run tests for Agent. During your first run it will download all build dependencies mentioned above.

rake

Take it for a spin

Two ways to get the web application running.

Launch!

rake start_web

This will build a production version of the application and configure an IIS web site at http://localhost:8989.

Visual Studio

Double click on the Visual Studio solution /source/agent.sln. Make sure that the source/Web project is your "StartUp Project". If it is. The Web project will be bold in your Solution Explorer.

Hit Ctrl+F5 to build and launch the site.

To launch from Visual Studio you will need to run rake at least once first.

Frontend Development

When developing in frontend code (javascript, less, handlebars, etc.), you'll need to have npm installed in order to run a watch task that processes the files. npm is automatically installed with node.js. To run the watch task that compiles javascript:

npm run webpack -- --watch

This task must be running while doing javascript development in order to process the files correctly.

For styling, there are custom-styles.less and custom-print-styles.less files that can be used to customize the look of Agent. These are automatically compiled into the stylesheets via gulp less.

Custom Styles

Release

When you want to release Agent you'll need to do a release build. There are two batch files that can be used for this.

The first, and probably more commonly used, is package.bat. This will build the app in release mode and publish the results to the results/release/app directory. You can then point IIS to this directory to run your app or copy the contents elsewhere and host it there.

The second is release.bat. This will also build the app in release mode, but also runs unit tests, copies both the source and docs to results/release, and creates a zip file containing everything in results/release. This can be very helpful for creating snapshots of certain builds that can be backed up.

Logging

Logging is configured in the agent.log4net file. The defaults should be fine. The logging library Log4net is very flexible and has many configuration options

Customization

The Dovetail Agent Developer Training Wiki is a collection of developer training pages we've created to help out Dovetail customers wishing to customize this product. The wiki is a great resource for customizing Dovetail Agent.