Local Development Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for setting up, running, and testing the GoCasa project in a local development environment. GoCasa is a self-hosted family calendar dashboard built as a single static Go binary with a SQLite database and server-rendered UI.
Sources: README.md:1-5, internal/app/app.go:1-10
Development Environment Setup
GoCasa requires environment variables for configuration. No configuration file is used. You must provide values for BASE_URL, APP_ENCRYPTION_KEY, and SESSION_SECRET for the application to start.
Required Environment Variables
| Variable | Default | Description |
|---|---|---|
ADDR | :8080 | The network address where the HTTP server listens. |
BASE_URL | (Required) | The absolute URL used for cookies, redirects, and links. |
DATA_DIR | /data | The directory for app.db, backups, and assets. |
TZ | UTC | The household's default IANA time zone. |
APP_ENCRYPTION_KEY | (Required) | 32 base64-encoded bytes for encrypting tokens at rest. |
SESSION_SECRET | (Required) | Minimum 32 characters for session security. |
Sources: README.md:16-30, internal/config/config.go:17-64
Initializing the Server
To start the server locally, you must generate the templ files if you have edited any .templ source files. The application is executed via the cmd/gocasa package.
- Generate UI components:
go tool templ generate - Run the application:
go run ./cmd/gocasa
Sources: README.md:61-63
Architecture and Components
The GoCasa architecture follows a standard Go web application structure where the app package wires all components into a single http.Handler.
The diagram shows the initialization flow from the entry point to the web handler and database.
Sources: internal/app/app.go:50-84, cmd/gocasa/main.go:57-70
Database Migrations
GoCasa embeds migrations within the binary. These run automatically at startup. The application tracks the schema version using SQLite's PRAGMA user_version. Before applying migrations, the system creates a pre-migration backup in the DATA_DIR/backups directory.
Sources: README.md:43-51, internal/app/app.go:61-70
The Scheduler
A background scheduler manages periodic tasks, such as database backups and integration synchronization. Backups occur daily at 03:00 in the configured TZ.
Sources: README.md:35-37, internal/app/app.go:82-83, cmd/gocasa/main.go:73-75
Testing Framework
GoCasa uses a testing harness located in internal/apptest to build the real application for integration tests. This harness provides a temporary SQLite database, a fake clock, and fake upstream URLs to ensure tests are isolated and repeatable.
Test Harness Components
- Temporary Database: Created in a temporary directory for each test run.
- Fake Clock: Allows manual control of time via
Advance(d)andSet(t). - Fake Upstreams: Points Google API and OpenMeteo URLs to
127.0.0.1:1to prevent accidental internet calls. - Harness Client: An
http.Clientwith an isolated cookie jar to simulate a browser.
Sources: internal/apptest/apptest.go:19-58, README.md:66-68
Running Tests
Execute all project tests using the standard Go test command:
go test ./...
Sources: README.md:60
Testing Time-Dependent Logic
When testing scheduled tasks, use h.RunDue() to execute pending jobs at the current fake clock time.
func TestScheduledTask(t *testing.T) {
h := apptest.New(t)
// Advance clock to trigger due jobs
h.Clock.Advance(time.Hour)
h.RunDue()
}
Sources: internal/apptest/apptest.go:71, internal/app/app_test.go:50-59
Administrative Tools
The gocasa binary includes CLI commands for local maintenance and recovery.
Resetting Admin PINs
If an Admin PIN is lost, use the reset-pin command inside the container or local environment to generate a new temporary PIN for a specific member.
# Usage
go run ./cmd/gocasa reset-pin <Admin name or id>
Sources: cmd/gocasa/main.go:37-55
Health Checks
The binary includes a healthcheck subcommand used by Docker to probe the /healthz endpoint. It returns 0 if the database is reachable and the server responds with 200 OK.
Sources: cmd/gocasa/main.go:21-34
Summary
Local development of GoCasa relies on environment-based configuration and Go's standard toolchain. The internal/apptest package provides a robust environment for testing critical features like migrations and scheduling without external dependencies. Developers must ensure that required security keys are provided and that templ files are generated after UI changes.