Australian Genomics Health Alliance CTRL Project

The AGHA(Australian Genomics Health Alliance) Dynamic Consent project is building a web based platform that will manage consent for genomic testing, and allow participants to manage their preferences around how and where their test results are received and shared.

CTRL is distributed under the terms of the MIT licence.

Table of Contents

• Installation
  • Getting Started - via Docker (recommended)
  • Getting Started - Standard
  • Creating an Admin account
• Guides
  • Strategies for Multi-Language Support
  • Two Factor Authentication integration
  • Password security and user validation
  • Integration of a Content Management System
  • Resetting your environment
• Testing
  • Known Issues
• Deployment
  • Installing Heroku
  • Deploying to Heroku
• Environment Variables

Installation

Starting from release v1.0.0 CTRL follows the Gitflow model. This means active development happens on the devel branch, while the main branch only contains official releases, tagged with their version number. Depending on your needs please check out the appropriate branch and tag.

Getting Started - via Make and Docker (recommended)

There are two ways to get started, via Docker or the standard way. We recommend using Docker to minimise operating system installation issues. To install via Docker, first make sure that Docker is installed on your machine, then follow these steps.

There is a makefile (requires Gnu Make to be installed), which makes it easier to get a development environment up and running.

Decode or create config/credentials.yml

If you have been given the master.key file, move it to config/master.key. This decodes the config/credentials.yml.enc file which should already be present in this repo. Otherwise, you can create your own config/master.key and config/credentials.yml.env files by deleting config/credentials.yml.enc then running:

# Generate new keys and salts. Prints to std out.
make generate-keys

# Open config/credentials file using:
make edit-credentials

# Paste the output of the first command into your config/credentials.yml file

In the editor which appears append admin email and password for the development environment admin portal. It would look similar to below:

# aws:
#   access_key_id: 123
#   secret_access_key: 345

# Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
secret_key_base: <auto-generated-key-base>

active_record_encryption:
  key_derivation_salt: <auto-generated-key-derivation-salt>
  deterministic_key: <auto-generated-key>
  primary_key: <auto-generated-primary-key>

development:
  mailer:
    email: [email protected]
    password: tester123

Then save the file and exit the editor.

When deploying a production instance, you will also want to include a production: section in the above yaml file, following the same format as the development: section.

Note: config/master.key and config/credentials.yml.enc are generated or edited within the docker, they may have different file permissions to the other files in the repo. If you have an issue: error checking context: no permission to read from '/home/<user>/<dir>/CTRL/config/master.key then you may have to change ownership:

sudo chown <user>:<group> config/master.key config/credentials.yml.enc

Start up development environment

make up

This will:

• build containers,
• install Yarn dependencies,
• create the database,
• migrate the database,
• seed the database,
• and, start the rails, selenium, smtp and web servers.

After seeding, an Admin user is created with the following credentials:

email: [email protected]
password: tester123

As well as a normal User with the following credentials:

email: [email protected]
password: tester123

To access the homepage and login, go to localhost:3000. When you login, you will be sent a one-time password (OTP) via email. An in-memory SMTP server runs at localhost:1025. View your OTP by visiting the SMTP server's web interface at localhost:8025.

To access the Active Admin interface and the survey builder, go to localhost:3000/admin.

If you want to try and register a new user, you can append with the following Participant ID: A1543458

Other Make commands

Each of the steps above has a separete make command (e.g. make .docker; see makefile for more details). These steps touch an empty file to signify that that step was successful and doesn't need to be re-run. Run make clean to break the cache and delete all these .<step> files.

Other commands are:

# Stop servers
make down

# Remove docker volume (persistent database data)
make rm-volume

# Run Ruby tests
make tests

# Open Rails REPL with application data loaded
make console

Getting Started - Standard

Make sure you have Ruby 2.5.3 by doing ruby -v from your console.

It is recommended to have Node v14.16.1 (you can check the node version by doing node -v from your console). Also do a yarn -v to check if you have yarn installed. If it isn't installed then do npm install --global yarn.

Install gems via bundler

bundle install

Create and build the database.

rails db:create
rails db:migrate

Install yarn dependencies

yarn install

Seed the database

rails db:reset

Start the server! rails s

Creating an Admin account

To access the Active Admin interface and the survey builder, create an admin account by opening up the server console:

rails c

and create an AdminUser

AdminUser.create(email: '[email protected]', password: 'yourpassword')

then you can access the admin interface by going to localhost:3000/admin and typing in your credentials. Make sure to checkout the Documentation page from the navigation bar.

Guides

Strategies for Multi-Language Support

Multi-language support (aka internationalization) has been implemented within the project.

To see the English locale, navigate to config/locales/en.yml

To add the Chinese locale for example, create another yml file config/locales/ch.yml and imitate the structure of en.yml.

For example,

For the hello_world line in the English locale (en.yml):

en:
  hello_world: Hello World!

Should correspond to an equivalent translated line in the the Chinese locale (ch.yml):

ch:
  hello_world: 你好世界

The Survey form builder does not currently support internationalization. However, this could be implmented by creating separate fields for each table that displays text.

For example, if we want to support Chinese questions, then we can add question_chinese and description_chinese columns to the Question table and modify the Vue components to show the Chinese columns for the Chinese version and show the english columns for the English version.

Two Factor Authentication integration

We recommend using Devise-Two-Factor. Devise-Two-Factor is a minimalist extension to Devise which offers support for two-factor authentication, through the TOTP scheme. It integrates easily with two-factor applications like Google Authenticator and Authy.

Add Devise-Two-Factor to your Gemfile with:

gem 'devise-two-factor'

Next, since Devise-Two-Factor encrypts its secrets before storing them in the database, you'll need to generate an encryption key, and store it in an environment variable of your choice. Set the encryption key in the model that uses Devise:

  devise :two_factor_authenticatable,
         :otp_secret_encryption_key => ENV['YOUR_ENCRYPTION_KEY_HERE']

Finally, you can automate all of the required setup by simply running:

rails generate devise_two_factor user ENVIRONMENT_VARIABLE

ENVIRONMENT_VARIABLE is the name of the variable you're storing your encryption key in.

Remember to apply the new migration.

bundle exec rake db:migrate

It also adds the :two_factor_authenticatable directive to the user model, and sets up your encryption key. If present, it will remove :database_authenticatable from the model, as the two strategies are incompatible. Lastly, the generator will add a Warden config block to your Devise initializer, which enables the strategies required for two-factor authentication.

From the Application Controller:

before_action :configure_permitted_parameters, if: :devise_controller?

...

protected

def configure_permitted_parameters
  devise_parameter_sanitizer.permit(:sign_in, keys: [:otp_attempt])
end

After running the generator, verify that :database_authenticatable is not being loaded by your model. The generator will try to remove it, but if you have a non-standard Devise setup, this step may fail. Loading both :database_authenticatable and :two_factor_authenticatable in a model will allow users to bypass two-factor authenticatable due to the way Warden handles cascading strategies.

Password security and user validation

2FA should be sufficient for securing user sessions, but passwords should at least be 8 characters long. Special characters should not be a requirement if the user has 2FA setup during registration.

Integration of a Content Management System

We recommend using Refinery. Refinery CMS is in our view one of the best Ruby on Rails content management systems for many years now. Released as open-source in 2009, Refinery uses the ‘Rails way’ wherever possible but also allows the flexibility to design your website in your own way.

To integrate Refinery.

Open up your Gemfile and add the latest version (a later version than the one shown below may exist):

gem 'refinerycms', '~> 3.0.0'

Refinery doesn't ship with authentication by default, but you will need to add it unless you want every visitor to be automatically logged in.

If you want to use the default authentication system:

gem 'refinerycms-authentication-devise', '~> 1.0'

Now, to install the gems, run:

bundle install

Generating support files and migrations, and preparing the database.

Generating Refinery on top of an existing application is marginally more complicated than it was before, but it's still relatively straightforward:

rails generate refinery:cms --fresh-installation

This command does a few things:

• It creates config/initializers/refinery/ and copies over all the required initializers from Refinery

• It copies all Refinery migrations to your apps migration folder and runs these migrations, and adds the seed data to your database

• It injects Refinery's mounting line into your config/routes.rb file

• It inserts require refinery/formatting and require refinery/theme lines in your apps application.css file

• After this, you should be all set. Don't forget to revisit the initializers in config/initializers/refinery/ to customize your experience.

Mounting to a directory other than root

It is possible to mount Refinery to a subfolder. To do this, simply change the following setting in config/initializers/refinery/core.rb.

config.mounted_path = "/subfolder"

After starting your rails server and navigating to localhost:3000/subfolder, you should see a dummy home page.

You can create the initial admin user by visiting localhost:3000/subfolder/refinery.

Resetting your environment

# Stop all running containers mentioned in the docker-compose.yml file. Note
# that if services were removed from the docker-compose.yml file between running
# `docker compose up` and `docker compose down`, those services will not be
# stopped.
make down

# Remove CTRL docker volume
make rm-volume

# Remove, for example, `node_modules/`, `public/packs/`, `tmp/cache/`.
make clean

Testing

We use Capybara and Rspec for our unit tests.

Before running the tests, you might want to run some or all of the commands in the resetting your environment section. (If in doubt, run them all!)

Make sure you also follow the Getting Started - via Docker (recommended) section. However, note that any step containing --env-file=.env.dev, should have it replaced by --env-file=.env.test.

With that done, you can run the cucumber tests in docker using the following command:

docker compose --env-file=.env.test run web bundle exec rake cucumber

Similarly, to run the rspec tests:

docker compose --env-file=.env.test run web bundle exec rspec

We also use playwright to test active admin. The .github/workflows/pipeline.yml file is the source of truth for how to run those tests. But the commands are copied here for your convenience:

docker compose --env-file=.env.playwright run web yarn install
docker compose --env-file=.env.playwright run web bundle exec rails db:create
docker compose --env-file=.env.playwright run web bundle exec rails db:migrate
docker compose --env-file=.env.playwright run web bundle exec rails db:reset
docker compose --env-file=.env.playwright up -d

# Wait until the web server is ready
while ! curl -s http://localhost:3000 >/dev/null
do
  echo web server not ready, retrying in 5 seconds...
  sleep 5
done

docker compose --env-file=.env.playwright run playwright npx playwright test --trace on

You can update the snapshots using npx playwright test too, by deleting the existing snapshots before running the command.

Known Issues

For MacOS Catalina and Big Sur

If you encounter this error while bundling:

An error occurred while installing libv8 (3.16.14.19), and Bundler
cannot continue.
Make sure that `gem install libv8 -v '3.16.14.19' --source
'https://rubygems.org/'` succeeds before bundling.

Update your brew installation.

brew install [email protected]
bundle config build.libv8 --with-system-v8
bundle config build.therubyracer --with-v8-dir=$(brew --prefix [email protected])
bundle

Source

Deployment

Installing Heroku

Make sure you have installed the Heroku CLI

Login with your Heroku credentials using heroku login.

Add the Heroku git remote using heroku git:remote -a agha.

Deploying to Heroku

git add .
git commit -m [Your message](https://github.com/erlang/otp/wiki/writing-good-commit-messages)
git push heroku master

Environment Variables

There are .env.X files containing environment variables that are passed to docker compose:

• CTRL_ADMIN_EMAIL - This is the address from which emails are sent to study participants. It's also the address to which emails are sent when a study participant uses the "Contact Us" form.
• RAILS_ENV - This variable sets various Rails settings.
• DATABASE_NAME
• DATABASE_USER
• DATABASE_PASSWORD
• DATABASE_HOST
• REDCAP_TOKEN - API token for REDCap api
• REDCAP_API_URL - URL for REDCap API
• REDCAP_CONNECTION_ENABLED - Whether data should be forwarded to REDCap. Valid values are true and false. Defaults to false.
• OTP_ENABLED - Whether or not login should be permitted without entering a valid OTP. Valid values are true and false. Defaults to true.
• CADDYFILE_LOCATION - This variable is required to be set for the docker-compose to be evaluated correctly. It currently points to an example Caddyfile. No changes to this file are required for local development.

In the makefile there are options to provide further configuration via environment variables. These are used for deploying CTRL and do not need to be adjusted for local development. Variables specified at the top of the makefile can be overridden by passing them in when make is called. For example, to run docker compose commands with the .env.test file, run make ENV=test up.

In addition the variables below can be passed in from environment variables (e.g. COMPOSE_PROFILES=test make test):

• COMPOSE_PROFILES - This can remain unset for local development. Use test for testing, deploy for deployment.
• ALLOWED_HOSTS - This can remain unset for local development. It is only required for deployment.
• IMAGE_REGISTRY - This can remain unset for local development. If a registry is provided, it must end with a trailing /.
• RAILS_MASTER_KEY - This can remain unset for local development. Rails will default to using the file in config/master.key.

Continuous integration

There are two Github Action pipelines that run on each push:

• .github/workflows/pipeline.yml - Runs all the tests
• .github/workflows/docker_build.yml - Checks if there has been a change in the dockerfile. If there have been changes it then builds and pushes an image.