Building the Docker Image from Source
HydroServer publishes a pre-built container image for every release to the GitHub Container Registry, which is the recommended way to deploy HydroServer (see Setting Up a Production Deployment). This guide is for building that same image yourself instead — useful if you're testing local changes, building from an unreleased branch, or want to inspect the build process directly.
Prerequisites
- Docker with BuildKit support. BuildKit has been the default builder since Docker Engine 23.0 — if you're on an older Docker installation, see the note in Step 2 below.
- Git.
Step 1: Clone the repository
git clone https://github.com/hydroserver2/hydroserver.git
cd hydroserverStep 2: Set up a builder (older Docker installations only)
The Dockerfile uses a multi-platform-aware build stage for the frontend apps. If docker buildx build fails with an error about parsing an empty platform, your Docker installation's default builder doesn't resolve this correctly. Create a dedicated builder that does:
docker buildx create --name hydroserver-builder --driver docker-container --useThis is a one-time setup step. Once created and selected (--use), later docker buildx build commands will use it automatically. If docker buildx build already works without this, you can skip this step.
Step 3: Build the image
From the repository root:
docker buildx build --load -t hydroserver:local -f django/Dockerfile .- --load
Loads the built image into your local Docker image store so it's usable withdocker run. Without it,buildxonly builds the image without making it available locally.
Step 4: Apply database migrations
Run this once against the database your container will use:
docker run --rm \
-e STRICT_SECURITY=False \
-e DATABASE_URL="postgresql://hsdbadmin:admin@host.docker.internal:5432/hydroserver" \
hydroserver:local \
python manage.py migrateStep 5: Run the container
This command serves traffic, so SECRET_KEY and IDP_OIDC_PRIVATE_KEY need real values. Replace them with securely generated values for live deployments. If you are running this container locally, you can alternatively just set STRICT_SECURITY to False.
docker run --rm -p 8000:8000 \
-e DATABASE_URL="postgresql://hsdbadmin:admin@host.docker.internal:5432/hydroserver" \
-e SECRET_KEY="replace-with-a-securely-generated-secret-key" \
-e IDP_OIDC_PRIVATE_KEY="replace-with-a-generated-oidc-private-key" \
hydroserver:local \
gunicorn hydroserver.wsgi:application --bind 0.0.0.0:8000 --workers 3Every setting other than the ones above falls back to its default in this example, which is enough to get a working instance running locally. For the full list of supported environment variables and their production recommendations, see Setting Up a Production Deployment.
After the server starts, visit http://127.0.0.1:8000 in a browser to access HydroServer.
