Installation

Please ensure that Docker and Docker Compose is installed on the host machine. Download and install instructions for Docker on Ubuntu can be found here link.

Setup

Before running any environment, copy the environment and volumes template files:

cp .env.template .env
cp docker-compose.volumes.yml.template docker-compose.volumes.yml

Then fill in the required values in .env (see Environment variables below). Both files are gitignored and will not be committed.

Development

To start the webapp locally in development mode:

make dev

This starts the Django, Postgres, and Firefly containers. Once running, the webapp is accessible at http://localhost:80 with the following default credentials:

Username: admin
Password: test

To shut down:

make dev-down

Production

First-time HTTPS certificate setup

Before starting production for the first time, obtain a Let’s Encrypt TLS certificate. Ports 80 and 443 must be open and vaster.duckdns.org must resolve to the server:

make cert-init-prod EMAIL=your@email.com

This script creates a temporary self-signed cert, starts nginx, obtains a real certificate via the ACME webroot challenge, then reloads nginx.

Starting production

make prod

This starts all containers including nginx (HTTPS on port 443, HTTP→HTTPS redirect on port 80) and a certbot container that automatically renews the certificate every 12 hours.

To shut down:

make prod-down

Staging

First-time HTTPS certificate setup

make cert-init-staging EMAIL=your@email.com

Same process as production but for vaster-staging.duckdns.org.

Starting staging

make staging

The staging environment is identical to production but displays a [STAGING] indicator in the header bar. Optionally, place a staging-details.html file in the repo root to display release notes on the home page.

To shut down:

make staging-down

Environment variables

All environment-specific configuration is set in .env. The following variables must be filled in before deploying:

DJANGO_ALLOWED_HOSTS: Space-separated list of allowed hostnames, e.g. vaster.duckdns.org
DJANGO_SUPERUSER_USERNAME: Admin username
DJANGO_SUPERUSER_PASSWORD: A strong password (16+ characters, mixed case, numbers, symbols)
DJANGO_SUPERUSER_EMAIL: Admin email address shown to users for support
DJANGO_SECRET_KEY: A long random string used for cryptographic signing
DB_PASSWORD / POSTGRES_PASSWORD: Database passwords

See .env.template for the full list of variables.

Volumes

By default, Docker manages the named volumes for the database and media files. If you wish to store data at specific paths on the host machine, edit docker-compose.volumes.yml and uncomment the driver_opts block for each volume:

volumes:
  django_media:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /data/vaster_webapp/volumes/django_media

Make sure the directories exist and have the correct permissions before starting:

mkdir -p /data/vaster_webapp/volumes/django_media
sudo chown -R 999:999 /data/vaster_webapp/volumes/django_media

Please note that ports 80 and 443 on the host machine must be open for internet traffic to reach the webapp. Refer to this guide on how to open ports on Ubuntu 22.04.

Backups

For production deployments, it is strongly recommended to set up automated backups of the database and media files. See the Backup documentation for details.