Docker - Peering Manager

This repository contains the components needed to build Peering Manager as a Docker container. It provides everything that is needed to run the whole application stack.

Dependencies

This project relies only on Docker and docker-compose. Make sure to use a decent version of each tool and everything will work as expected.

To check the version installed on your system run docker --version and docker compose --version.

Getting Started

Built Images

Official Docker images of Peering Manager are available on Docker Hub

Building Images

To build your own images you'll need the following binary: bash, curl, git and jq (in addition to Docker and standard UNIX utils).

./build.sh can be used to rebuild Docker images. See ./build.sh --help for more information. build-latest.sh will automatically retrieve the last available version of Peering Manager and build its image.

Running With Docker Compose

To run the Peering Manager application stack with Docker Compose, copy the docker-compose.override.yml.example file into docker-compose.override.yml and override definitions from this file.

Scheduled Tasks

Peering Manager 1.11 and later run housekeeping and PeeringDB synchronisation from the rqworker service. Manage the schedule of each task from Admin > Scheduled Tasks in the web interface.

The housekeeping and peeringdb-sync services stay in docker-compose.yml for users who prefer an external scheduler. They do not start by default. First disable the matching tasks in Admin > Scheduled Tasks, then start them:

docker compose --profile external-scheduler up --detach

Do not run a task twice. Two runs of the same task waste resources, and a PeeringDB synchronisation can take about 90 minutes.

Base Path

Set BASE_PATH in env/peering-manager.env to serve Peering Manager from a directory, for example https://example.com/peering/:

BASE_PATH=peering/

The container applies the value to the URLs, to the static files and to its health check.

Upgrade PostgreSQL

docker-compose.yml tracks a recent PostgreSQL release, so a git pull can move the database to a new major version. A server refuses a data directory that another major version wrote, so every major bump needs a dump and a restore.

Take the dump before you pull, while the old server still runs:

docker compose exec -T postgres pg_dumpall -U peering_manager >dump.sql
docker compose down
docker volume ls  # find the name of the postgres volume
docker volume rm <project>_peeringmanager-postgres-data
git pull
docker compose up --detach --wait postgres
docker compose exec -T postgres psql -U peering_manager -d postgres <dump.sql
docker compose up --detach

Compose puts the name of your project in front of the volume, hence the docker volume ls step.

The restore reports two errors, one for the role and one for the database that already exist. Ignore them, because the new container creates both before the restore runs.

To stay on your current major version, pin the image in your docker-compose.override.yml. For example, to keep PostgreSQL 17:

services:
  postgres:
    image: docker.io/postgres:17-alpine

One extra step applies when you come from PostgreSQL 17 or older. Version 18 keeps its data in a directory named after the major version, so docker-compose.yml mounts the volume on /var/lib/postgresql instead of /var/lib/postgresql/data. Copy that change if you declare the postgres service yourself.

About

This work is based on the great netbox-docker project and uses the same license.