Deployment of the database, API and frontend⚓︎

The system is set up using docker compose. There are different containers spun up using docker compose:

The postgresql database. This uses the public postgis/postgis:17-3.5 image.
The frontend. This uses the docker image as pushed to GHCR, ghcr.io/ssciwr/onehealth-map-frontend:<tag>, where <tag> is replaced by the version number, latest or the branch name.
The Python backend. This contains both the ORM for the database and API, to process requests to the database from the frontend, but also the data feeding into the database. This uses the docker image as pushed to GHCR, ghcr.io/ssciwr/onehealth-db:<tag>, where <tag> is replaced by the version number, latest or the branch name; or can use a locally built image. The reason to supply a locally built image would be, for example, if one where to provide a changed config for the data feeding into the database, to include more or different data.

Development environment⚓︎

To bring up your development environment, add a .env file in the onehealth-db root directory, that contains the following environment variables:

POSTGRES_USER=<user>
POSTGRES_PASSWORD=<password>
POSTGRES_DB=<db-name>
DB_USER=<user>
DB_PASSWORD=<password>
DB_HOST=db
DB_PORT=5432
DB_URL=postgresql://<user>:<password>@db:5432/<db-name>
WAIT_FOR_DB=true
IP_ADDRESS=0.0.0.0

Replace the entries <user>, <password>, and <db-name> with a username, password, and database name of your choosing. You only need to set the IP address for a server running in production (this is relevant for the Cross-Origin Resource Sharing (CORS), a security feature for handling the requests across the web).

To bring the database up and feed the development data into the database, run the command

docker compose up --abort-on-container-exit production-runner

This will insert the testing data into the database for the development environment. After the data has been inserted, you need to run

docker compose up api

to start the frontend and API service (request handling to the database). If you are running this locally, you should be able to access the frontend through your browser at 127.0.0.1:80 or localhost:80.

If you know what you are doing, and want to test the API directly, you can open port 8000 through changing the docker-compose.yaml file, exposing this port from the network by including ports: under the service api::

  ports:
    - "8000:8000"

Similarly you can expose the database, to test the connectivity from outside of the docker network.

Building the image locally⚓︎

To build the docker image locally, i.e. for a changed database config file, execute

docker build -t onehealth-backend .

This will build the image locally. In the docker-compose.yaml file, you need to change the line image: ghcr.io/ssciwr/onehealth-backend:latest to use your local image. Alternatively, you can also force docker compose to rebuild the image locally by uncommenting the build: ... lines in the respective sections. To tag a local image with the correct name so it can be pushed to GHCR, use

docker image tag onehealth-backend ghcr.io/ssciwr/onehealth-backend:latest

This image can be pushed to GHCR (provided, you have set your CR_PAT key in your local environment):

docker push ghcr.io/ssciwr/onehealth-backend:latest

Production environment⚓︎

To run the system in production, change the database configuration file to include all the data you want to ingest in the database. Then trigger a local build of the docker image (see above) and run the two docker compose commands, to build the tables locally and start the API service and frontend:

docker compose up --abort-on-container-exit production-runner
docker compose up api

Troubleshooting⚓︎

Sometimes issues arise with old, leftover volumes from the database. To remove old volumes, use docker compose down -v or docker volume prune (or docker system prune --force --volumes to remove all old images, containers and volumes).

The same applies for networking issues, this is usually resolved by a docker compose down and docker compose up -d.