call-center/docs/runbooks/postgres-server-parallel-stack.md

Runbook - Parallel PostgreSQL-backed Stack on a Shared Docker Host

Use this runbook after the isolated PostgreSQL server from postgres-server-docker.md is already running. The goal is to bring up a second call-center stack on PostgreSQL without stopping the current SQLite-backed stack on port 8080.

Assets

• Compose file: deployment/docker-compose.parallel.server.yml
• Base env: /home/mvpcc/call-center-pg/.env.production
• Override env: /home/mvpcc/call-center-pg/.env.postgres.parallel.server
• Runtime data dir: /home/mvpcc/call-center-pg/.data_pg_parallel
• Gateway port: 18080

This parallel stack intentionally disables active external integrations so it stays passive while the SQLite-backed stack remains live:

• Telegram bot disabled
• WhatsApp outbound disabled
• Asterisk bridge disabled
• FastAGI disabled
• AI voice disabled

The parallel stack reaches PostgreSQL over the external Docker network created by deployment/docker-compose.postgres.server.yml, using the hostname call-center-postgres on port 5432.

Server bring-up

Prepare a separate build workspace from the current repository checkout:

rm -rf /home/mvpcc/call-center-pg
mkdir -p /home/mvpcc/call-center-pg

Copy the current .env.production from the live SQLite stack, then add a PostgreSQL override file:

cd /home/mvpcc/call-center-pg
cp /home/mvpcc/call-center/.env.production .env.production
cp .env.postgres.parallel.server.template .env.postgres.parallel.server

Update .env.postgres.parallel.server:

• replace <server-host> with the real server host or IP
• replace the PostgreSQL password placeholder with the password from /home/mvpcc/call-center/.env.postgres.server
• keep DATABASE_URL pointed at call-center-postgres:5432, not 127.0.0.1:5434

Build the image and prepare the runtime directory:

cd /home/mvpcc/call-center-pg
mkdir -p .data_pg_parallel
docker compose -f deployment/docker-compose.parallel.server.yml build

The parallel compose builds and uses the dedicated image tag call-center-app:pg-parallel.

Run migrations before starting the stack:

cd /home/mvpcc/call-center-pg
docker compose -f deployment/docker-compose.parallel.server.yml run --rm auth-service python scripts/migrate_core_db.py

Bring up the PostgreSQL-backed stack:

cd /home/mvpcc/call-center-pg
docker compose -f deployment/docker-compose.parallel.server.yml up -d

Verification

Health and status:

cd /home/mvpcc/call-center-pg
docker compose -f deployment/docker-compose.parallel.server.yml ps
curl -fsS http://127.0.0.1:18080/health
curl -fsS http://127.0.0.1:18080/proxy/auth/health
curl -fsS http://127.0.0.1:8080/health

Focused PostgreSQL preflight from inside the parallel stack:

cd /home/mvpcc/call-center-pg
docker compose -f deployment/docker-compose.parallel.server.yml run --rm auth-service \
  sh -lc 'python scripts/postgres_dev_preflight.py --database-url "$DATABASE_URL" --base-url http://api-gateway:8000'

Expected result:

• the new stack is reachable at http://<server-host>:18080
• the old SQLite-backed stack stays reachable at http://<server-host>:8080
• no host ports except 18080 are added for the parallel stack
• the PostgreSQL-backed containers stay healthy
• application containers talk to PostgreSQL over Docker network call-center-postgres_default

Scope guardrails

Do not do these actions in this step:

• do not stop or restart the existing call-center compose project
• do not change /home/mvpcc/call-center/deployment/docker-compose.server.yml
• do not reuse the existing call-center-app:local image tag for the new stack
• do not re-enable Telegram, WhatsApp, or Asterisk on the parallel stack until cutover is planned