HykuAddons: Setup Guide

Setup HykuAddons

Deleting an existing installation

If HykuAddons already exists on your system and you want to start fresh, you can do the following.

DANGER: This will remove all containers, images and data.

docker-compose down
docker system prune
docker rm -f (docker ps -a -q)
docker volume rm (docker volume ls -q)

From a clean system

Add the host file entries

In order to access the super-admin host as well as the normal tenants, you will need to add the following to your /etc/hosts. This will depend on what your chosen tenants cname's are, however an example host file might look like this:

# sudo nano /etc/hosts

127.0.0.1       localhost
::1             localhost

# Hyku
127.0.0.1       hyku.docker # Required for the super admin to work
127.0.0.1       repo.hyku.docker # One of the tenants for this instantion
127.0.0.1       anschutz.hyku.docker # Another tenant

Please note, you will still have to use the :3000 port to access the tenants in development, as you would for any normal Rails app: http://hyku.docker:3000/

Start the containers

HykuAddons is contained within a series of Docker containers, controlled via a docker-compose.yml file. To start the application you can use the following:

docker-compose up

The first time you run the application, this will build the images on your host machine and when complete, start the services required for the system to run.

If you want to use byebug, you must start the containers with the web container set to work in the background, then use docker attach container_name.

docker-compose up -d; docker attach hyku_addons_web_1

To enter bash inside container:

docker-compose exec web /bin/bash

Creating a Super Admin

To access the Tenant account settings you will need to create a "Super Admin" user. This can be done from the terminal:

bundle exec rails app:hyku_addons:superadmin:create

Create an Tenant (Account)

Hyku uses Tenants to seperate the content entered into the admin. This is done by checking the subdomain of the URL and running the AccountElevator.

To create a Tenant, go to the following URL and when asked for a repository cname, use the one previously added to your Host file: http://hyku.docker:3000/proprietor/accounts?locale=en

You can then create an Admin (not a super admin, just an admin for an individual tenant) when asked.

Via console

It is possible to create an account via a Rake task, which saves having to access the Super Admin section in your browser.

Goto the rails console:

docker-compose exec web rails console

Create a random string that will be used for the new tenants UUID:

SecureRandom.uuid

Copy the output to your clipboard for use in the rake task, and using the UUID and your email address as appropriate, run the following:

# bundle exec rails "app:hyku:account:create[Name, Copied UUID, CNAME, Email]"
docker-compose exec web bundle exec rails "app:hyku:account:create[test, aa070467-09d7-4b13-bb5a-7192f900e6c3, test.hyku.docker, paul.danelli+admin@ubiquitypress.com]"

Activate user

After you create your user you will need to be activate them via the console as invitations are not sent in development:

docker-compose exec web bundle exec rails console

AccountElevator.switch!(Account.first.cname)

# NOTE: The password is being set again as it doesn't seem to be correct when trying to login
User.first.update(invitation_token: nil, invitation_accepted_at: DateTime.current, password: 'test1234')

Accessing works

When you want to access the tenant works via the command line, you will need to set the Account via the AccountElevator before hand.

# I'm using the first account cname here as I just have a single tenant, but this could be any account cname
AccountElevator.switch!(Account.first.cname)

Hyku/Hyrax uses ActiveFedora as a shim to maintain ActiveRecord functionality whilst accessing the data stored in Fedora. You can use most ActiveRecord methods, but some might not maintain 100% parity.

For instance, if you wanted to access a GenericWork, you could use GenericWork.find("<uuid>"), or ActiveFedora::Base.find("<uuid>"). The later of the commands will work with any work type and return an instance of the correct work type, where as the former will only look for GenericWork type works.