Configuration Options

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/config/config.go
• internal/config/config_test.go
• internal/app/app.go
• cmd/gocasa/main.go
• internal/db/migrations/0006_integrations.sql

GoCasa uses environment variables as the exclusive mechanism for system configuration. The application does not support configuration files. Upon startup, the binary validates all required environment variables and terminates immediately if any values are missing or malformed. Sources: README.md:19-19, internal/config/config.go:7-7

Core System Configuration

The core configuration defines the networking, storage, and security parameters of the GoCasa instance. These values are loaded into a Config struct during the initialization phase of the application. Sources: internal/config/config.go:19-26, cmd/gocasa/main.go:81-84

Environment Variables

Variable	Default	Requirement	Description
ADDR	:8080	Optional	The TCP address for the HTTP server to listen on.
BASE_URL	None	Required	The absolute public URL (http/https). Used for cookies and OAuth redirects.
DATA_DIR	/data	Optional	Directory for the SQLite database (app.db) and backups.
TZ	UTC	Optional	Default IANA time zone for the household (e.g., America/Los_Angeles).
APP_ENCRYPTION_KEY	None	Required	32-byte base64 string for encrypting OAuth tokens and API keys at rest.
SESSION_SECRET	None	Required	String of at least 32 characters for securing user sessions.

Sources: README.md:21-31, internal/config/config.go:30-66

Configuration Loading Flow

The following diagram illustrates the sequence from environment variable detection to application initialization.

The application validates types and constraints, such as ensuring APP_ENCRYPTION_KEY is exactly 32 decoded bytes and BASE_URL contains a valid scheme and host. Sources: internal/config/config.go:42-66, internal/app/app.go:50-58

Integration and External Service Configuration

GoCasa manages connections to external services through a combination of hardcoded upstream defaults and database-persisted integration settings. Sources: internal/app/app.go:21-25, internal/db/migrations/0006_integrations.sql:3-12

Default Upstream Services

The application defines default endpoints for third-party APIs. These are typically replaced only during testing.

• Google API: https://www.googleapis.com
• Google OAuth: https://oauth2.googleapis.com
• Open-Meteo: https://api.open-meteo.com

Sources: internal/app/app.go:27-33

Integration Parameters

Integration-specific settings are stored in the integrations table. These parameters control the synchronization behavior for external feeds like iCal or Google Calendar.

• Enabled State: Controlled by the enabled column (Boolean 0/1).
• Sync Interval: Defined by sync_interval_seconds (default is 900 seconds/15 minutes).
• Credentials: Sensitive data is stored in credentials_enc using AES-256-GCM encryption, utilizing the APP_ENCRYPTION_KEY.
• Sync Cursor: Tracks the state of the last sync (e.g., an iCal ETag).

Sources: internal/db/migrations/0006_integrations.sql:3-12

Validation Logic

The config package performs strict validation to prevent runtime failures.

// From internal/config/config.go
if key, err := base64.StdEncoding.DecodeString(getenv("APP_ENCRYPTION_KEY")); err != nil || len(key) != 32 {
    errs = append(errs, errors.New("APP_ENCRYPTION_KEY must be 32 random bytes, base64-encoded"))
}

if s := getenv("SESSION_SECRET"); len(s) < 32 {
    errs = append(errs, errors.New("SESSION_SECRET must be at least 32 characters"))
}

Sources: internal/config/config.go:56-66

Data Storage Architecture

The configuration dictates where the application state is persisted.

GoCasa manages its own backups within the DATA_DIR/backups directory. It performs a VACUUM INTO every day at 03:00 based on the TZ configuration. Sources: README.md:33-40, internal/app/app.go:66-70

Conclusion

GoCasa follows a "fail-fast" configuration philosophy. By centralizing all critical settings in environment variables and enforcing strict validation at boot, the system ensures that security requirements (encryption keys and session secrets) and connectivity requirements (base URLs) are met before any data processing occurs. Sources: internal/config/config.go:28-68, cmd/gocasa/main.go:81-88