Local Docker validation before Azure rollout¶

Purpose¶

Use this runbook to validate the Milestone 1 low-side Pulp scaffold locally before handing it to the Azure deployment workflow.

This runbook verifies:

Docker/Compose wiring,
Pulp runtime secrets and key material,
the Ubuntu 22.04 repo matrix inputs,
the bootstrap workflow against the local control plane.

It does not validate the high side or production transfer behavior.

Prerequisites¶

Docker and Docker Compose installed
Python 3 available for the validation helper scripts
outbound access to pull the configured container images
outbound access to https://archive.ubuntu.com/ubuntu/ if you later enable sync
free local ports 18080 and 18081 by default, or alternate ports you choose in .env

1. Prepare local-only secrets¶

From the repo root:

python3 -m pip install -r automation/bootstrap/requirements.txt
cp runtime/compose/.env.example runtime/compose/.env
mkdir -p /opt/linux-update-cds/{postgres-data,pulp-data}
mkdir -p runtime/compose/pulp/certs
python3 -c 'import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())' \
  > runtime/compose/pulp/certs/database_fields.symmetric.key
chmod 600 runtime/compose/pulp/certs/database_fields.symmetric.key

Then edit runtime/compose/.env and replace the placeholder values for:

PULP_SECRET_KEY
PULP_ADMIN_PASSWORD
POSTGRES_PASSWORD

The default LOCAL_STORAGE_ROOT is /opt/linux-update-cds. Keep postgres-data and pulp-data on storage with enough capacity for local sync testing, or override LOCAL_STORAGE_ROOT before starting the stack.

Do not commit .env or the runtime/compose/pulp/certs/ directory.

2. Resolve any local port conflicts¶

If 18080 or 18081 are already in use on your workstation, update all four values together in runtime/compose/.env:

PULP_API_PORT
PULP_CONTENT_PORT
PULP_API_BASE_URL
PULP_CONTENT_ORIGIN

Example alternate values:

PULP_API_PORT=28080
PULP_CONTENT_PORT=28081
PULP_API_BASE_URL=http://localhost:28080
PULP_CONTENT_ORIGIN=http://localhost:28081

3. Validate the Compose rendering¶

docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml config

This should exit cleanly and show the resolved low-side stack.

4. Start the core services¶

docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml \
  up -d postgres redis pulp-api pulp-content pulp-worker

Then confirm the stack is healthy:

docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml ps

curl http://localhost:18080/pulp/api/v3/status/

If you chose alternate ports, use the matching API URL instead of 18080.

Before enabling sync, validate the configured upstream:

python3 automation/bootstrap/validate_upstream.py --repo-config config/repos/ubuntu-jammy.yaml

The default upstream is https://archive.ubuntu.com/ubuntu/. Set PULP_UBUNTU_REMOTE_URL in runtime/compose/.env only when testing an approved internal mirror.

5. Reconcile the repo-as-code inputs¶

The bootstrap profile applies the Milestone 1 repo matrix from:

config/environments/low-side.yaml
config/pulp/settings.yaml
config/repos/ubuntu-jammy.yaml

Run it after the API endpoint is reachable:

docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml \
  --profile runtime --profile bootstrap run --rm bootstrap

Default behavior¶

By default:

SYNC_ON_BOOTSTRAP=false
PUBLISH_ON_BOOTSTRAP=false

That means the bootstrap step is safe for initial validation: it reconciles the object model without immediately pulling upstream content or publishing new distributions.

Optional deeper validation¶

After the status endpoint is healthy and the upstream is reachable, you can enable a fuller validation pass:

SYNC_ON_BOOTSTRAP=true \
PUBLISH_ON_BOOTSTRAP=true \
docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml \
  --profile runtime --profile bootstrap run --rm bootstrap

Keep this limited to the Milestone 1 Ubuntu matrix.

Validation checklist¶

You are ready for the Azure handoff when all of the following are true:

docker compose ... config exits with no errors,
the Pulp status endpoint returns JSON,
the bootstrap runner exits successfully,
the configured remotes/repositories/distributions match the jammy matrix,
local secrets stayed in .env and runtime/compose/pulp/certs/ only.

Troubleshooting¶

Symptom	Likely cause	Action
`Bind for 0.0.0.0:18080 failed`	local port conflict	choose alternate local ports and update both port and URL values in `.env`
Pulp containers restart immediately with missing key errors	no local DB encryption key file	generate `runtime/compose/pulp/certs/database_fields.symmetric.key` before starting
bootstrap cannot log in	placeholder admin password still in use or mismatch	update `PULP_ADMIN_PASSWORD` in `.env` and restart the stack
image pull or plugin issues	local machine cannot pull the selected `PULP_IMAGE` or the image is not the approved org build	point `PULP_IMAGE` at the approved low-side image before rollout

Cleanup¶

When the local validation pass is complete:

docker compose --env-file runtime/compose/.env \
  -f runtime/compose/docker-compose.yml down