Skip to content

Demo Server Guide

Jump to bottom
Carl Smith edited this page Feb 21, 2022 · 21 revisions

Conforma Server build, versioning, and install using Docker

Prep

  • Add token to githubtoken.txt (for downloading expression-evaluator)
    • requires token that has read access to packages on server repo
  • Ensure your back-end .env has a variable called FRONT_END_PATH with the full path to the front-end repo on your local system.
    e.g. FRONT_END_PATH='/Users/<username>/GitHub/conforma/application-manager-web-app/'
  • Ensure your local Docker installation is logged in with the msupplyfoundation account (Password in Bitwarden)

Bump the version and generate a tag.

  • The version field in package.json is the source of truth for the current version number. Increases to version numbers should be done according to semantic versioning, including "pre-release" versions (for testing purposes, for example).
  • Bump the version and create a tag by running the script yarn release <version-type>, where version-type is on of "--major", "--minor", "--patch" or "--prerelease". ("--pre-release" is the default if not specified.) This will also apply the new version number to the front-end (on whatever branch is currently checked out, so it should normally be develop or main). The tag is auto-generated by the yarn version command (run as part of this release script), and is just v<version-num> (e.g. v0.1.5-2)
  • Note: it is not necessary to create a "release" on Github for each tag unless we need to make a particular version publicly downloadable, but one can easily be created based on the current tag/version on Github if required.

Build (and upload to Docker hub)

yarn dockerise <tag-name> [push]

(If you don't specify any parameters, it will build the current develop branch.)

Note that the previous yarn release script will offer to start this build process automatically with the tag you've just created.

It should take a while to run and will build a local Docker image. The optional parameter push specifies if the script should automatically push the created image to the msupplyfoundation Docker Hub account.

Example:
yarn dockerise v0.1.5 push

The build process will create a local image with a tag of the form: build-<releaseTag>_<date>_pg-<version>_node-<version>

To see what's going on under the hood when this command is run, please inspect the file /docker/dockerise.sh

If you don't auto-push the image as part of the build process, you can do so manually by running: docker push <full image name>, where <full-image-name> includes the account name, repo name ("conforma-demo") and tag.

Example:
docker push msupplyfoundation/conforma-demo:build-B-1.0.13_2021-12-08_pg-12_node-14

Test locally

When the build (above) completes, it should print a command for running the new image locally, which you can copy and paste. It will be something like:

yarn docker_run msupplyfoundation/conforma-demo:build-B-1.0.13_2021-12-08_pg-12_node-14

You'll need to make sure you have the SMTP_PASSWORD in your local .env file.

To see the actual Docker commands that are constructued, please inspect the file /docker/run.sh

Log in to demo server with ssh

  • Get key file from Bitwarden (openstack-irims-demo-keypair) and save locally (e.g. in ~/Documents/private/conformakey.pem)

  • SSH login to server:

    export KEY_LOC='/Users/<you>/Documents/private/conformakey.pem' (or your local location)
sudo ssh -i $KEY_LOC [email protected]

  • View commit hashes of currently running images:
    sudo docker container ls

  • Stop all instances:
    sudo docker stop <hashes… >

  • Pull image from docker hub:
    sudo docker pull <full-image-name> Example: sudo docker pull msupplyfoundation/conforma-demo:build-B-1.0.13_2021-12-08_pg-12_node-14

  • Run image:
    sudo docker run -dti -p 8000:3000 -e 'SMTP_PASSWORD=<password>' -e 'WEB_HOST=https://irims-demo.msupply.org:50000' -e 'JWT_SECRET=<some-random-secret>' --name conforma-demo-on-8000 msupplyfoundation/conforma-demo:build-B-1.0.13_2021-12-08_pg-12_node-14
    This will launch one instance. To launch other instances in their own container, run the same command, but change:

    • name
    • port 8000
    • WEB_HOST url
    • JWT_SECRET (this can be any random string, but should be a decent length, say > 24 alphanumeric characters. There's no need to record this key anywhere, as it can change anytime -- that just means existing JWTs become invalid, so users will need to re-login)

    The system will be launched with “basic_snapshot” data. Upload and run a new snapshot as required

Move files/folder to/from instance

Edit script in ./docker/demo_server/docker-compose.yml

  • only change the image name (if required)
  • don't change SMTP_PASSWORD!

Copy script folder demo server scripts

Note: You are sending local changes to the server

cd application-manager-server/docker
scp -r -i $KEY_LOC ./demo_server [email protected]:/home/ubuntu/

Now jump to section docker-compose if this is just a server upgrade

Download nginx config from demo server to local

Note: These steps doesn't seem required for a sever upgrade

cd application-manager-server/docker
scp -i $KEY_LOC [email protected]:/etc/nginx/sites-enabled/default ./demo_server/nginx_config

Upload nginx config back to demo server

# cannot directly replace default config, need to do it as sudo, so from within docker instance
sudo mv demo_server/nginx_config/default /etc/nginx/sites-enabled/

NGINX

Everything should be configured via default config. Cert bot was installed and should auto update certs (https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx).

After changing config as per above, run

sudo service nginx restart

Logs are in /var/log/nginx

docker-compose

docker-compose will complain if directories are not present, create them if needed (they will persist when restarting image, even if docker-compose down was run)

mkdir app_snapshots_on_port_8000
mkdir app_postgres_on_port_8000

mkdir grafana_on_port_8001
# grafana user has to own the local directory that's mounted to volume
# https://community.grafana.com/t/new-docker-install-with-persistent-storage-permission-problem/10896/2
sudo chown 472 grafana_on_port_8001

mkdir app_snapshots_on_port_8002
mkdir app_postgres_on_port_8002

mkdir grafana_on_port_8003
sudo chown 472 grafana_on_port_8003

mkdir app_snapshots_on_port_8004
mkdir app_postgres_on_port_8004

mkdir grafana_on_port_8005
sudo chown 472 grafana_on_port_8005

mkdir app_snapshots_on_port_8006
mkdir app_postgres_on_port_8006

mkdir grafana_on_port_8007
sudo chown 472 grafana_on_port_8007

mkdir app_snapshots_on_port_8008
mkdir app_postgres_on_port_8008

mkdir grafana_on_port_8009
sudo chown 472 grafana_on_port_8009

Launching all

export TAG='build-B-1.0.13_2021-12-08_pg-12_node-14'
export SMTP_SECRET='add_smtp_secret_here'
export WEB_URL='https://irims-demo.msupply.org:<replace port>'
export JWT_SECRET='random private key'

# -d is for detached, if you want to see all output then start without -d
PORT_APP=8000 PORT_DASH=8001 sudo -E docker-compose --project-name 'conforma-on-8000' up -d

# currently running with snapshot demo-2021-08-27
PORT_APP=8002 PORT_DASH=8003 sudo -E docker-compose --project-name 'conforma-on-8002' up -d

# currently running with basic_snapshot
PORT_APP=8004 PORT_DASH=8005 sudo -E docker-compose --project-name 'conforma-on-8004' up -d
PORT_APP=8006 PORT_DASH=8007 sudo -E docker-compose --project-name 'conforma-on-8006' up -d
PORT_APP=8008 PORT_DASH=8009 sudo -E docker-compose --project-name 'conforma-on-8008' up -d

View logs

# don't need bash inside contiainer for this
sudo docker exec -ti conforma-on-8000_app_1 cat /var/log/application_manager/server.log
sudo docker exec -ti conforma-on-8000_app_1 cat /var/log/application_manager/graphile.log

To restart an instance

In case you don't want to use the existing database previously set on that instance, you need to stop and remove the resouces by doing this:

  • Run sudo docker stop <name>

    • name from above (plus _app_1 e.g.: conforma-on-8000_app_1)
    • or can use container id. e.g.: sudo docker stop 030f8b82814b

  • Remove container: sudo docker rm <name> or remove the folder on demo_server (e.g sudo rm -rf app_postgres_on_port_8000)

  • Now re-run the instance changing the ports accordingly to the instance you need to re-launch: PORT_APP=8000 PORT_DASH=8001 sudo -E docker-compose --project-name 'conforma-on-8000' up -d

Note: this resets the container to initial state, including database reset. If you want to preserve existing data, you’ll need to take a snapshot first, then reload after restart.

Other image/container commands

  • List local images

sudo docker images

  • Remove all containers

sudo docker rm $(sudo docker ps -a -q)

  • Remove all images

sudo docker rmi -f $(sudo docker images -a -q)

  • Remove all images

sudo docker volume prune

Access command line within container:

You can access the command line of a particular container instance with the following:

sudo docker exec -ti <name-or-container-id> /bin/bash

From there the following commands might be useful:

  • view environment variables: printenv
  • check the server log: tail -n 100 /var/log/application_manager/server.log

mSupply logo

Powered by mSupply

Clone this wiki locally