Self-hosting

GetPaidHQ is self-hostable billing infrastructure. You run the API, databases, workflow engine, pub/sub, cache, and any payment-provider credentials inside your own environment.

What you host

Component	Required	Notes
API server	Yes	Go HTTP service. REST API is mounted under `/api`.
Postgres	Yes	Operational database.
Workflow engine	Yes	Hatchet by default; Temporal can be selected.
Redis	Recommended	Cache and cluster-wide rate limits.
NATS	Recommended	Pub/sub. Required for JetStream usage ingestion.
Usage store	Optional	Same Postgres, separate Postgres DB, or ClickHouse.

Local self-hosting

From the server repository:

cp .env.example .env
make up
make db-migrate-all
make run

make up starts the local backing services:

Service	Local port
Postgres	`10432`
Redis	`10379`
NATS	`10422`
NATS monitoring	`10822`
Hatchet UI/API	`10888`
Hatchet gRPC	`10707`

Minimum production shape

Run at least:

One or more API server instances.
A managed or self-hosted Postgres database.
A workflow engine reachable from the API workers.
Redis if more than one API instance is running.
NATS if using pub/sub-backed workflows or JetStream usage ingestion.

For low usage volume, USAGE_DATABASE_URL can be empty and usage events will use the operational Postgres database. For heavier usage, use a separate usage database or ClickHouse.

Required configuration

Set these before serving production traffic:

DATABASE_URL
API_KEY_PEPPER
SECRETS_ENCRYPTION_KEY
ALLOWED_ORIGINS
WORKFLOW_ENGINE
workflow-engine credentials, such as HATCHET_CLIENT_TOKEN
payment gateway credentials for the processors you enable

Recommended:

REDIS_HOST
NATS_URL
USAGE_DATABASE_URL for separate usage-event storage
USAGE_INGEST_MODE=jetstream only when NATS JetStream is available

Data ownership

Self-hosting keeps customer, subscription, payment, dunning, and usage data in your infrastructure. Payment credentials should still be encrypted and scoped to the gateway adapters you use.

Prepare runtime configuration: Deploy
Understand the system shape: Architecture & Concepts
Configure usage storage: Usage & Metering