Run HelloJohn on your own infrastructure with full control over data, configuration, and scaling.

Self-Hosting HelloJohn

HelloJohn OSS can be deployed on any infrastructure you control — a single VPS, a Kubernetes cluster, or a managed container platform. You own your data, your keys, and your configuration.

What you need

Component	Minimum	Recommended
CPU	1 vCPU	2+ vCPU
RAM	512 MB	1 GB+
PostgreSQL	14+	15+ (managed, e.g. RDS, Supabase, Neon)
Redis	Optional	6+ (for rate limiting + sessions)
Reverse proxy	Any	nginx or Caddy

HelloJohn is a single Go binary with no runtime dependencies beyond PostgreSQL. Redis is optional but recommended for high-traffic deployments.

Deployment options

Docker Compose (quickest)

The fastest way to get HelloJohn running locally or on a single server:

curl -fsSL https://hellojohn.dev/install/docker-compose.yml -o docker-compose.yml
docker compose up -d

See the Docker guide for the full reference.

Binary

Download and run the pre-built binary directly:

# Linux amd64
curl -fsSL https://github.com/hellojohn/hellojohn/releases/latest/download/hellojohn-linux-amd64.tar.gz | tar xz
./hellojohn serve

Binaries are available for Linux (amd64, arm64), macOS (arm64), and Windows.

Kubernetes / Helm

A community Helm chart is available:

helm repo add hellojohn https://charts.hellojohn.dev
helm install hellojohn hellojohn/hellojohn \
  --set config.databaseUrl=postgres://...

Railway / Render / Fly.io

HelloJohn ships a Dockerfile and runs as a standard 12-factor app. Any platform that supports Docker containers works out of the box.

Architecture overview

                ┌──────────────────────────────────┐
                │           Your App               │
                │  (frontend + backend services)   │
                └─────────────────┬────────────────┘
                                  │ HTTPS
                ┌─────────────────▼────────────────┐
                │         Reverse Proxy            │
                │       (nginx / Caddy)            │
                └──────────┬───────────────────────┘
                           │
              ┌────────────▼────────────┐
              │      HelloJohn          │
              │   (single binary)       │
              │   :3000 (API)           │
              └──────┬──────────────────┘
                     │
         ┌───────────┼───────────────┐
         │           │               │
    ┌────▼───┐  ┌────▼───┐  ┌───────▼───┐
    │ Postgres│  │ Redis  │  │  Storage  │
    │  (DB)  │  │(cache) │  │  (S3/R2)  │
    └────────┘  └────────┘  └───────────┘

Quick health check

Once running, verify HelloJohn is alive:

curl https://auth.yourdomain.com/health
# {"status":"ok","version":"1.2.3","db":"connected"}

Next steps

Docker Setup

Run HelloJohn with Docker Compose in minutes

Environment Variables

Complete reference for all configuration options

Database Setup

PostgreSQL configuration, migrations, and backups

Reverse Proxy

nginx and Caddy configuration examples

Production Checklist

Everything to check before going live

Upgrading

How to upgrade HelloJohn safely