CasaOS Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The CasaOS deployment module provides a pre-configured Docker Compose bundle designed for seamless integration with the CasaOS App Store. This deployment path allows users to self-host the Syllogic personal finance platform on local network hardware with automated management of the multi-service architecture.
The system utilizes a two-service architecture—comprised of a Next.js frontend and a FastAPI backend—sharing a unified PostgreSQL database and Redis cache. The CasaOS implementation specifically focuses on local accessibility, persistent storage mapping to the /DATA/AppData/ directory, and internal API proxying.
Sources: deploy/casaos/README.md:3-5, CLAUDE.md:5-10, README.md:126-128
Architecture Overview
The CasaOS deployment orchestrates eight distinct containers to ensure full system functionality, ranging from core application services to background workers and infrastructure components.
Service Relationships
The following diagram illustrates the connectivity and dependency flow between the CasaOS services:
The architecture separates persistent data (Postgres/Redis) from ephemeral application logic, with a Caddy reverse proxy acting as the primary entry point for web traffic.
Sources: deploy/casaos/docker-compose.yml:4-220, CLAUDE.md:14-31
Components and Services
Core Infrastructure
- Postgres (v16-alpine): The primary relational store. In CasaOS, data is bound to
/DATA/AppData/$AppID/postgres. - Redis (v7-alpine): Handles job queuing and caching for Celery workers.
Application Layer
- Frontend (Next.js): Handles UI, authentication via BetterAuth, and CRUD operations. It listens internally on port 3000.
- Backend (FastAPI): Manages the data pipeline, transaction enrichment, and integrations.
- MCP Server: A FastMCP server exposed on port 8001 (default) for programmatic access and AI tool integration.
Background Processing
- Celery Worker: Executes asynchronous tasks like transaction categorization and bank syncing with a concurrency of 4.
- Celery Beat: A scheduler that triggers periodic tasks defined in the backend.
Sources: deploy/casaos/docker-compose.yml:4-150, README.md:130-145
Deployment Configuration
Required Environment Variables
Before starting the stack, several critical secrets must be configured to ensure database security and authentication integrity.
| Variable | Description | Source |
|---|---|---|
POSTGRES_PASSWORD | Secure password for the PostgreSQL database. | docker-compose.yml:12 |
BETTER_AUTH_SECRET | Secret used to sign authentication sessions. | README.md:300 |
INTERNAL_AUTH_SECRET | Shared secret for signed requests between Frontend and Backend. | deploy/casaos/README.md:14 |
APP_URL | The public or local IP address used to access the UI. | deploy/casaos/README.md:15 |
Sources: deploy/casaos/README.md:11-16, deploy/casaos/docker-compose.yml:164-173
Storage and Volumes
CasaOS deployments use specific bind mounts to ensure data persists across container updates within the CasaOS filesystem structure.
| Container Path | Host Path (CasaOS) | Description |
|---|---|---|
/var/lib/postgresql/data | /DATA/AppData/$AppID/postgres | Database records |
/data | /DATA/AppData/$AppID/redis | Cache and queue data |
/app/public/uploads | /DATA/AppData/$AppID/uploads | User uploads and CSV imports |
/etc/caddy | /DATA/AppData/$AppID/caddy | Proxy configuration |
Sources: deploy/casaos/docker-compose.yml:15-17, deploy/casaos/docker-compose.yml:181-183
Network Logic and Proxying
The deployment includes a Caddy container that manages traffic routing. This is critical because API routes must be proxied through the frontend (/api/*) or directly to the backend (/api/health) to maintain internal signed authentication.
Installation Procedure
- Preparation: Open the CasaOS App Store and select "Custom Install".
- Environment Setup: Copy
.env.exampleto.envand generate hex secrets usingopenssl rand -hex 32. - App Versioning: By default,
APP_VERSIONis set toedgeto track the latest main image. For stability, this should be pinned to a specific release tag (e.g.,v1.2.3). - Execution: Use the CasaOS UI to start the stack or execute manually via terminal:
cd deploy/casaos docker compose up -d
Sources: deploy/casaos/README.md:7-17, deploy/compose/README.md:12-16, deploy/install/install.sh:65-72
Summary
The CasaOS Deployment module provides a robust, self-contained environment for Syllogic. It leverages Docker Compose to manage dependencies, Caddy for internal routing, and specific CasaOS volume mappings for persistent financial data. By configuring the necessary auth secrets and storage paths, developers can deploy a production-ready instance on local home-server hardware.