Skip to content

Installation

Jump to bottom
Brian Riley edited this page Jun 14, 2023 · 43 revisions

Requirements

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

  • Ruby >= 3.0.4
  • Bundler >= 2.4
  • Rails >= 6
  • PostgreSQL >= 9.2 or MySQL >= 5.5
  • Yarn 1.22
  • Node.js 16.x
  • 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: https://rubyonrails.org

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

Core system libraries The following libraries are typically already installed for most linux and OSX users. It is worth verifying though that you have the following installed:

autoconf, automake, gawk, g++, git, imagemagick, libffi-dev, libgdbm-dev, libreadline-dev, libssl-dev, libtool, libyaml-dev, shared-mime-info

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 C library will be auto-installed when you build the application bundle.

OSX environment setup

We recommend using the Homebrew package manager to build your environment. Once home-brew is installed you should install the following:

  • brew install node
  • brew install yarn
  • brew install [mysql or postgres]
  • brew install shared-mime-info
  • brew install rbenv ruby-build (or RVM if you prefer that Ruby version manager)

Install Ruby 3.0.4 rbenv install 3.0.4 or rvm install 3.0.4 depending on which Ruby version manager you are using

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

Install Ruby 3.0 and bundler 2.4

Then ensure that you are on the correct Ruby version ruby -v. You are using rbenv you should run rbenv local 3.0.4 for rvm you can run rvm use 3.0.4

Then install bundler: gem install bundler -v 2.4

Run the Setup script

Run the setup script for your database type. Either ruby bin/setup mysql or ruby bin/setup postgres

The setup script will do the following:

  • Install all of the Ruby gem and JS dependencies
  • Create a config/database.yml file
  • Create a config/initializers/contact_us.rb file
  • Create a config/initializers/wicked_pdf.rb file
  • Create and open a .env file to store Environment variables for your development environment. You should update the values when the editor opens (particularly your DB credentials)
  • Create and open the Rails credentials file. You should review and update the values when the editor opens
  • Create and build the DB structures
  • Populate the licenses, metadata_standards and research_domains lookup tables

Once it completes, we highly recommend that you populate the Repositories table, but this can take in excess of 10 minutes so we do not include it as part of the setup.rb file: bin/rails external_api:load_re3data_repos

We also recommend that you review the contact_us.rb and wicked_pdf.rb initializer files that the setup.rb script created for you. Adjust them as needed. If you want to know the location of your wkhtmltopdf executable just run which wkhtmltopdf (on OSX or linux)

We recommend that you review all of the config/initializer/ files (_dmproadmap.yml in particular) and replace any values to suit your deployment and security needs.

Seed your database if this is a completely new installation

Run bin/rails db:seed to populate the database with example users, templates, guidance, etc. The user names and passwords can be found in db/seed.rb. Be sure to change the email and passwords for these users once you've seeded the DB!

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.

Build the assets

Run bin/rails assets:precompile to do an initial build of the stylesheet, font, image and JS assets

Start the Rails application

Run bin/dev in development mode (the old bin/rails s will not pick up changes you make to asset files any longer) and bin/puma -C config/puma.rb -p 80 when running on a server

Navigate to http://localhost:3000 in your browser. This should display the homepage. If you've just seeded the DB then login as the system 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.

Modifying your environment

Updating your environment variables

You can update your environment variables at any time by editing the .env file. You need to restart the Rails server afterward.

Note that you can use standard environment variables instead of the .env file if you prefer.

If you want to generate any random keys to use in this file, you can run rails secret.

Updating your Ruby Gem and JS dependencies

We endeavor to release a new version of the DMPRoadmap codebase every other month. We highly recommend that you keep an eye on any security vulnerability alerts that GitHub's dependabot issues. If you want to update you dependencies (recommended) between releases, you can run bin/rails update:all

Updating the Rails credentials file and master key

Rails 6 requires an encrypted credentials file that you can use to store sensitive information. To edit the information in this file you can run EDITOR=[my_fav_editor] rails credentials:edit where [my_fav_editor] is your preferred text editor like 'vim'.

If you want to generate any random keys to use in this file, you can run rails secret.

Issues

If you have trouble installing the system, please check our Troubleshooting guide for a list of common issues. If you don't see your issue there, please create an issue in this repository to let us know

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

  • Make sure you defined the DMPROADMAP_HOST environment variable to match the domain of your site. Rails restricts activity to a whitelist of valid domains/

  • 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