Docker Compose Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Compose setup for the Syllogic personal finance application provides a containerized orchestration layer for a two-service architecture. It manages the lifecycle of the Next.js frontend, FastAPI backend, and supporting infrastructure including PostgreSQL and Redis. This setup is designed to handle both local development environments and production-grade self-hosted deployments.
Sources: CLAUDE.md:10-25, deploy/compose/README.md:3-10
Infrastructure Architecture
The application relies on a multi-container strategy to separate concerns between the UI, data processing, and persistence layers. The architecture is unified by a shared PostgreSQL database and a Redis instance used for task queuing.
The diagram above illustrates the service interdependencies. The Caddy reverse proxy routes external traffic, while services like migrate and uploads-init perform one-shot initialization tasks.
Sources: deploy/compose/docker-compose.yml:5-130, README.md:75-95
Core Services
Database and Cache
The system uses PostgreSQL 16 as the primary datastore, shared between the frontend (via Drizzle ORM) and backend (via SQLAlchemy). Redis 7 serves as the message broker for Celery-based background jobs and caching.
- Postgres: Initialized with custom user/database credentials. Health is verified using
pg_isready. - Redis: Configured with
--appendonly yesfor data persistence.
Sources: deploy/compose/docker-compose.yml:5-28, CLAUDE.md:65-73
Application Services
The application is split into specialized containers to handle different workloads:
| Service | Image/Context | Responsibility |
|---|---|---|
app | Frontend (Next.js) | Serves the UI and handles CRUD via Server Actions. |
backend | Backend (Python) | Transaction enrichment and merchant identification. |
worker | Backend (Python) | Executes asynchronous Celery tasks. |
beat | Backend (Python) | Schedules recurring cron jobs (e.g., daily syncs). |
mcp | Backend (Python) | FastMCP server for Claude Desktop integration. |
Sources: deploy/compose/docker-compose.yml:58-130, README.md:120-140
Initialization and Lifecycle
The Docker Compose setup includes specialized services that run to completion before the main application starts.
Migration Logic
Database migrations are handled by the migrate service, which runs node scripts/migrate.js using the frontend image. Other services like backend and app use the depends_on property with service_completed_successfully to ensure the schema is ready before they boot.
Volume Management
The configuration uses named volumes to persist data across container restarts:
postgres_data: Stores the SQL database files at/var/lib/postgresql/data.redis_data: Stores the Redis AOF files at/data.uploads_data: Stores user-uploaded CSVs and profile photos at/app/public/uploads.
The uploads-init service is a one-shot container that ensures the /uploads directory exists and has the correct permissions (UID 1000:1000) before the application attempts to write to it.
Sources: deploy/compose/docker-compose.yml:30-36, deploy/compose/docker-compose.yml:157-162
Environment Configuration
Deployment requires an .env file containing critical secrets and networking parameters.
| Variable | Description | Default/Example |
|---|---|---|
DATABASE_URL | Full PostgreSQL connection string | postgres://user:pass@postgres:5432/db |
BETTER_AUTH_SECRET | Secret for authentication signing | (Generated via openssl) |
INTERNAL_AUTH_SECRET | Shared secret for app-to-backend auth | (Generated via openssl) |
APP_URL | The public-facing URL of the application | http://localhost:8080 |
MCP_PORT | External port for the MCP server | 8001 |
Sources: deploy/compose/README.md:12-25, deploy/compose/docker-compose.yml:132-155
Deployment Variants
The project supports multiple environment-specific Compose configurations:
- Production (Standard): Uses
deploy/compose/docker-compose.ymlwith prebuilt GHCR images. Includes a Caddy reverse proxy for TLS. - Local Build: Uses
deploy/compose/docker-compose.local.ymlas a layer to build images from the current local source code instead of pulling from GHCR. - Railway: Uses
deploy/railway/docker-compose.yml. Optimized for Railway's shared variable system, omitting Caddy as Railway provides its own proxy. - CasaOS: Uses
deploy/casaos/docker-compose.ymlwith specificx-casaosmetadata for the CasaOS App Store.
Sources: deploy/compose/README.md:27-34, deploy/railway/docker-compose.yml:20-35, deploy/casaos/docker-compose.yml:1-10
Summary
The Docker Compose setup encapsulates the entire Syllogic ecosystem, ensuring that infrastructure (Postgres/Redis), data migrations, and the two-service application stack are deployed in a coordinated manner. By leveraging one-shot initialization containers and strict dependency ordering, it provides a stable environment for both development and production use cases.