RelayOps/docs/rollback.md

Rollback

Purpose

This document describes a low-risk rollback procedure for the first-stage production deployment.

Principles

• do not delete PostgreSQL or Redis volumes during rollback;
• do not remove .env.production;
• prefer switching containers back to the last known-good image or revision;
• avoid ad-hoc schema downgrades during an incident;
• verify /health and login before declaring rollback complete.

Safe Rollback Procedure

1. Identify the currently running revision and the last known-good revision.
2. Keep a copy of the current environment file:

cp .env.production .env.production.backup

3. If the issue is configuration-only, restore the previous config file versions first:

   • .env.production
   • deploy/nginx/server-panel.conf
   • docker-compose.prod.yml

4. Switch the repository back to the last known-good revision.

5. Rebuild and restart the production stack without touching volumes:

docker compose \
  --env-file .env.production \
  -f docker-compose.prod.yml \
  up --build -d

6. If the rollback target expects the same additive schema, keep the migrated database in place. If a future revision introduces incompatible schema changes, restore from a database backup instead of attempting an emergency manual downgrade.
7. Verify:
   • http://YOUR_HOST/health
   • frontend load at /
   • admin login
   • one read-only API flow

If The New Frontend Is The Only Problem

If the backend is healthy and only the frontend is broken:

1. restore the previous frontend source or image tag;
2. rebuild only the frontend and reverse proxy path:

docker compose \
  --env-file .env.production \
  -f docker-compose.prod.yml \
  up --build -d frontend reverse-proxy

3. re-check / and one authenticated UI action.

If The Backend Or Worker Is The Problem

1. restore the previous backend revision;
2. rebuild:

docker compose \
  --env-file .env.production \
  -f docker-compose.prod.yml \
  up --build -d backend worker bot reverse-proxy

3. verify:
   • /health
   • login
   • queued action processing

Do Not Do This During Rollback

• do not run docker compose down -v;
• do not remove postgres_data;
• do not remove redis_data;
• do not delete the database to "start clean";
• do not improvise manual ALTER TABLE rollback steps on production data.

After Rollback

Capture:

• what failed;
• which revision was restored;
• whether any queued actions need manual follow-up;
• whether the reverse proxy or environment template needs a corrective update before the next deployment.