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.

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
• Testing
  • Known Issues
• Deployment
  • Installing Heroku
  • Deploying to Heroku

Installation

Getting Started - via 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.

From the project root, build the containers:

docker-compose up -d --build

Install yarn dependencies

docker-compose run web yarn install

Create the database

docker-compose run web bundle exec rails db:create

Migrate the database

docker-compose run web bundle exec rails db:migrate

Seed the database

docker-compose run web bundle exec rails db:seed

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

Start the server!

docker-compose up

To access the homepage and login, go to localhost:3000. 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 Study ID: A1543457

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:seed

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.

Testing

We use Capybara and Rspec for our unit tests. Type and enter rspec in your terminal console to run the tests.

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