Skip to content

Setting up a production deployment

Jump to bottom
River edited this page Sep 18, 2024 · 17 revisions

Example configuration referenced in this document is @ https://github.com/CoEDL/nyingarn-workspace/tree/master/production.

Architecture Schematic

Nyingarn architecture

Set up Auth providers

AAF Authentication

If you want to use AAF authentication you will need to email the following to support. Be sure to change the placeholders as required:

More information: https://support.aaf.edu.au/support/solutions/articles/19000096640-openid-connect-

* redirect url: https://{SERVICE NAME}/callback-oauth-login
* descriptive name: {DESCRIPTIVE NAME FOR THIS SERVICE - e.g. nyingarn platform}
* org name: {ORGANISATION - the AAF org this service will be associated to}
* purpose: production
* keybase account: {YOUR KEYBASE USERNAME - this is how they pass you secrets}

Google Authentication

Set up an OIDC via the google API Console. See https://developers.google.com/identity/protocols/oauth2/openid-connect

  • Go to the credentials tab and create a new OAuth 2.0 Client
  • Name as you wish: {SERVICE NAME} makes sense
  • Authorised Javascript Origins: https://{SERVICE NAME}
  • Authorised redirect URIs: https://{SERVICE NAME}/callback-oauth-login

Set up your DNS names

This guide assumes you are running all of the containers on a single host or in a cluster behind a single floating IP. Adjust accordingly if this is not the case.

Set up DNS records for:

  • workspace.nyingarn.net
  • repository.nyingarn.net

Setup your server to run the workspace and repository

For this example we'll assume you are setting up the workspace and repository to run from the same virtual machine, in the path /srv/nyingarn

  • copy ${GITHUB SOURCE CODE}/production/* -> /srv/nyingarn/*
  • copy ${GITHUB SOURCE CODE}/configuration/example-configuration.json to /srv/nyingarn/configuration/configuration.json and edit as required
  • copy ${GITHUB SOURCE CODE}/configuration/error-definitions.json to /srv/nyingarn/configuration/error-definitions.json
  • cp /srv/nyingarn/env /srv/nyingarn/.env and edit /srv/nyingarn/.env file - be sure to fill to replace all instances of {SET_THIS}
  • npm instal
  • copy ${GITHUB SOURCE CODE}/profiles -> /srv/nyingarn/profiles. These profiles describe the metadata interface for the application. You can edit these to suit your requirements - detailed documentation is available at https://github.com/describo/profiles#profile-documentation.

First time setup

You'll notice that there are 2 docker compose files. The file docker-compose-01-base-services.yml starts up the supporting services. When setting up the environment for the first time, run this compose file manually to start those services then do the following:

Set up postgres DB's

Exec into the db container and connect to the postgres service to setup the required databases.

> docker exec -it nyingarn-workspace_db-1 sh
> psql postgres
postgres=# create database nyingarn;
>

The postgres user is root and the password will be whatever you set in the .env file.

Loading describo data packs

Describo data packs are canned JSON-LD configuration users can inject into their metadata when editing items. You only need to do this once or if the data pack is updated (ensure the environment is running as this loads data into elastic search):

 node load-data-packs.js

Starting the environment

./workspace-init.sh start

Starts the base services and then after a brief pause, the workspace and repository containers.

Stopping the environment

./workspace-init.sh stop

Updating the environment

./workspace-init.sh update - updates all the containers
./workspace-init.sh restart

Before you run an update, you probably want to remove any old containers (docker images shows containers with TAG none) with:

docker rmi $(docker images | grep none | awk '{print $3}')

Then, after you do the upgrade if it has gone pear shaped, just set the latest tag on the old set of containers and restart the application.

Maintenance mode

If you need to go into maintenance mode do the following:

  • dump the letsencrypt certificates to file so they can be used by the maintenance web server:
    • docker compose -f docker-compose-dump-certs.yml up && docker compose -f docker-compose-dump-certs.yml stop && docker compose -f docker-compose-dump-certs.yml rm -f
    • Ctrl C to stop it - doesn't auto stop after dumping the certificates
  • ./workspace-init.sh mon: turns on maintenance mode (a simple html page is displayed at each url saying the sites are in maintenance)
  • ./workspace-init.sh moff: turn maintenance mode off and restart the application
Clone this wiki locally