Skip to main content

Self-Hosting

This guide covers a clean production-style self-hosted setup with Docker Compose.

Prerequisites​

  • Docker and Docker Compose installed
  • A server or VPS with open ports for your reverse proxy
  • A domain pointing to your server

1) Prepare the project files​

mkdir cashlytics && cd cashlytics
curl -O https://raw.githubusercontent.com/aaronjoeldev/cashlytics-ai/main/docker-compose.selfhost.yml
curl -O https://raw.githubusercontent.com/aaronjoeldev/cashlytics-ai/main/.env.example
cp .env.example .env

2) Configure required values in .env​

Set these before first start:

POSTGRES_PASSWORD=replace_with_long_random_password
AUTH_SECRET=replace_with_long_random_secret
NEXT_PUBLIC_APP_URL=https://your-cashlytics-domain.tld
AUTH_TRUST_HOST=true
SINGLE_USER_MODE=true

Generation helpers:

openssl rand -hex 32
npx auth secret

3) Start the stack​

docker compose -f docker-compose.selfhost.yml up -d

This starts:

  • cashlytics app container
  • postgres database container
  • cashlytics-cron reminder scheduler container

4) Verify services​

docker compose -f docker-compose.selfhost.yml ps
docker compose -f docker-compose.selfhost.yml logs -f cashlytics

Then open your configured app URL.

5) Optional features​

  • AI Assistant: set OPENAI_API_KEY
  • SMTP email (password reset, welcome mails): set EMAIL_TRANSPORT and SMTP variables
  • Push reminders: set VAPID keys and CRON_SECRET

Reverse proxy notes​

  • Keep AUTH_TRUST_HOST=true when running behind a domain/proxy
  • Route public traffic to the app container on port 3000
  • Keep PostgreSQL private (no public 5432 unless strictly required)

Updating Cashlytics​

docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

Backup recommendation​

Use periodic PostgreSQL dumps from the postgres service and store backups off-host.

Minimum backup target:

  • Database contents (cashlytics DB)
  • .env file (stored securely)