Docker Compose Deployment
Relevant source files
The following files were used as context for generating this wiki page:
GoCasa uses Docker Compose to provide a portable, self-hosted environment for the family dashboard. This deployment method packages the Go binary and its SQLite database into a containerized service that handles its own data persistence and health monitoring.
The deployment relies on environment variables for configuration and a persistent volume for data storage. It expects a reverse proxy to handle HTTPS termination, as the application serves plain HTTP by default.
Sources: README.md:1-10, README.md:65-67
Deployment Architecture
The deployment consists of a single application container interacting with a persistent volume. The GoCasa binary includes built-in migration logic and a backup scheduler that runs automatically within the container environment.
The diagram shows the relationship between the external request flow, the internal container logic, and the persistent data storage.
Sources: README.md:15-18, internal/app/app.go:73-85, cmd/gocasa/main.go:88-92
Configuration Environment
GoCasa configuration comes exclusively from environment variables. The application refuses to start if required values are missing or malformed.
| Variable | Requirement | Description |
|---|---|---|
ADDR | Optional | Listen address (Default: :8080). |
BASE_URL | Required | The external URL used by clients. Drives cookies and OAuth redirects. |
DATA_DIR | Optional | Directory for app.db and backups (Default: /data). |
TZ | Optional | Household IANA time zone (Default: UTC). |
APP_ENCRYPTION_KEY | Required | 32-byte base64 key for encrypting OAuth tokens and API keys. |
SESSION_SECRET | Required | String of at least 32 characters for session security. |
Sources: README.md:22-34, internal/config/config_test.go:23-45
Data Persistence and Permissions
GoCasa stores all state in a single SQLite file named app.db within the DATA_DIR.
Volume Management
The application uses a Docker volume named gocasa-data mounted at /data. This volume contains:
app.db: The primary SQLite database.backups/: Automated daily database backups.photos/andphoto-cache/: Storage for screensaver images (future use).
Container User and Permissions
The container runs as UID 65532. If you use a host bind mount instead of a named volume, you must change the host directory ownership:
sudo chown 65532:65532 ./data
Sources: README.md:15-19, internal/app/app.go:66-68
Lifecycle Operations
The GoCasa binary manages its own lifecycle tasks, including health checks and database maintenance, during the container's runtime.
Startup and Migrations
When the container starts, GoCasa performs the following sequence:
- Validates all environment variables.
- Initializes the
DATA_DIR. - Checks the SQLite
PRAGMA user_version. - Executes a pre-migration backup if upgrades are pending.
- Runs migrations in order, each within a single transaction.
The sequence diagram illustrates the internal initialization process before the application begins serving traffic.
Sources: internal/app/app.go:73-85, README.md:46-55, cmd/gocasa/main.go:80-92
Health Monitoring
The container includes a native health check mechanism. The binary contains a healthcheck command that probes the internal /healthz endpoint. This endpoint returns 200 OK only if the application is running and the database is responsive.
Sources: cmd/gocasa/main.go:37-60, internal/app/app.go:121-131
Automated Backups
The internal scheduler performs a VACUUM INTO command daily at 03:00 in the configured TZ. The system keeps the 14 most recent backups. If GoCasa starts and the newest backup is older than 24 hours, it triggers an immediate backup.
Sources: README.md:36-40, internal/app/app.go:94-96
Administrative Utilities
Docker Compose allows running administrative tasks through the docker exec command using the GoCasa binary's built-in CLI flags.
- PIN Reset: If an Admin loses their PIN, you can generate a new one via the container:
docker compose exec gocasa /gocasa reset-pin <Admin_Name> - Database Restore: To restore a backup, you must stop the container, replace
app.db, and delete the Write-Ahead Log (app.db-wal) and shared memory (app.db-shm) files.
Sources: cmd/gocasa/main.go:64-85, README.md:41-44
GoCasa deployment focuses on a "one binary, one database" philosophy. By managing migrations and backups internally, the Docker Compose deployment ensures data integrity while remaining compatible with standard reverse proxies for secure HTTPS access.