Skip to main content

Installation Guide

Deploy BillManager on your own infrastructure using Docker.

:::info For Self-Hosters Only This section is for administrators who want to run their own BillManager instance. If you're using the hosted version at app.billmanager.app, you don't need this guide. :::

Prerequisites​

  • Docker and Docker Compose installed
  • PostgreSQL database (included in Docker Compose, or use your own)
  • A domain name (optional, for production deployments)

Quick Start​

1. Create docker-compose.yml​

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:latest
    ports:
      - "5000:5000"
    environment:
      - DEPLOYMENT_MODE=self-hosted
      - DATABASE_URL=postgresql://billsuser:your-db-password@db:5432/billmanager
      - FLASK_SECRET_KEY=your-secret-key-here
      - JWT_SECRET_KEY=your-jwt-secret-here
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=billsuser
      - POSTGRES_PASSWORD=your-db-password
      - POSTGRES_DB=billmanager
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:

2. Generate Secure Keys​

Generate secure random keys for your installation:

# Generate FLASK_SECRET_KEY
openssl rand -hex 32

# Generate JWT_SECRET_KEY (required for production!)
openssl rand -hex 32

# Generate database password
openssl rand -hex 16

Replace the placeholder values in docker-compose.yml with your generated keys.

:::warning Production Requirement In production, JWT_SECRET_KEY (or FLASK_SECRET_KEY) must be explicitly set. The application will refuse to start without it. :::

3. Start the Application​

docker-compose up -d

4. Get Your Admin Password​

On first startup, BillManager creates a default admin account with a randomly generated secure password. This password is printed to the container logs.

docker-compose logs billmanager | grep -A 5 "INITIAL ADMIN CREDENTIALS"

You will see output like:

============================================================
🔐 INITIAL ADMIN CREDENTIALS (save these now!)
   Username: admin
   Password: xK9mP2vL7nQr3wYz
   You will be required to change this password on first login.
============================================================

:::danger Save This Password The initial admin password is only shown once during first startup. Save it immediately! :::

5. Access BillManager​

  1. Open your browser and navigate to http://localhost:5000
  2. Log in with username admin and the password from the logs
  3. You will be required to change the password on first login

Using Your Own Database​

If you have an existing PostgreSQL server:

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:latest
    ports:
      - "5000:5000"
    environment:
      - DEPLOYMENT_MODE=self-hosted
      - DATABASE_URL=postgresql://user:password@your-db-host:5432/billmanager
      - FLASK_SECRET_KEY=your-secret-key
      - JWT_SECRET_KEY=your-jwt-secret
    restart: unless-stopped

Database URL Format:

postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE

Next Steps​