Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Hearth is a self-hostable household management system designed to run as a private server. You deploy the application using Docker Compose to ensure a consistent environment for sensitive personal and financial data. One instance serves a single household and operates in a privacy-conscious, self-hosted context.
Sources: CLAUDE.md, PRODUCT.md
Architecture Overview
The deployment architecture consists of two primary services: an Nginx reverse proxy and the Hearth application container. Nginx handles TLS termination and directs traffic to the application running on port 3000. The application uses a local SQLite database for data persistence, which simplifies the infrastructure by removing the need for a separate database container.
This diagram shows the flow of traffic through the Nginx proxy to the Hearth application and its interaction with the persisted data volume.
Sources: docker-compose.https.yml:21-33, CLAUDE.md
Core Components
The deployment environment utilizes specific Docker services and configurations to manage application lifecycle and data security.
| Component | Image | Purpose |
|---|---|---|
| Nginx | nginx:alpine | Handles SSL/TLS termination and serves as the web gateway. |
| App | jaysbeekay/hearth:latest | Runs the Next.js application, Prisma engine, and cron tasks. |
| SQLite | Internal | Local database file stored in the /app/data volume. |
| Data Volume | ./data | Persists the database, document uploads, and local backups. |
Sources: docker-compose.https.yml:21-76, CLAUDE.md
Configuration and Environment Variables
Hearth uses environment variables to configure critical security keys, integration credentials, and system behaviors. You must provide these variables during deployment to enable optional features.
Security and Auth
AUTH_SECRET: Used by NextAuth for session security.ENCRYPTION_KEY: Gates offsite DB backup encryption and user AI API key encryption (AES-256-GCM).APP_URL: Defines the Relying Party ID for WebAuthn passkeys and generates invitation links.
Notification Integrations
SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASSWORD: Configures email delivery for reminders and invites.NTFY_URL,NTFY_TOPIC: Configures real-time push notifications.
Data Management
BACKUP_S3_BUCKET/BACKUP_SFTP_HOST: Defines where encrypted snapshots are uploaded.BACKUP_RETENTION_COUNT: Determines how many historical backups are kept.
Sources: docker-compose.https.yml:37-73, CLAUDE.md, src/app/(app)/settings/app/page.tsx
Initial Setup Flow
When you start a fresh Docker instance, Hearth enters a setup mode. The application checks the database for existing users and redirects you to the setup page if the household is empty.
The sequence above illustrates the automated redirection logic that ensures the first deployment is properly initialized.
Sources: src/app/setup/page.tsx:11-14, CLAUDE.md
Persistence and Backups
You must mount a host directory to /app/data within the container to prevent data loss. The application performs a live VACUUM INTO SQLite snapshot during backups.
- The scheduler runs a backup based on
BACKUP_CRON_SCHEDULE. - The system encrypts the snapshot using the
ENCRYPTION_KEY. - The container uploads the encrypted file to S3, SFTP, or a local folder.
- Past backups are pruned according to
BACKUP_RETENTION_COUNT.
Sources: CLAUDE.md, docker-compose.https.yml:62-75, src/components/AppSettingsForms.tsx:300-340
Conclusion
Docker deployment provides the standard method for running Hearth in a secure, self-contained environment. By configuring the necessary environment variables and volumes, you enable the full suite of household management features while maintaining data privacy on your own hardware. Revisit System Settings within the app to refine integrations after the initial Docker start.