Self-Hosting

Docker Compose

The repository includes a complete container stack:

The gateway sends /api/* and /.well-known/* to the backend and everything else to the frontend. Both application containers use the same immutable image, while only the gateway is exposed to application traffic.

Production Deployment

cp .env.example .env

docker compose up -d --build

docker compose ps
curl --fail http://localhost:3000/healthz
curl --fail http://localhost:3000/api/health

docker compose logs -f gateway frontend backend
docker compose down

For hardened settings, copy .env.production.example to .env.production, fill in real secrets and the public URL, then use the production override:

docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file .env.production up -d --build

Environment Variables

Authentication

MemoBILL supports three authentication methods:

• Email & Password - Works out of the box, no additional setup needed
• Google OAuth - Requires AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET from Google Cloud Console
• Apple Sign In - Requires AUTH_APPLE_ID, AUTH_APPLE_TEAM_ID, AUTH_APPLE_KEY_ID, and AUTH_APPLE_KEY_BASE64 from Apple Developer. Encode your .p8 key file with base64 -w0 AuthKey_XXXXXXXXXX.p8

For OAuth providers, set the callback URL to https://your-domain.com/api/auth/callback/google (or /apple).

First User Setup

The first user to register on a new instance automatically becomes a site admin. This applies to both email/password and OAuth registration. Site admins can access the admin panel at /admin and configure site-wide settings at /admin/settings.

Registration Controls

Control who can create accounts on your instance:

Set via environment variable (REGISTRATION_MODE) or the admin settings page at /admin/settings.

Domain Restrictions

Restrict registration to specific email domains by setting ALLOWED_EMAIL_DOMAINS (comma-separated) or configuring it in admin settings. When set, only users with matching email domains can register or sign in via OAuth.

ALLOWED_EMAIL_DOMAINS="acme.com,example.com"

Self-Hosted Unlimited Mode

Without Stripe configured, all organizations automatically receive unlimited Pro features. No billing, subscriptions, or plan limits apply. This is detected automatically based on the absence of STRIPE_SECRET_KEY.

You can also control this behavior from the admin settings page:

• Auto (default) - Unlimited when Stripe is not configured
• Always on - Force unlimited regardless of Stripe config
• Always off - Enforce plan limits even without Stripe

Admin Settings

Site admins can configure all self-hosting settings from /admin/settings:

• Registration mode and allowed email domains
• Organization creation permissions
• Self-hosted unlimited mode toggle

Billing (Stripe)

Billing is fully optional. Without Stripe configured, all users get unlimited Pro features automatically. Site admins can also override plan limits per organization from /admin/organizations.

To enable paid plans, see the Billing & Stripe Setup guide for full instructions on creating products, prices, and configuring webhooks.

Email

Platform emails (welcome, invitations, login alerts, notification digests) use Resend. Set RESEND_API_KEY to enable these. Without it, platform emails are silently skipped.

Organization-level emails (invoices, reminders, statements) use per-org SMTP configuration set up in Settings > Email.

Background Jobs

MemoBILL uses Trigger.dev for scheduled maintenance and delayed retries. Set TRIGGER_PROJECT_REF and TRIGGER_SECRET_KEY in production before accepting traffic.

Scheduled tasks are defined in trigger/scheduled.ts:

• Notification digests every 15 minutes
• Report schedules hourly
• Stripe retry hourly
• Invoicing, bookkeeping, trash purge, and backups daily

Webhook delivery failures schedule exact delayed retry runs, so retries happen at their intended backoff time without polling. If TRIGGER_SECRET_KEY is missing when a webhook delivery fails, that retry run cannot be scheduled.

For local development:

pnpm trigger:dev

For production, deploy the Trigger.dev tasks:

pnpm trigger:deploy

Database

MemoBILL uses PostgreSQL. Minimum version: 15.

The schema is managed by Drizzle ORM. To apply schema changes:

pnpm db:push

Storage

File uploads (receipts, attachments, and backups) use the S3 API. The default Docker stack provisions a private MinIO bucket and a persistent object_storage_data volume, so it works locally without an AWS account.

docker compose up -d --build postgres frontend backend gateway

Reverse Proxy

For production, place MemoBILL behind a reverse proxy:

server {
    server_name accounting.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

accounting.example.com {
    reverse_proxy localhost:3000
}

Backups

Back up your PostgreSQL database regularly:

# Dump database
docker compose exec postgres pg_dump -U memobill memobill > backup.sql

# Restore
docker compose exec -T postgres psql -U memobill memobill < backup.sql