Operate a self-hosted instance

This page covers the routine tasks for a running Docker instance.

Know where data lives

With the default Compose file:

• SQLite database: /data/invoicer.sqlite3
• Generated files: /data/files
• Managed backups: /data/backups
• Docker volume: invoicer-data

Do not delete the Docker volume unless you intentionally want to remove the app data.

Start, stop, and update

Start or rebuild:

docker compose up -d --build

Stop:

docker compose down

Check logs:

docker compose logs -f invoicer

Check health:

curl -fsS http://127.0.0.1:8000/api/health

Back up before risky changes

Use the Settings backup page to create and review managed backups.

Managed backup ZIP files contain:

• manifest.json with metadata and row counts.
• database.json with a portable finance backup envelope.
• files/... for generated files that still exist in storage.

Store copies of backup ZIP files outside the Docker volume before upgrades, server moves, or destructive testing.

Secure public deployments

Before exposing the app outside localhost:

• Set INVOICER_SETUP_TOKEN until setup is complete.
• Use HTTPS and set INVOICER_COOKIE_SECURE=1.
• Keep .env and invoicer.toml out of Git.
• Use long unique passwords.
• Put the app behind a reverse proxy that you control.
• Create a backup before upgrades.

The app is designed for self-hosted trusted operators, not open public signup.

Add users and workspaces

After login, open Settings → Workspaces and users.

Owners and admins can create users in the active workspace. Owners can manage all roles in that workspace. Admins can manage admins and members, but not owners.

Create a new workspace when you need isolated finances for a different business or project. A workspace has its own clients, work items, invoices, expenses, payments, settings, backups, and Notion connector settings.