Appendix: Environment Variables and Directories
This appendix provides a deployment reference for services, directories, environment variables, ports, validation commands, and glossary terms. It is intended for implementation and handover use.
Service List
| Service | Required | Purpose |
|---|---|---|
frontend | Yes | NGINX-served React UI and /api/ proxy. |
backend | Yes | FastAPI application and main API runtime. |
postgres | Yes | PostgreSQL database. |
gotenberg | Yes | Document conversion for preview workflows. |
preview-worker | Yes in production Compose paths | Preview job processing. |
index-worker | Yes in production Compose paths | OCR, search indexing, and retrieval/index processing. |
Directory List
| Directory / path | Purpose | Production note |
|---|---|---|
/srv/edms/volumes/postgres | Linux PostgreSQL data | Must be durable and backed up through a database-aware process. |
/srv/edms/volumes/uploads | Linux uploaded documents | Must be included in backup and capacity planning. |
/srv/edms/volumes/previews | Linux preview artifacts | Can be regenerated in some cases but should be protected for operational continuity. |
/srv/edms/volumes/faiss | Linux search/RAG/index artifacts | Include in backup or plan reindex time. |
/srv/edms/volumes/backups | Linux backup output | Prefer off-host/off-site copy. |
/srv/edms/volumes/licensing | Linux licensing state | Must be preserved. |
C:/ProgramData/DeskDox | Windows deploy-kit DATA_ROOT | Contains production data paths under the deploy-kit model. |
Environment Variable Reference
Application and Public URL
| Variable | Purpose | Production note |
|---|---|---|
IMAGE_TAG | Container image version | Pin to the target release. |
DEBUG | Runtime debug behavior | Production should be false. |
FRONTEND_URL / PUBLIC_URL | Public application URL | Must be the real FQDN, not a local-only URL. |
ALLOWED_ORIGINS / CORS_ORIGINS | Browser origin allow-list | Verify actual runtime behavior during validation. |
EDMS_AUTO_SEED | Automatic seed behavior | Should be disabled for production (0 or unset). |
Database
| Variable | Purpose | Production note |
|---|---|---|
POSTGRES_DB | Database name | Present in production templates. |
POSTGRES_USER | Database user | Use deployment-specific credentials. |
POSTGRES_PASSWORD | Database password | Must be strong and secret. |
DATABASE_URL | Backend database connection | Compose uses service host postgres. |
POSTGRES_CONTAINER_NAME | Backup/restore container reference | Used by deploy-kit and backup tooling contexts. |
Security and Authentication
| Variable | Purpose | Production note |
|---|---|---|
JWT_SECRET_KEY | Token signing secret | Must be unique, random, and protected. |
JWT_ALGORITHM | Token signing algorithm | Template value is HS256. |
ACCESS_TOKEN_EXPIRE_MINUTES | Session/token lifetime | Set according to customer security policy. |
| Variable | Purpose | Production note |
|---|---|---|
SMTP_HOST, SMTP_PORT | SMTP relay endpoint | Required when email is in scope. |
SMTP_USER, SMTP_PASSWORD | SMTP credentials | Handle as secrets. |
EMAIL_FROM | Default sender address | Should align with the customer email domain and relay policy. |
SMTP_SEND_TIMEOUT_SECONDS | SMTP socket timeout | Default in backend example is 30 seconds. |
Converter, Storage, and Workers
| Variable | Purpose | Production note |
|---|---|---|
CONVERTER_URL | Gotenberg endpoint | In Docker Compose, http://gotenberg:3000. |
CONVERTER_TIMEOUT_SECONDS | Conversion timeout | Template default is 120. |
OCR_ENABLED | OCR enablement | Default production templates enable OCR. |
TESSERACT_CMD | Tesseract executable path | Linux Compose sets /usr/bin/tesseract; Windows can auto-detect or configure. |
TESSERACT_LANG | OCR language | Template default is eng. |
OCR_MAX_PAGES | OCR page limit | Template default is 10. |
INDEX_WORKER_ENABLED | Index worker behavior | Dedicated worker container sets this to true. |
PREVIEW_WORKER_ENABLED | Preview worker behavior | Dedicated worker container sets this to true. |
DATA_ROOT | Windows deploy-kit data root | Default C:/ProgramData/DeskDox. |
HTTP_PORT, HOST_BIND_IP | Windows frontend binding | Default 8088 and 0.0.0.0; review exposure. |
Backup and Licensing
| Variable | Purpose | Production note |
|---|---|---|
BACKUP_ROOT | Backup output path | Must have sufficient capacity and protection. |
BACKUP_ENCRYPTION_KEY | Backup encryption key | Store separately from backup archives. |
BACKUP_WORKER_ENABLED | Backup worker enablement | Template default is true. |
BACKUP_RETENTION_DAILY, BACKUP_RETENTION_WEEKLY, BACKUP_RETENTION_MONTHLY | Retention controls in backend settings | Defaults in config.py are 7 daily, 4 weekly, and 12 monthly. |
LICENSE_DATA_DIR | Licensing data path | Mounted in production Compose. |
AI, Emii, WhatsApp, and Optional Redis URL
| Variable | Purpose | Production note |
|---|---|---|
LLM_ENABLED, EMII_ENABLED, RAG_ENABLED, AI_EXTERNAL_ENABLED | AI/Emii features | Confirm customer data handling and outbound access before enabling. |
OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL | OpenAI-compatible AI integration | Required only for cloud AI features. |
AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT | Azure OpenAI integration | Required only for Azure OpenAI mode. |
OLLAMA_BASE_URL, OLLAMA_MODEL | Local LLM integration | Required only for Ollama mode. |
WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_ACCESS_TOKEN, WHATSAPP_APP_SECRET, WHATSAPP_VERIFY_TOKEN | WhatsApp Cloud API | Required only when WhatsApp integration is enabled. |
REDIS_URL | Optional AI/WhatsApp state or rate-limit backing | No Redis service is present in the current production Compose baseline. |
Validation Commands
Use commands only in implementation or handover contexts.
docker compose -f docker-compose.prod.yml --env-file .env.prod config
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
.\deploy-kit\scripts\healthcheck.ps1
.\deploy-kit\scripts\backup.ps1 -Tag "validation"
Glossary
| Term | Meaning |
|---|---|
| FQDN | Fully qualified domain name used as the production DeskDox URL. |
| RPO | Recovery Point Objective; maximum acceptable data loss measured in time. |
| RTO | Recovery Time Objective; maximum acceptable recovery duration. |
| Gotenberg | Conversion service used by DeskDox for preview workflows. |
| FAISS | Local vector/index artifact storage used by retrieval/search-related features. |
| OCR | Optical character recognition for scanned or image-based documents. |
| Deploy-kit | Windows-oriented deployment package containing Compose, configuration, scripts, and installer assets. |