Deployment Validation and Troubleshooting
Deployment troubleshooting should begin with service health, configuration correctness, storage availability, and network reachability before investigating application-specific behavior.
Validation Sequence
| Step | Expected result |
|---|---|
| Compose validation | Compose file renders successfully with the selected environment file. |
| Container status | frontend, backend, postgres, gotenberg, preview-worker, and index-worker are running. |
| Health checks | Frontend and backend health checks pass; PostgreSQL and Gotenberg are healthy. |
| Public URL | Production FQDN loads the application over HTTPS. |
| Login | Admin and non-admin accounts can authenticate. |
| Upload | Test files upload successfully. |
| Preview | Representative PDF and Office documents preview correctly. |
| OCR/search | Indexed documents can be found after worker processing. |
| Workflow | A representative workflow can be completed. |
| SMTP test and live notification/document email work if enabled. | |
| Backup | Manual or scheduled backup completes and writes to the configured location. |
| Restore review | Restore is tested or a deferred validation plan is recorded. |
Common Issue Matrix
| Symptom | Likely area | Initial checks |
|---|---|---|
| Frontend not reachable | DNS, TLS, firewall, frontend container | Confirm FQDN, certificate, port binding, reverse proxy target, frontend health. |
| Login page loads but API calls fail | NGINX proxy, backend, CORS/public URL | Confirm /api/ proxy, backend health, FRONTEND_URL, allowed origins. |
| Backend unhealthy | Database, required env vars, migrations, startup settings | Check DATABASE_URL, JWT_SECRET_KEY, CONVERTER_URL, production guards, migration logs. |
| Database connection failure | PostgreSQL, credentials, network | Confirm postgres container health, credentials, DATABASE_URL, internal DNS name. |
| Previews fail | Gotenberg, preview worker, storage permissions | Confirm Gotenberg health, CONVERTER_URL, worker status, upload/preview paths. |
| OCR/search delayed | Index worker, Tesseract, workload | Confirm index worker running, OCR_ENABLED, TESSERACT_CMD, queue volume, CPU. |
| Email links use wrong URL | Public URL configuration | Confirm FRONTEND_URL or PUBLIC_URL and application settings. |
| SMTP fails | Relay, credentials, firewall, TLS policy | Confirm host, port, user/password, outbound firewall, relay allow-list, and test recipient. |
| Backup fails | Backup path, Docker access, permissions, encryption key | Confirm BACKUP_ROOT, available disk, key presence, write permissions, and deployment-specific backup method. |
| Restore fails | Backup integrity, destructive restore sequence, service state | Validate backup contents, database dump, data paths, restore procedure, and available disk. |
Implementation Notes
Linux compose diagnostics:
docker compose -f docker-compose.prod.yml --env-file .env.prod ps
docker compose -f docker-compose.prod.yml --env-file .env.prod logs --tail 100 backend
docker compose -f docker-compose.prod.yml --env-file .env.prod logs --tail 100 preview-worker
docker compose -f docker-compose.prod.yml --env-file .env.prod logs --tail 100 index-worker
Windows deploy-kit diagnostics:
.\deploy-kit\scripts\healthcheck.ps1
docker compose -f .\deploy-kit\compose\docker-compose.production.yml --env-file .\deploy-kit\.env ps
Commands should be executed by authorized deployment or operations personnel.
Escalation Data
For support escalation, collect:
- Deployment model and OS.
- DeskDox image tag/release.
- Compose file path and sanitized environment summary.
- Container status and health.
- Relevant logs with secrets removed.
- Public URL and reverse proxy pattern.
- Recent change history.
- Backup/restore status if data recovery is involved.
- Exact user-facing error and timestamp.
Troubleshooting Boundary
DeskDox support can assist with application behavior, container configuration, documented deployment scripts, and product-level validation. Customer infrastructure teams own DNS, TLS, reverse proxy, firewall, host OS, Docker runtime installation, endpoint security policy, storage health, SMTP relay, external API availability, and enterprise monitoring platforms.