Deploy, back up, and upgrade

The installation guide is a local evaluation path. For an ongoing service, use PostgreSQL, persistent broker storage, managed secrets, HTTPS, and a backup/restore procedure. The current repository pins version 0.5.0; verify matching image artifacts before planning a registry rollout.

Select a deployment configuration

Keep the app, orchestration worker, and migration image on the same release. Do not combine source and registry Compose stacks with the same fixed container names. Registry tags should be checked using the image verification commands in installation.

Configure credentials before the first start

Generate unique session, database, broker, and integration encryption values. Set POSTGRES_PASSWORD and the password inside DATABASE_URL consistently. In registry Compose, set RABBITMQ_DEFAULT_PASS and the matching password inside RABBITMQ_URL. Hex-generated passwords avoid URL-encoding ambiguity in connection strings.

openssl rand -base64 48
openssl rand -hex 24
openssl rand -hex 24
openssl rand -base64 32

Use the outputs for JWT_SECRET, database password, broker password, and SECRETS_ENCRYPTION_KEY, respectively. Do not reuse the example development credentials. Configure administrator/application bootstrap as described in installation. Keep .env outside version control and readable only by the deployment owner.

The registry file initializes a guest broker account with the configured password. For application AMQP workers, provision an appropriately scoped broker account/vhost and set WORKER_RABBITMQ_URL to the worker-accessible connection. If WORKER_BROKER_HANDOUT=false, workers must receive their broker connection separately. API-key isolation does not automatically create RabbitMQ permission isolation.

Changing initial PostgreSQL or RabbitMQ container environment does not rotate existing persisted users by itself. Coordinate credential changes in the database/broker and every client.

Expose only the intended services

Registry Compose publishes dashboard port 3300 and external API port 8081. Its default host mappings are not restricted to loopback; use host firewall rules or deployment-specific Compose bindings so clients cannot bypass your HTTPS proxy. Database, broker management, and metrics stay on the Docker network.

For a reverse proxy attached to the pipelogiq network, the targets are:

Dashboard and dashboard API: pipelogiq-app:8080
External SDK/worker API:     pipelogiq-app:8081

For example, replace these domain names with your own in Caddy:

workflows.example.com {
    reverse_proxy pipelogiq-app:8080
}

workflow-api.example.com {
    reverse_proxy pipelogiq-app:8081
}

The dashboard includes its own sign-in. Restrict access further according to your organization's network policy. Preserve WebSocket support and the forwarded HTTPS protocol. For the example HTTPS domain, create compose.production.yml in the repository root with the corresponding allowed origin:

services:
  pipelogiq-app:
    environment:
      CORS_ALLOWED_ORIGINS: https://workflows.example.com
      COOKIE_SECURE: always

Replace the domain with your actual browser origin, including its scheme. The supplied registry service does not pass CORS_ALLOWED_ORIGINS from .env, so that file alone is insufficient for this setting. Include the override on start:

docker compose --env-file .env -f infra/compose/docker-compose.registry.yml -f compose.production.yml up -d

Keep using the same override for later start/update commands. When following commands below, add -f compose.production.yml after the registry file if your deployment uses this override. Omitting it during an update can restore the original service configuration.

Understand migration ordering

The app does not migrate the database. The dedicated pipelogiq-migrate image runs Liquibase before the app starts. Compose requires service_completed_successfully; the Helm chart uses a migration hook. A completed migration container is expected to exit.

docker compose --env-file .env -f infra/compose/docker-compose.registry.yml ps -a
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml logs --tail=100 pipelogiq-migrate

Treat a failed precondition as an upgrade issue to investigate. Do not clear Liquibase history or change logicalFilePath to force migrations through. Version 0.5.0 includes account, role, credential, and session changes; duplicate normalized emails or other incompatible data can require preparation before migration.

Back up the database

Run from the repository root on the deployment host. This writes a PostgreSQL custom-format dump without printing connection credentials:

mkdir -p backups
chmod 700 backups
umask 077
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml exec -T pipelogiq-postgres \
  sh -c 'pg_dump --format=custom --no-owner -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
  > "backups/pipelogiq-$(date -u +%Y%m%dT%H%M%SZ).dump"

Check that the command succeeded and the dump is nonempty. Copy backups to storage independent of this host. Keep the matching SECRETS_ENCRYPTION_KEY, deployment configuration, and release identifiers separately in your recovery materials.

PostgreSQL is the orchestration source of truth. RabbitMQ still carries in-flight jobs and results, so preserve its volume and plan broker recovery too. A broker loss can require reconciliation of external outcomes; database recovery is not an exactly-once guarantee for side effects. The registry configuration persists both database and broker data; the source stack is not the production persistence reference.

Rehearse a restore

Restore into an isolated recovery installation first, with application and orchestration workers stopped. Choose one exact dump, not a wildcard. The following expects the selected dump at backups/restore.dump and replaces data in the target recovery database:

docker compose --env-file .env -f infra/compose/docker-compose.registry.yml stop pipelogiq-app pipelogiq-worker
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml exec -T pipelogiq-postgres \
  sh -c 'pg_restore --clean --if-exists --no-owner -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
  < backups/restore.dump

Start with the version/configuration matching the backup, including the encryption key. Confirm sign-in, application memberships, old run visibility, and worker connectivity before resuming real processing. Reconcile any business operation that may have occurred after the backup timestamp.

Upgrade in a maintenance window

1. Read the target release's migration and SDK compatibility notes.
2. Verify all three image tags exist and rehearse against a restored database copy.
3. Back up the live database and record the current version/configuration.
4. Set PIPELOGIQ_VERSION in the deployment environment to the verified target tag, then pull it.
5. Stop app/orchestration processing, apply the migration image, and start the stack only after success.

docker compose --env-file .env -f infra/compose/docker-compose.registry.yml pull
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml stop pipelogiq-app pipelogiq-worker
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml run --rm pipelogiq-migrate
docker compose --env-file .env -f infra/compose/docker-compose.registry.yml up -d
curl -fsS http://localhost:3300/api/version
curl -fsS http://localhost:3300/api/readyz

Then verify account access, expected worker registrations, schedule behavior, and a representative workflow. Upgrade application SDKs/workers after the compatible server is available. Health responses alone do not establish successful end-to-end execution.

Rollback needs a tested database/configuration plan. An older image may not preserve new access-control or schema behavior. There is no general automatic downgrade migration; do not assume every schema change is safely reversible.

Ongoing maintenance

Monitor migration failures, missing worker heartbeats, repeated timeouts, retry trends, scheduler lag, and audit record failed server errors. Use observability for metrics and alerts.

Community retains completed pipelines. Plan database growth and a reviewed retention process. Commercial retention/export catalogue entries do not establish an automatic archive or compliance guarantee; validate the exact feature and recovery behavior before relying on it.

Changing JWT_SECRET ends dashboard sessions. Changing the integration encryption key requires coordinated re-entry/re-encryption of integration secrets; simply replacing it makes existing encrypted values unreadable. Rotate application API keys through the key lifecycle.