drivers_bot/DEPLOY.md

CarPass Deploy

First Install

sudo mkdir -p /opt/carpass
sudo chown "$USER":"$USER" /opt/carpass
git clone <repo-url> /opt/carpass/app
cd /opt/carpass/app
cp .env.example .env

Edit .env and set real secrets:

• BOT_TOKEN
• BOT_USERNAME
• PUBLIC_WEBAPP_URL
• CORS_ORIGINS
• INTERNAL_API_TOKEN
• SECRET_KEY
• REDIS_URL if Redis is external
• VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY only when browser push beta is enabled
• ADMIN_TELEGRAM_IDS

Production must use public HTTPS URLs and ALLOW_DEV_AUTH=false.

Start

docker compose up -d --build
docker compose exec api alembic upgrade head
python -m scripts.bootstrap_admin
curl -fsS http://127.0.0.1:8000/ready

If port 8000 is already used on the host, set APP_PORT in .env and point the reverse proxy to that local port:

APP_PORT=8010
curl -fsS http://127.0.0.1:8010/ready

The default compose stack includes Postgres, Redis, API and bot services with health checks, restart policies and log rotation. Telegram notifications are the primary pilot notification channel. Browser push currently stores subscriptions and is treated as beta until server-side Web Push delivery is enabled.

Git-Based Update

The server directory must remain a git clone. The main update path is:

APP_DIR=/opt/carpass/app DEPLOY_BRANCH=main ./scripts/deploy.sh

The script runs:

• git fetch
• git pull --ff-only
• optional DB backup with BACKUP_BEFORE_DEPLOY=true
• Docker build/up
• alembic upgrade head
• Python smoke compile
• /health, /ready and /metrics smoke checks

Do not use rsync as the primary deploy mechanism.

Rollback

cd /opt/carpass/app
git log --oneline -20
git checkout <previous_commit>
docker compose up -d --build
curl -fsS http://127.0.0.1:8000/ready

Be careful with database migrations: code rollback does not automatically downgrade data.

Backups

Create a compressed custom-format dump before risky deploys:

BACKUP_DIR=/opt/carpass/backups ./scripts/backup_db.sh

Compatibility wrapper:

BACKUP_DIR=/opt/carpass/backups ./scripts/backup.sh

Restore only during a maintenance window:

./scripts/restore_db.sh /opt/carpass/backups/carpass-drivers-YYYYMMDDTHHMMSSZ.dump

Compatibility wrapper:

./scripts/restore.sh /opt/carpass/backups/carpass-drivers-YYYYMMDDTHHMMSSZ.dump

For volume-level recovery, back up the Docker named volumes pgdata and redisdata according to the host backup policy.

Logs

docker compose ps
docker compose logs -f api
docker compose logs -f bot
docker compose logs -f db

Migration Smoke Check

For a configured Postgres database:

./scripts/check_migrations.sh

Cleanup Jobs

Run periodic cleanup from cron or systemd timer:

docker compose exec -T api python scripts/cleanup_jobs.py

It expires stale employee invites, marks exhausted notifications as abandoned, removes old abandoned notifications and clears old draft work orders.