ahmido
d43ebcb4ee
Added PDF generation service for management reports as per Spec 378, including Gotenberg integration in docker-compose and configuration updates. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #449
116 lines
5.0 KiB
Markdown
116 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
php artisan queue:work database --queue=high,default,graph,restore,reports,notifications --sleep=3 --tries=3 --timeout=300
|
|
```
|
|
|
|
When Redis is enabled:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## PDF Renderer Checklist
|
|
|
|
Spec 378 approves Gotenberg 8 Chromium only as an internal renderer service for report-style PDFs.
|
|
|
|
- Use a pinned `gotenberg/gotenberg:8.34.0-chromium` image or an explicitly reviewed immutable digest.
|
|
- Keep the renderer on the internal Dokploy/container network only; do not publish a public port.
|
|
- Configure `/health` monitoring for the renderer service.
|
|
- Set `TENANTPILOT_PDF_RENDERER_BASE_URL` to the internal service URL, for example `http://gotenberg:3000`.
|
|
- Set explicit renderer timeouts and limits: `TENANTPILOT_PDF_RENDERER_TIMEOUT_SECONDS`, `TENANTPILOT_PDF_RENDERER_CONNECT_TIMEOUT_SECONDS`, `TENANTPILOT_PDF_RENDERER_MAX_HTML_BYTES`, `TENANTPILOT_PDF_RENDERER_MAX_ASSET_BYTES`, and `TENANTPILOT_PDF_RENDERER_MAX_OUTPUT_BYTES`.
|
|
- Set matching Gotenberg service controls: `API_TIMEOUT`, `API_BODY_LIMIT`, `API_CORRELATION_ID_HEADER`, `CHROMIUM_START_TIMEOUT`, `CHROMIUM_MAX_QUEUE_SIZE`, and `CHROMIUM_MAX_CONCURRENCY`.
|
|
- Keep `API_DISABLE_DOWNLOAD_FROM=true`, `WEBHOOK_DISABLE=true`, `CHROMIUM_ALLOW_LIST=^$`, `CHROMIUM_DENY_PRIVATE_IPS=true`, and `CHROMIUM_DENY_PUBLIC_IPS=true` unless a later spec approves external asset fetches.
|
|
- Do not install Node, Puppeteer, Chrome, Chromium, or browser binaries in Laravel web or queue containers for production PDF rendering.
|
|
|
|
## 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.
|