Operations & troubleshooting
Deployment, backup, logs and the most common errors.
VeloStack runs as a single FastAPI application with PostgreSQL. Updates are rolled out with migration, health check and smoke test; no backup, no update.
Deployment
- Back up database and secrets.
- Deploy the new version.
- Run
alembic upgrade head. - Check
GET /healthandGET /health/timers. - Smoke test: login, marketplace search, one order in dry-run.
Backup
Back up PostgreSQL with pg_dump, store .env and keys separately. Test a restore regularly, do not just document it. Copy SQLite files only while stopped.
Logs
- App log for errors and slow queries.
/health/timersfor sync and timer status.- Dispatch audit for orders.
- n8n execution log for forwarding.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 401/411 on VeloConnect | Wrong credentials or tenant | Check connection and tenant |
| 415 on VeloConnect | Unknown SellersID | Check the connection's seller ID |
| Sync without new items | Filter, interval or timeout | Check run and profile, start manually |
| PDF marked DRAFT | Recipient data missing | Complete tenant master data |
| Dispatch failed | Channel, credentials or target unreachable | Check dry-run and channel config |