installation

Requirements

Roadmap is a Ruby on Rails application that requires the following:

Ruby >= 3.0
Rails >= 6.1
PostgreSQL >= 9.2 or MySQL >= 8.0
Yarn >= 1.22.4
Node.js 16.x for management of assets (DMPRoadmap is using the Rails asset pipeline with Webpacker)

Further details on how to install Ruby, please see their installation guide. If you are trying to setup a development environment. We highly recommend using a Ruby version manager like rbenv.

Further details on how to install the database server and create your first user and database. Be sure to follow the instructions for your particular environment.

PostgreSQL documentation:
- Install: https://wiki.postgresql.org/wiki/Detailed_installation_guides
- Create a user: https://www.postgresql.org/docs/current/static/app-createuser.html
- Create the database: https://www.postgresql.org/docs/9.6/static/tutorial-createdb.html
MySQL documentation:
- Install: http://dev.mysql.com/downloads/mysql/
- Create a user: https://dev.mysql.com/doc/refman/8.0/en/create-user.html

You may also find the following resources useful:

The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html
Ruby on Rails Tutorial Book: http://www.railstutorial.org/

Installation

Fork the repository and then clone it

We advise that you create a fork of this repository where you can store your local customization and branding. Then clone that fork instead of cloning this repository directly.

Navigate to the cloned repository and run the either ruby bin/setup mysql or ruby bin/setup postgres depending on which DB you have installed (assuming you have Ruby, Node and either MSQL or Postgresql installed)

The installation will walk you through the process of setting up your DMPTool application. It will:

Install bundler
Install all of the Ruby gem dependencies
Install all of the JS dependencies
Copies over a sample .env file and opens it in an editor window (vim for OSX and Linux). You should update the entries, and then save and close in order for the setup script to continue (to generate new secrets, you can run rails secret in a separate tab/window)
Copies over the sample encrypted Rails credentials file and opens an editor window (vim for OSX and linux). You should update the entries, and then save and close in order for the setup script to continue (to generate new secrets, you can run rails secret in a separate tab/window)
Builds the database
Populates the licenses table
Populates the metadata_standards table
Populates the research_domains table
Clears any existing Rails cache and restarts the server (if applicable)
Provides instructions on how to populate the repositories and registry_orgs tables

We highly recommend that you review the sample files mentioned above once the setup script has completed. Make any changes you find necessary (e.g. administrator email).

The DMPTool uses the AnywayConfig gem to help manage configuration settings. This gem loads configuration options in a cascading hierarchy. For example a value in config/dmproadmap.yml will be overwritten if the same value also exists in the Rails credentials file. The gem uses the following hierarchy (where values are overridden left to right ... ENV always takes precedence): config/dmproadmap.yml -> credentials.yml.enc -> AWS SSM (if applicable) -> ENV (or .env file)

This allows us to set default values and then override them for a specific environment.

If you need help determining where a particular configuration option is being set, you can run bin/rails config:trace which will return all of the config settings along with their location. For example:

  {"server_host"=>
    {:value=>"http://localhost:3000", :source=>{:type=>:env, :key=>"DMPROADMAP_SERVER_HOST"}},
 "port"=>
    {:value=>"3000", :source=>{:type=>:yml, :path=>"config/dmproadmap.yml"}},

If you need to edit your credentials file after the setup script finishes, you can run EDITOR=vim bin/rails credentials:edit

Once you're happy with the configuration files, you can start the Rails server and verify that the application is up and running:

Run bin/dev to start the application
Visit http://localhost:3000/ in a browser to verify that the site is working
Log in as the default super admin account: using the email+password option (default is: 'super_admin@example.com'+'password123')
Go to the 'Edit Profile' page and change your email and password to something more secure

Post Installation

You should perform the following tasks prior to deploying the system on a server that is accessible to the web:

Delete any other default users included in the seeds.rb file or at least change their passwords.
Update the site's Branding.

Please replace the app/views/branded files with your own copies. The DMPTool, UC3, CDL, DCC and DMPRoadmap logos and the DMPTool, DMPRoadmap names are for use by those organizations / applications.

Designate/create a default template. If a user creates a plan and specifies no research organization and no funder (or a combination that results in no published templates) then their plan is created using a default template. You must define your default template in the DB by setting templates.is_default equal to true.

Troubleshooting

If the installation process fails after the 'Preparing database' step, you will need to run rails db:drop before running the setup script again!

Running with Docker

Uses docker compose (like docker compose build or docker compose up)
Will need a working .env file with correct secrets, etc.
I got frequent crashes from Docker Desktop and my servers kept going away. For me this was resolved by updating to the latest version. Another team member had problems starting and resolved with by "clearing the docker space"
If getting "invalid password" while trying to start the docker containers under docker compose, edit the .env file and comment out database settings that might conflict with the ones set in the docker compose files. I had to comment out DMPROADMAP_DATABASE_USERNAME and DMPROADMAP_DATABASE_PASSWORD lines by putting a # in front of them to stop them from overriding the Docker Compose settings.
I had additional problems getting the usual database migrations to run and it giving errors about duplicate table names (I believe the errors are related to the background job Gem). To fix those problems I had to follow these steps:

docker compose run --rm -it dmptool bash  # you must do this way instead of exec since the container doesn't start and stay running

# you should now be in a bash shell and run these commands
rails db:drop
rails db:create
rails db:schema:load

I was able to do docker compose up and get a running server that accessed the database (from Docker) and ran on localhost:3000 .

I was also able to connect to the database running in docker from a normal db client using localhost, port 3306, database dmp and the rest of the settings shown in the docker-compose.yml file (can be helpful for troubleshooting and seeing db contents).