The Bird Ringing Project

Deployment

Deployment instructions can be found here.

Development and production environments

The docker-compose.yml file defines the production environment, while the docker-compose.dev.yml contains the overrides for the development environment.

Two convenience scripts are provided for starting the two different environments: compose-prod.sh for the production environment and compose-dev.sh for the development environment.

To start and stop the production environment, use:

./compose-prod.sh up --build
./compose-prod.sh down

To start and stop the development environment, use:

./compose-dev.sh up --build
./compose-dev.sh down

In general, the scripts can be used with any docker compose command, for example:

./compose-dev.sh {up|down|logs|ps|...} [options]

Regardless of the environment, once started, the website will be available at http://localhost:3210/.

Getting started

Creating users

From the project root (the bird-ringing directory), run: /create-test-users Then open http://localhost:3210/admin/ and log in to the Django admin using the credentials admin:test. Create a new user and add that user to the bird-ringer expert group.

Load mock data (latest)

To use the more recent batch of mock data, from the project root (bird-ringing), run the three commands:

mkdir -p backend/mock_data/example/
./create-test-users
./data-init

Local email testing

For local development, the Docker Compose setup includes Mailpit for capturing outgoing emails. Open the Mailpit at http://localhost:8025/ to inspect emails sent by the application without sending real messages.

Frontend development

Adding dependencies

To add a dependency, add it to package.json under "dependencies" or "devDependencies", depending on your usecase. We use the caret (^) syntax to make sure to always have the latest version of dependencies.

Afterwards, run the script update-package-lock inside the frontend folder. Commit both your package.json and package-lock.json to GitHub.

Linting & formatting

ESlint is running as a linter when you push to GitHub. For formatting, we have decided to follow Prettier's default settings. There are three scripts in the scripts folder that can help you do things locally:

• If you want to check for linting errors locally, run lint-frontend.sh
• If you want to check for formatting errors, run format-frontend.sh
• If you want to fix formatting errors automatically, run fix-frontend.sh

Switching between development and production deployments

When switching between development and production deployments, e.g., when testing, it is important to bring down the currently running environment before rebuilding and starting the other environment.

For example, to switch from a running development environment to a production environment, use the following commands:

./compose-dev.sh down           # Bring down the development environment
./compose-prod.sh up --build    # Build and start the production environment

To switch from a running production environment to a development environment, use the following commands:

./compose-prod.sh down          # Bring down the production environment
./compose-dev.sh up --build     # Build and start the development environment

Differences between development and production environments

The main differences between the two environments are:

• The frontend directory is bind-mounted into the "frontend" service container in the development environment, while in the production environment, the source code is copied into the container at build time.

• The backend directory is bind-mounted into the "backend" service container in the development environment, while in the production environment, the source code is copied into the container at build time.

• The "frontend" service in the development environment runs the development server with hot reloading, while in the production environment, it does nothing apart from checking to make sure the static site's file are present.

  • The development server is served by npm run dev.
  • The production server is built as an exported static site and served by a Caddy web server. The exported site is stored in the frontend-vol Docker volume.

Application Secrets

The following file is required and must be created before attempting to deploy the backend server.

The file should only contain the secret value itself.

• secrets/django-secret-key.txt - This is used to provide cryptographic signing, and should be set to a unique, unpredictable value.

Database management

The database used by this project is a PostgreSQL database running in a Docker container called database. The name of the database in the container is ringdb. Apart from the database superuser, postgres, there are the two application users db_admin (only used for applying schema migrations) and db_user.

Direct access to the database can be obtained by exposing the database port for the database container in the docker-compose.yml file and connecting to it directly from the host, or by using the psql command in the database container:

./compose-prod.sh exec database psql -U db_user -d ringdb

Database passwords

Passwords used for accessing the database are stored in separate files in the secrets directory at the root of the project. The following files are required and must be created before attempting to set up the initial database.

The files should only contain the secret values themselves.

• secrets/postgres-pass.txt - The password for the PostgreSQL superuser, postgres. This user has full administrative access to the database server, and is only used for initial database setup.

• secrets/db-admin-pass.txt - The password for the PostgreSQL application admin user, dbadmin. This is the user that has the ability to apply migrations to the database. It is only used by the backend-init service when applying migrations during service startup.

• secrets/db-user-pass.txt - The password for the PostgreSQL application user dbuser. This is the user that the application connects to the database with.

Database initialisation

If the database-vol Docker volume does not exist, the database is initialised when the services are started with either ./compose-prod.sh up or ./compose-dev.sh up.

Database backup

A backup of the database can be created with the following command while the database container is running:

./compose-prod.sh exec database pg_dump --format=custom -U postgres ringdb >initdb.d/database.dump

Restoring a database from a backup

A database dump file called initdb.d/database.dump will be restored automatically when the services are started with docker compose up if the database-vol Docker volume does not exist.

All Docker volumes associated with the project can be removed with the following command:

./compose-prod.sh down -v

Or, to only remove the database volume (assuming all services are stopped), use:

docker volume rm bird-ringing_database-vol

Docker build setup (for developers)

Frontend

• node:24-alpine
  • base
    • prod-build
    • dev
• busybox:stable-musl
  • prod
    • Copies static site from prod-build stage

Backend

• python:3.12-alpine
  • base
    • prod-build
    • dev
• python:3.12-alpine
  • prod
    • Copies application from prod-build stage