Running cardiacmodelling/ap-nimbus-client-direct

See also

Offical docker run documentation.

Note

client-direct requires a number of configuration property values / Environment Variables to be assigned (e.g. for database connectivity) before it will start.

See later Prerequisites section for a more detailed running explanation.

docker run -d --name name-client --net ap-nimbus-network --restart always -v volume-client:/opt/django/media -p 4240:80 --env-file env cardiacmodelling/ap-nimbus-client-direct:<version>

Where:

  1. ap-nimbus-network is a docker network.
  2. volume-client is a docker volume.
  3. env A file, e.g. docker/env, containing Environment Variables (which could also be passed as command line switches).
  4. <version> is a valid dockerhub tag (as available at https://hub.docker.com/r/cardiacmodelling/ap-nimbus-client-direct).

Note

If you want to run cardiacmodelling/ap-nimbus-client-direct in “developer” mode (e.g. using client/config/develop_settings.py) then add the -d DJANGO_SETTINGS_MODULE=config.develop_settings to the docker run command.

In Docker parlance, the -p 4240:80 will “publish” or “expose” the container port 80 to port 4240 on the host machine by means of fiddling with the firewall (see cardiacmodelling/ap-nimbus-client-direct for a bit more information).

Environment Variables

The environment variables used by the docker components for AP-Nimbus are listed below. They are listed as VAR=VALUE pairs (without any spaces).

Note

A template environment var file is provided in the repository, e.g. docker/env.

DJANGO_SECRET_KEY=
Please pick a secret key. A long random string is ideal.
DJANGO_SUPERUSER_EMAIL=
DJANGO_SUPERUSER_FULLNAME=
DJANGO_SUPERUSER_PASSWORD=
DJANGO_SUPERUSER_INSTITUTION=
Please assign the email, full name, password and institution of the user who will be the Django superuser on application initialisation.
After initialisation, if you wish to change the identity of the Django superuser, you have the choice to either :
1. Create a new user (i.e. someone whose email does not already exist in the application), by specifying a completely new email, full name, password and institution in the above env vars, or,
2. Use the identity of an existing user (identified by email, case sensitive), who will have their existing full name, password and institution overwritten with the values specified in the above env vars.
(In both cases, you will need to restart cardiacmodelling/ap-nimbus-client-direct for the changes to become effective.)

Warning

On system restart, a Django superuser will exist as defined by whatever data is specified in the SUPERUSER environment vars. See create_admin.py, which gets run on each restart.
If the Django superuser (as defined by DJANGO_SUPERUSER_EMAIL) needs to update their email address, they must do so first via the UI “Account” option, and then via a corresponding update to DJANGO_SUPERUSER_EMAIL (any other details to update must be done through SUPERUSER environment vars ONLY), and then restart cardiacmodelling/ap-nimbus-client-direct.

subfolder=
This is intended for situations where the client is running behind a proxy, e.g. Apache, and a URL path is used to direct proxying requests, e.g. the ActionPotentialPortal in https://cardiac.nottingham.ac.uk/ActionPotentialPortal.
This variable will ensure the urls used will correctly contain the relevant path.
ALLOWED_HOSTS=
Allowed hosts Django should be allowed to serve web pages for (comma separated).
In production this should probably be set to the public facing hostname of your webpage to prevent security issues such as web cache poisoning.
If left empty any host will be allowed ('*')
smtp_server=
Set the SMTP server used to send emails from.
django_email_from_addr=
This email address is used as the From: address in any emails sent by the client.
#PYTHONUNBUFFERED=1
POSTGRES_PASSWORD=
PGPASSWORD=
PGDATABASE=django_ap_nimbus_client
PGPORT=5432
PGHOST=name-postgres
PGUSER=postgres
Database variables.
Values above assume you are running a postgres container with name name-postgres in the docker network.
PGPASSWORD is used by Django whereas POSTGRES_PASSWORD is used by the Postgres database, so these should have the same value.
AP_PREDICT_ENDPOINT=http://name-app-manager:8080
Location of the AP predict endpoint.
Value above assumes you are running an app-manager container with the name ap-nimbus-app-manager in the docker network, but it could be set to be elsewhere.
HOSTING_INFO=
Supply a brief sentence about where this instance is hosted.
PRIVACY_NOTICE=""
A brief statement that will be shown at the start of the privacy notice
CONTACT_MAILTO=mailto:
Mailto link for contacting maintiners
CONTACT_TEXT=""
Contact text for contacting maintiners
AP_PREDICT_STATUS_TIMEOUT=1000
Status timeout (in ms). After this time the portal assumes something has gone wrong and stops trying to get a status update.

Prerequisites

In order for the cardiacmodelling/ap-nimbus-client-direct to call app-manager and display simulation results you at least need:

  1. The app-manager (See Running cardiacmodelling/ap-nimbus-app-manager).

  2. Communication: networking

    app-manager and client-direct need to be able to communicate with each other. There are two main ways of achieving this:

    1. You can refer to components by their docker IP address.
      To find this it needs to be started first, so you will have to start the database and app-manager first and find their IPs to use in the client-direct configuration.
    2. An easier way is to create a docker network (e.g. docker network create ap-nimbus-network) and add the database, app-manager and client-direct components to it and give each component a name.

  3. Data persistence

    Important: By default data does NOT persist.
    This means that if you restart the client-direct any uploaded files (cellml models and PK data files) will be gone and if you restart the database all data will be gone, i.e. all accounts, simulations, cellml models etc. Data volumes can be used to make sure data persists.

    The following commands create and “inspect” a docker data volume called volume-postgres:

    docker volume create volume-postgres
    docker volume inspect volume-postgres

    inspect reveals information including the mount point (the actual location where the data is stored). This mountpoint can be backed up if desired.

  4. Database

    The following starts a postgres 14.1 database using the official debian-bullseye postgres docker image.

    docker run -d --name name-postgres --net ap-nimbus-network --restart always --user postgres -v volume-postgres:/var/lib/postgresql/data --env-file env postgres:14.1-bullseye

    Parameters

    -d detached mode

    You could start with -it if you want to see output. However don’t forget to leave the component running (detach rather than close).

    --name name-postgres

    This is the name given to the component, it can be seen when doing docker ps and is the hostname we use in settings for client-direct.

    --net ap-nimbus-network

    Make sure the component is part of our docker network.

    --restart always

    Should the component stop for whatever reason we want it to try and restart.

    -v volume-postgres:/var/lib/postgresql/data

    Link the docker volume volume-postgres to the path inside the container where the database data is stored.

    --env-file env

    Use the Environment Variables in the env file.