Introduction to GoCasa
Relevant source files
The following files were used as context for generating this wiki page:
GoCasa is a self-hosted family calendar dashboard. It provides a shared space for households to manage calendars, to-dos, shopping lists, and chores. The system runs as a single static Go binary and stores all data in a single SQLite file with a server-rendered user interface.
Sources: README.md:3-5, GLOSSARY.md:1-4
System Architecture
GoCasa uses a simplified architecture to ensure easy self-hosting. It functions as a standalone web server that interacts with a local SQLite database.
This diagram shows the request flow from the user to the GoCasa backend and its interaction with the database and external integrations.
Sources: README.md:7-14, internal/app/app.go:76-105
Core Components
- Web Server: Listens on a configurable address (defaulting to
:8080) and serves plain HTTP. - Database: Uses SQLite for persistence. The binary manages its own migrations and automated backups.
- Scheduler: Runs background tasks such as integration synchronization and database maintenance.
- Templates: Utilizes
a-h/templfor server-side rendering of the user interface.
Sources: cmd/gocasa/main.go:94-106, internal/app/app.go:68-81, internal/web/home_templ.go:1-10
Core Concepts and Terminology
GoCasa uses specific terms to define the relationships between users and the system data.
| Term | Definition |
|---|---|
| Household | The single family unit that one GoCasa instance serves. |
| Member | A person or pet belonging to the Household. |
| Admin | A Member with permission to change settings and integrations; requires a PIN. |
| Lock | A rule requiring an Admin PIN for specific actions like editing the calendar. |
| Archived Member | A Member who left the Household but remains in historical records. |
Sources: GLOSSARY.md:7-35
System Startup and Configuration
The binary initializes by loading configuration from environment variables. It then prepares the data directory, opens the database, and executes pending migrations before starting the HTTP server.
This sequence diagram illustrates the initialization steps the binary performs at startup.
Sources: cmd/gocasa/main.go:79-112, internal/app/app.go:50-85
Configuration Variables
GoCasa configures itself through environment variables only.
| Variable | Default | Requirement | Description |
|---|---|---|---|
ADDR | :8080 | Optional | The address where the server listens. |
BASE_URL | - | Required | The full URL (e.g., https://casa.example.com) for links and cookies. |
DATA_DIR | /data | Optional | Location for app.db and backups. |
TZ | UTC | Optional | Default IANA timezone for the Household. |
APP_ENCRYPTION_KEY | - | Required | 32 base64-encoded bytes used to encrypt tokens at rest. |
SESSION_SECRET | - | Required | Minimum 32 characters for session security. |
Sources: README.md:19-33, internal/config/config.go:21-68
Data Management
GoCasa automates database maintenance to prevent data loss.
Backups and Restore
The application performs a VACUUM INTO command every day at 03:00 (based on the configured TZ). It maintains the latest 14 backups in the /data/backups/ directory. Before any schema migration, the system creates a mandatory pre-migration backup. If this backup fails, the application refuses to start to protect existing data.
Sources: README.md:37-45, internal/app/app.go:60-67
Migrations
Database migrations are embedded within the binary. GoCasa tracks the schema version using SQLite's PRAGMA user_version. The application refuses to start if it detects a database version newer than what the binary supports, preventing data corruption from downgrades.
Sources: README.md:52-58, internal/app/app_test.go:34-43
Integrations and Syncing
The Scheduler manages external data synchronization. It processes enabled integrations such as iCal feeds or Google accounts.
- Integrations: Logic for syncing is defined by the
Integrationinterface. - Sync Interval: Each integration has a specific interval. If a sync fails, the system applies an exponential backoff (doubling each time) up to a maximum of 6 hours.
- Security: API keys and OAuth tokens are encrypted using AES-256-GCM with the
APP_ENCRYPTION_KEY.
Sources: internal/app/integrations.go:13-30, internal/app/integrations.go:76-90
Conclusion
GoCasa provides a centralized, self-hosted hub for household management. By utilizing a single-binary approach with automated SQLite management, it simplifies the deployment of a family dashboard while ensuring data security through mandatory encryption and automated backup cycles.
Sources: README.md:3-5, GLOSSARY.md:1-5