Deployment Guides
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The deployment guides for tldw_server provide a comprehensive framework for transitioning the application from a development environment to a production-ready state. These guides are targeted at DevOps engineers, SREs, and self-hosters who need to ensure the system is secure, scalable, and maintainable over the long term. The scope includes initial setup procedures, choice of infrastructure (Docker vs. Bare-Metal), and day-2 operational tasks such as monitoring, backups, and upgrades.
The deployment architecture centers around a FastAPI backend that interacts with various databases (SQLite or PostgreSQL) and vector stores (ChromaDB), typically managed via Docker Compose for rapid orchestration. High-level deployment strategies prioritize security through explicit CORS configuration, TLS termination via reverse proxies, and robust authentication modes.
Sources: Docs/Deployment/First_Time_Production_Setup.md:3-10, Docs/Architecture.md:33-51, AGENTS.md:12-28
Infrastructure Options
The project supports two primary deployment pathways depending on the intended scale and management requirements.
Docker Compose (Recommended)
Docker Compose is the recommended path for the fastest secure start on a single host. It simplifies the orchestration of the API server, database, and sidecar workers.
- Single-user Docker: Targeted at personal use with simplified API key authentication.
- Multi-user Docker + Postgres: Targeted at teams or public deployments requiring JWT-based auth and robust relational data management.
Bare-Metal (systemd + Nginx)
For environments requiring package-managed services or specific OS integration, a bare-metal setup is provided. This typically involves using systemd for process supervision on Linux and Nginx or Caddy as a reverse proxy for TLS termination.
Sources: Docs/Deployment/First_Time_Production_Setup.md:30-49, Docs/Deployment/Long_Term_Admin_Guide.md:14-25
The following flowchart illustrates the high-level decision process for selecting a deployment mode:
The diagram shows the logic for selecting between Docker and Bare-Metal based on speed, integration needs, and user scale.
Sources: Docs/Deployment/First_Time_Production_Setup.md:25-50
Configuration Essentials
Deployment requires careful configuration of environment variables to ensure security and proper module integration.
| Variable | Description | Recommended Production Value |
|---|---|---|
AUTH_MODE | Determines auth logic | single_user or multi_user |
SINGLE_USER_API_KEY | Secret key for personal mode | High-entropy random string |
JWT_SECRET_KEY | Secret for signing JWTs | Result of openssl rand -base64 64 |
DATABASE_URL | Connection string for AuthNZ | PostgreSQL URL for multi-user |
ALLOWED_ORIGINS | CORS restriction | Explicit domain list (e.g., https://myapp.com) |
tldw_production | Production hardening flag | true (masks secrets in logs) |
UVICORN_WORKERS | Number of worker processes | 4 (default), tune based on CPU/RAM |
Sources: Docs/Deployment/First_Time_Production_Setup.md:52-60, Docs/Deployment/Long_Term_Admin_Guide.md:108-115
Day-2 Operations and Maintenance
Once the server is running, administrators must manage ongoing maintenance tasks to ensure stability.
Upgrades and Rollbacks
The project follows a "pull and rebuild" strategy for Docker deployments. It is critical to back up databases before any update.
- Pull latest changes via
git pull. - Rebuild the app:
docker compose build app. - Restart services:
docker compose up -d. - Verify health via
GET /healthandGET /readyendpoints.
Sources: Docs/Deployment/Long_Term_Admin_Guide.md:34-45, Docs/Release_Checklist.md:175-185
Backup and Restore
Administrators must manage several persistent data sources:
- AuthNZ DB: Centralized database (
users.dbor Postgres). - Content DBs: Per-user media and metadata stored under
<USER_DB_BASE_DIR>/<user_id>/. - Vector Stores: ChromaDB data directories.
- Config:
.envandconfig.txtfiles.
The diagram illustrates the different backup strategies required for relational, file-based, and encrypted data.
Sources: Docs/Deployment/Long_Term_Admin_Guide.md:51-70, Docs/Architecture.md:144-155
Monitoring and Observability
Production deployments should leverage the built-in health and metrics endpoints for proactive monitoring.
Health Endpoints
GET /health: Basic application health check.GET /ready: Readiness check for traffic routing.GET /api/v1/admin/circuit-breakers: Admin-only view of system resilience status.
Metrics Stack
tldw_server exports Prometheus-compatible metrics via GET /metrics. These include HTTP error rates, latency, LLM provider costs, and database connection pool saturation.
Sources: Docs/Deployment/Long_Term_Admin_Guide.md:82-95, Docs/Release_Checklist.md:231-238
Troubleshooting Common Issues
| Issue | Symptom | Potential Fix |
|---|---|---|
| Proxy Timeouts | 502/504 Errors | Increase reverse proxy timeouts; check WebSocket upgrade rules. |
| DB Locks | "Database is locked" | Enable WAL mode for SQLite or migrate to PostgreSQL. |
| Auth Failures | 401 Unauthorized | Verify AUTH_MODE in .env matches the provided header (X-API-KEY or Bearer). |
| Resource Saturation | Slow response times | Tune UVICORN_WORKERS or TLDW_DB_POOL_SIZE. |
Sources: Docs/Deployment/Long_Term_Admin_Guide.md:154-175, Docs/Release_Checklist.md:200-210
Conclusion
The tldw_server deployment guides provide a robust path from a single-user local instance to a multi-tenant production environment. By following the recommended Docker Compose orchestration, implementing strict environment-based configuration, and establishing a regular cadence for backups and monitoring, administrators can maintain a secure and high-performing research assistant platform. Core focus should remain on the "Production Hardening Checklist" to ensure all security guards, such as secret masking and CORS restrictions, are properly active.
Sources: Docs/Deployment/First_Time_Production_Setup.md:73-86, Docs/Deployment/Long_Term_Admin_Guide.md:195-205