Deployment

Setup environment

  • Clone the repository on an NHS server git clone https://github.com/HYLODE/HyUi.git.
  • Configure your .env variables using .env.example as a template.

Docker permissions

If setting up a ‘shared’ deployment (a named dev deployment for example), ensure that permissions are set correctly on the directory to allow git pulls and docker builds by multiple users. On the deployment GAEs users are assigned to the docker group, so permissions can be changed as follows

cd /path/to/git/repository

# Give group access to any new local modifications to the repo
git init --shared=group

# Give the group access to all existing items in the repository
chown -R :docker "$PWD"
chmod -R g+swX "$PWD"

This is expected to work optimally with a freshly cloned git repository. If working with an existing local repository containing multiple changes, docker builds or git pull/pushes may throw permissions errors as another user may have set restrictive permissions on a file crucial for either process. In many cases it is simplest to clone the repository from scratch and perform the steps above.

As an alternative if the above is not working, you should try

chgrp -R docker /path/to/repository
chmod -R g+rws /path/to/repository
setfacl -R -m d:g::rwX /path/to/repository

Run the Docker Compose services

In the base directory (containing compose.yml)

docker compose --project-name [project name] up --build

Ensure that you use a unique name for your [project name]. The production service should be named hyui-prod.

Initialise services

This should be done the first time you stand up the services. It populates the Baserow database with the tables and static data required to run the rest of the HyUi services. You will also need to do this when you update your configuration (loading) data for Baserow. That is, you should consider Baserow as a temporary scratch pad, and mapping changes etc. will live in code (see initialise/src/initialise/bed_defaults.json). Before you ‘redeploy’, you must manually delete the tables from Baserow.

You may also want to register the license for the self hosted version. To do this, check that the ‘instance id’ available on the admin pages is copied from the self-hosted version to the web / hosted version; then regenerate the license key on the hosted version; then copy that license key back to the self-hosted; then add the user to the ‘seat’ created by that registered version. This enables ‘export to JSON’ functionality etc.

./bin/initialise.sh --operation baserow

Recreating defaults in baserow

To be used when updating an existing instance of baserow adjustments to default tables

  • loads fresh versions of the default tables including
    • departments
./bin/initialise.sh --operation recreate_defaults

Stop And Remove Docker Containers

docker compose --project-name [project name] down

Tips and Tricks

Debugging from within the NHS network

Sometimes it can be difficult to debug your staging services when they are deployed via docker.

You can log into the hyui-web or hyui-api services from a terminal within the HyUi directory using the following:

docker compose --project-name [project name] exec web bash
docker compose --project-name [project name] exec api bash

You can then change the code using vim or open a python console and debug from there.

Remember you will then need to manually make the same changes outside the docker bash terminal!

It may be useful to edit the docker/api/Dockerfile or docker/web/Dockerfile and add a --reload flag to the ENTRYPOINT so that code changes from within the container are reloaded automatically. ENTRYPOINT ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--reload"] instead of ENTRYPOINT ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--reload"].

If you prefer not to use vim then Visual Studio can SSH into the running containers somehow.