TenantAtlas/docs/deployment-checklist.md

TenantPilot Deployment Checklist

Status: 2026-05-15 Target: Sail locally, Dokploy-first staging/production, PostgreSQL, container-based deployment.

Production Readiness Checklist

• Staging environment exists and is the mandatory production gate.
• APP_ENV=production and APP_DEBUG=false.
• APP_KEY is stable, secret, and backed up securely.
• Database is PostgreSQL 16-compatible.
• Storage volumes/private object storage are persistent.
• Queue workers and scheduler are explicitly configured.
• Health check route /up is monitored.
• Logs are collected outside the container.
• Backups are encrypted and restore-tested.
• Dependency audits are clean or exceptions are approved.

Build and Release Checklist

1. cd apps/platform && composer install --no-dev --optimize-autoloader
2. cd apps/platform && corepack pnpm install --frozen-lockfile
3. cd apps/platform && corepack pnpm build
4. cd apps/platform && php artisan filament:assets
5. cd apps/platform && php artisan migrate --force
6. cd apps/platform && php artisan optimize
7. Restart or reload long-running services with php artisan reload or php artisan queue:restart depending on runtime setup.
8. Verify /up.
9. Verify login, tenant selection, queue dispatch, and audit write on staging.

Queue Worker Checklist

Do not use queue:listen for production workers.

Recommended baseline:

php artisan queue:work database --queue=high,default,graph,restore,reports,notifications --sleep=3 --tries=3 --timeout=300

When Redis is enabled:

php artisan queue:work redis --queue=high,default,graph,restore,reports,notifications --sleep=3 --tries=3 --timeout=300

Rules:

• Use process supervision so exited workers restart.
• Keep worker --timeout lower than queue retry_after.
• Reload/restart workers on deploy.
• Track queue depth and failed jobs.
• Run destructive restore/backups in separate queues when volume grows.

Scheduler Checklist

• One scheduler instance per environment.
• Use Laravel scheduler with withoutOverlapping() for recurring jobs.
• Monitor last successful scheduler tick and per-command failures.
• Long-running scheduled work dispatches jobs rather than doing Graph work inline.

Migration Checklist

• Review locks and table size before staging.
• Backfill in chunks where needed.
• Avoid irreversible destructive schema changes after production unless forward-only rollback is documented.
• JSON to JSONB conversions need staging timing proof.
• Composite FK and partial index changes need PostgreSQL CI/staging validation.

Rollback Checklist

• Keep previous image available.
• Know whether rollback is code-only or code+schema.
• For forward-only migrations, ship a forward fix instead of unsafe down migration.
• Pause workers before risky rollback if queued payload formats changed.
• Verify audit logs and operation runs remain readable.

Backup/Restore Checklist

• Database backups encrypted.
• Storage backups encrypted.
• Provider credentials excluded from logs and exports.
• Restore tested on staging from a real backup.
• Backup retention and deletion documented.
• Restore runbook includes queue/scheduler coordination.

Monitoring Checklist

• /up uptime check.
• Laravel logs and container logs centralized.
• Queue failures and long-running jobs alerted.
• Scheduler missed-run alert.
• Database connections, slow queries, disk, and backup freshness monitored.
• Graph 429/503 rates visible.
• Error tracking integrated before production.

Dokploy Notes

• Treat Dokploy as the process/orchestration layer, not as application governance.
• Ensure web, queue, and scheduler processes are separate service definitions or entrypoints.
• Persist storage/, database volumes, and uploaded/private files.
• Do not bake .env into images.