Self-Hosting

Alphorn is fully open source (AGPL-3.0-or-later) and designed to be self-hosted. You need a PostgreSQL 18 database - that's the only external dependency.

Docker Compose (recommended)Copy Anchor Link

The fastest way to get Alphorn running is the prebuilt image from the GitHub Container Registry:

services:
  alphorn:
    image: ghcr.io/alphorn-dev/alphorn:latest
    ports:
      - "3000:3000"
    environment:
      # PostgreSQL connection string
      DATABASE_URL: postgresql://alphorn:secret@db:5432/alphorn
      # Generate with: openssl rand -base64 32
      BETTER_AUTH_SECRET: your-secret-key
      # Public URL where Alphorn will be accessible
      BETTER_AUTH_URL: http://localhost:3000
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000/api/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s # migrations run before the server starts
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: alphorn
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: alphorn
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U alphorn"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  pgdata:

docker compose up -d

Alphorn is available at http://localhost:3000. Create your first account there.

The repository's own docker-compose.yml is the same setup, but builds the image from source (build: .) and reads settings from a .env file. It sets DATABASE_URL itself (overriding the one in .env) and takes the database password from POSTGRES_PASSWORD (default alphorn - change it). To use it:

git clone https://github.com/alphorn-dev/alphorn.git
cd alphorn
cp .env.example .env   # set at least BETTER_AUTH_SECRET
docker compose up -d

PodmanCopy Anchor Link

Podman is a drop-in replacement for Docker that runs rootless by default. The same compose file works with podman-compose or Podman's built-in podman compose:

podman compose up -d

Or run the containers individually:

# Create a pod so containers can communicate
podman pod create --name alphorn -p 3000:3000

# Start PostgreSQL
podman run -d --pod alphorn --name alphorn-db --restart unless-stopped \
  -e POSTGRES_USER=alphorn \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=alphorn \
  -v pgdata:/var/lib/postgresql \
  postgres:18-alpine

# Wait until PostgreSQL accepts connections - Alphorn exits if it can't migrate
until podman exec alphorn-db pg_isready -U alphorn; do sleep 1; done

# Start Alphorn
podman run -d --pod alphorn --name alphorn-app --restart unless-stopped \
  -e DATABASE_URL=postgresql://alphorn:secret@localhost:5432/alphorn \
  -e BETTER_AUTH_SECRET=your-secret-key \
  -e BETTER_AUTH_URL=http://localhost:3000 \
  ghcr.io/alphorn-dev/alphorn:latest

Alphorn is available at http://localhost:3000.

Running from SourceCopy Anchor Link

Requirements: Node.js 22.12 or newer (the Docker image uses Node 24), pnpm, and a PostgreSQL 18 database.

git clone https://github.com/alphorn-dev/alphorn.git
cd alphorn
pnpm install
cp .env.example .env   # set DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL
pnpm db:deploy         # apply database migrations
pnpm build
pnpm start

pnpm start runs the web app with the delivery worker embedded (MODE=all). Next.js prints a warning that next start doesn't fit output: standalone - it still works.

To run separate worker processes from source, see Architecture & Scaling.

Environment VariablesCopy Anchor Link

The .env.example in the repository lists every variable with comments.

RequiredCopy Anchor Link

Sign-upCopy Anchor Link

Email (SMTP)Copy Anchor Link

Alphorn sends system emails (verification, password reset, email change, invitations) over SMTP. All five variables must be set, otherwise email is switched off.

With SMTP configured, new accounts must verify their email address. Without SMTP:

• Accounts are usable right after sign-up, without verification
• Password reset and email change are not available
• Members can only be invited with shareable links
• SSO logins can't be linked to existing email/password accounts, because those email addresses are never verified (see Authentication → SSO)

SMTP connections time out after 15 seconds. Failed emails are logged.

Runtime & ScalingCopy Anchor Link

LimitsCopy Anchor Link

Live Stream (SSE)Copy Anchor Link

See Streaming → Self-Hosting for when you need this.

Logging & Error TrackingCopy Anchor Link

Server-side error tracking works with the prebuilt image. Browser error tracking needs SENTRY_DSN at build time, so it only works when you build the image or app yourself.

Outbound TrafficCopy Anchor Link

Build-timeCopy Anchor Link

SSO / OAuthCopy Anchor Link

Alphorn supports social login and enterprise SSO. Set the relevant environment variables to enable a provider - if the variables are absent, the provider is simply not shown on the login page.

GitHubCopy Anchor Link

Create an OAuth App at GitHub → Settings → Developer settings → OAuth Apps. Set the callback URL to {BETTER_AUTH_URL}/api/auth/callback/github.

GoogleCopy Anchor Link

Create credentials at Google Cloud Console → APIs & Services → Credentials → OAuth client ID (Web application). Add {BETTER_AUTH_URL}/api/auth/callback/google as an authorized redirect URI.

MicrosoftCopy Anchor Link

Register an app in Azure Portal → App registrations. Under Redirect URIs, add a Web URI: {BETTER_AUTH_URL}/api/auth/callback/microsoft.

Generic OIDC (Keycloak, Okta, Azure AD, etc.)Copy Anchor Link

Connect any OIDC-compliant identity provider.

Register {BETTER_AUTH_URL}/api/auth/callback/{OIDC_PROVIDER_ID} as the redirect URI in your identity provider (with the default ID: /api/auth/callback/custom-oidc).

The discovery document is fetched once at startup. If that fails, the SSO button is still shown but signing in with it fails, and only an error is logged - check the logs and restart once the provider is reachable.

Architecture & ScalingCopy Anchor Link

Alphorn has three parts:

• Web - the dashboard, the webhook receiver (/n/...), and Live Stream connections
• Worker - sends deliveries from the queue, retries them, and runs the background sweep
• Queue - lives in PostgreSQL (pg-boss), so there is no Redis or other broker

With the default MODE=all, web and worker run in one process. To scale, run them separately with the same image and the same environment:

From source, start a separate worker with pnpm dev:worker, or bundle it with pnpm build:worker and run node --env-file=.env worker.mjs. The worker doesn't read .env by itself - export the variables or pass --env-file. Set MODE=worker for it as well, otherwise Live Stream deliveries are marked delivered without reaching any client. pnpm dev:worker and pnpm sse-server run through npx tsx, which downloads tsx on first use.

Health CheckCopy Anchor Link

GET /api/health returns {"status": "ok", "version": "..."}, or 503 with {"status": "error", "message": "database unreachable", "version": "..."} when PostgreSQL can't be reached. It needs no login. Use it for container health checks and load balancers.

Reverse Proxy & HTTPSCopy Anchor Link

Run Alphorn behind a reverse proxy with TLS (Nginx, Caddy, Traefik, etc.) and set BETTER_AUTH_URL to the public https:// URL.

• HTTPS is required for anything but localhost. The production build uses secure cookies, which browsers drop on plain http:// - signing in over http://192.168.x.x fails.
• Set X-Forwarded-For (or X-Real-IP) to the real client IP. Alphorn uses it for login rate limiting and the per-IP stream limit. Without it, all clients share one limit. Make sure the proxy overwrites the header from clients, otherwise clients can fake it.
• Disable buffering for streams so Live Stream events arrive immediately, and allow long-lived connections.

Example for Nginx:

server {
    listen 443 ssl;
    server_name alphorn.example.com;

    # ssl_certificate ...;

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

    location /api/stream/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

Alphorn already sends Strict-Transport-Security, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and Referrer-Policy headers. Because of X-Frame-Options: DENY, the dashboard can't be embedded in an iframe.

DatabaseCopy Anchor Link

Alphorn uses PostgreSQL exclusively - no Redis, no MongoDB, no additional infrastructure. All configuration, the delivery queue, and message history live in the database.

• Version: PostgreSQL 18 or newer. Alphorn uses the built-in uuidv7() function added in PostgreSQL 18.
• Permissions: the database user needs to create tables and the pgboss schema (the queue creates it on first start), so give it CREATE on the database.
• Extensions: the first migration runs CREATE EXTENSION IF NOT EXISTS pg_trgm (for message search). The database user needs permission to create it, or create it upfront as a superuser.
• Migrations: the Docker image applies them on every start. From source, run pnpm db:deploy.
• Connection poolers: the queue and the webhook cache use LISTEN/NOTIFY, which doesn't work through PgBouncer in transaction mode. Alphorn still works, but falls back to polling and picks up webhook changes with up to 30 seconds delay. Connect directly or use session mode if you can.

BackupsCopy Anchor Link

Back up the database regularly, e.g. with pg_dump:

# Backup
docker compose exec -T db pg_dump -U alphorn -Fc alphorn > alphorn-$(date +%F).dump

# Restore into an empty database
docker compose exec -T db pg_restore -U alphorn -d alphorn --clean --if-exists < alphorn-2026-01-01.dump

UpdatingCopy Anchor Link

Prebuilt imageCopy Anchor Link

# Docker
docker compose pull
docker compose up -d

# Podman
podman compose pull
podman compose up -d

Database migrations run automatically when the new container starts.

Available image tags:

Release tags are built for linux/amd64 and linux/arm64.

Pin a version tag in production so updates happen when you decide.

Repository compose file (built from source)Copy Anchor Link

git pull
docker compose up -d --build

From sourceCopy Anchor Link

git pull
pnpm install
pnpm db:deploy
pnpm build
# then restart the process