Skip to content

Installation

Jump to bottom
Brian Riley edited this page May 25, 2022 · 43 revisions

Requirements

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

  • Ruby >= 2.6.3
  • Bundler >= 2.2
  • Rails >= 5.2
  • PostgreSQL >= 9.2 or MySQL >= 5.5
  • Yarn 1.22.4
  • Node.js 10.x for management of assets (DMPRoadmap is using the Rails asset pipeline with Webpacker)
  • ImageMagick used by the Dragonfly gem to manage logos

Further details on how to install Ruby on Rails applications are available from the Ruby on Rails site:

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.

You may also find the following resources useful:

Installation

Install Dependencies (see above for supported versions).

Ruby We recommend using rbenv or rvm (at least in development) to help you manage and install Ruby versions.

Bundler See the latest bundler version in the Gemfile.lock tail -n 2 Gemfile.lock. Then run `gem install bundler -v[version nbr]

Node See the node documentation for how to install/manage node on your system.

Yarn See the yarn documentation for instructions on how to install it. Note the current node version, node -v, when reading the installation instructions.

WkHTMLToPDF This library will be auto-installed when you build the application bundle.

Fork the repository and then clone it onto your server

Fork this repository by clicking the 'Fork' button in the top right of this page and then clone the repository.

git clone https://github.com/[your organization]/roadmap.git

cd roadmap

Create your config files from the examples:

  • Run cp config/database.yaml.sample config/database.yaml
  • Run cp config/initializers/contact_us.rb.example config/initializers/contact_us.rb
  • Run cp config/initializers/wicked_pdf.rb.example config/initializers/wicked_pdf.rb

Review the following configuration files and adjust accordingly for your installation:

  • config/initializers/_dmproadmap.rb
  • config/initializers/contact_us.rb
  • config/database.yaml

We highly recommend that you change the DB username and password in your config/database.yaml to use environment variables such as ENV['DB_USERNAME'] and ENV['DB_PASSWORD']

Feel free to replace any values in the config files to use environment variables to suit your deployment and security needs.

Define your environment variables for the database

There are numerous approaches to manage environment variables and most institutions will have guidelines and best practices to follow. To get started, in your development environment, you can use the DotEnv gem which is already installed. To do that, simple create the file and then add your environment variable to it touch ./.env. You can also simply set these variable by running export DB_ADAPTER=postgres or adding that line to your shell profile file (e.g. ~/.bash_profile or ~/.zshrc, etc.)

The following environment variable must be defined:

  • DB_ADAPTER (e.g. mysql2, postgres, etc.)
  • DB_USERNAME (only if you have updated the config/database.yaml to use this)
  • DB_PASSWORD (only if you have updated the config/database.yaml to use this)
  • Any other environment variables you may have added to the config files above

Create the Rails credentials file and master key

Rails 5.x requires an encrypted credentials file that you can use to store sensitive information. To generate both of these files you should run EDITOR=[my_fab_editor] rails credentials:edit where [my_fab_editor] is your preferred text editor like 'vim'.

This command will open the editor of your choice. You will then need to copy the text bellow with your correct info and then save it:

database:
  host: localhost
  
# Generate your own pepper by running `rails secret`
devise_pepper: ABCDEFG12345

# Generate your own secret by running `rails secret`
dragonfly_secret: ABCDEFG12345

# This is only required if you're going to store institution logos in an S3 bucket (the default is to store these on disk)
dragonfly:
  host: my-s3-bucket-host
  bucket: my-s3-bucket-name

# Sign up for ORCID credentials if you want your users to be able to connect their ORCID accounts (the user's ORCID 
# will be included in the PDF download and API calls for the user's DMPs):
#    https://orcid.org
orcid:
  # Sandbox
  client_id: ABCDEFG12345
  client_secret: ZYXWVU98765
  sandbox: true

# Sign up for Google's reCaptcha v2 if you want to enable reCaptcha for the contact us and account creation pages:
#    https://developers.google.com/recaptcha/docs/display
recaptcha:
  site_key: ABCDEFG12345
  secret_key: ZYXWVU98765

# Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
# Just use the one generated for you when the file is created or run `rails secret`
secret_key_base: ZYXWV98765

Create your database

To create your databases run the following commands from the project directory:

  • bin/rails db:create - this will create both the 'roadmap' and 'roadmap_test' databases
  • bin/rails db:schema:load - this will build the tables for the roadmap database
  • bin/rails db:seed - this will populate the core tables with enough data to get started. Note that it creates an administrator account for you with the login of: email=super_admin@example.com, password=password123 (be sure to change the email and password for this account!).

NOTE: If you receive a "I18n::InvalidLocale: "en-GB" is not a valid locale" error message when running db:seed, you will need to manually add this entry to the database by running INSERT INTO languages (abbreviation, name, default_language) VALUES ('en-GB', 'English (GB)', true); and comment out lines 91-94 in the db/seeds.rb file.

Install the application's gem and JS dependencies

You can now install all of the application's dependencies.

bundle install

yarn install

Once complete, you should add the location of the WKHTMLtoPDF executable to your environment variables. Run which wkhtmltopdf and then set your WICKED_PDF_PATH variable to this location (e.g. on OSX using rbenv to manage Ruby /Users/me/.rbenv/shims/wkhtmltopdf).

Start the application and verify that the site is running properly

Run rails s to start the application.

Go to http://localhost:3000 in your browser. This should display the homepage. Login as the default administrator: 'super_admin@example.com' - 'password123' and make sure you are able to authenticate and see the 'My Dashboard' page.

At this point you should click on the user name in the upper right of the page and change the password and email to something more appropriate. Once you've done this, you can navigate to the 'Admin -> Users' page to see the various default accounts that were created. It is worthwhile for you to login as an 'Organizational Administrator' and a regular 'User' role to see what the system looks like for each of these users (the default passwords are all 'password123'). You should then either delete these accounts or change the passwords.

Post Installation

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

  • Delete the users included in the seeds.rb file (e.g. super_admin@example.com) or at least change their passwords.

  • Make sure you change Rails.application.routes.default_url_options[:host] = "example.org" (line 100) at `config/environments/production.rb

  • Update the site's Branding.

  • 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.

Table of Contents

Clone this wiki locally