Prerequisites

Before deploying HelloJohn, make sure you have the following infrastructure and tools in place. This page covers the minimum requirements for a production-ready deployment.

Infrastructure

PostgreSQL

HelloJohn requires PostgreSQL 14 or later. This is the only required dependency.

Managed options (recommended):

• Neon — serverless, autoscaling, free tier
• Supabase — PostgreSQL with extras, free tier
• Amazon RDS — managed, Multi-AZ available
• Google Cloud SQL

Connection string format:

postgresql://user:password@host:5432/hellojohn?sslmode=require

Redis (Optional)

Redis is optional but recommended for production workloads. It enables:

• Distributed rate limiting
• Session storage caching
• Webhook event queuing

Managed options:

• Upstash — serverless Redis, per-request billing
• Amazon ElastiCache
• Redis Cloud

If Redis is not configured, HelloJohn falls back to in-memory rate limiting (suitable for single-instance deployments only).

Compute

HelloJohn is a single statically-linked Go binary — no runtime dependencies beyond the database.

Required Software

Docker

Required for the Docker Compose deployment method:

# Check Docker version
docker --version
# Docker version 24.0.0 or later

docker compose version
# Docker Compose version v2.20.0 or later

Install Docker Engine →

HelloJohn CLI (Optional)

The CLI is used for:

• Running migrations
• Managing tenants
• Local development webhook forwarding

npm install -g @hellojohn/cli
hj --version

Network Requirements

DNS

You need a domain for HelloJohn. The API is typically served on a subdomain:

auth.example.com         # HelloJohn API
app.example.com          # Your application

Point your DNS A record to your server IP before setting up TLS.

Ports

PostgreSQL and Redis should not be exposed to the public internet. Use private networking or firewall rules.

TLS Certificate

HelloJohn requires HTTPS in production. Obtain a certificate from:

• Let's Encrypt (free) — via Certbot or Caddy (auto-provisioned)
• AWS Certificate Manager (free with ALB)
• Cloudflare (free with proxy)

Accounts & Keys

Signing Keys

HelloJohn uses Ed25519 keys to sign JWTs. Generate them before deployment:

# Generate Ed25519 private key (PEM format)
openssl genpkey -algorithm ed25519 -out signing_key.pem

# Extract the public key
openssl pkey -in signing_key.pem -pubout -out signing_key_pub.pem

# View the private key (for the environment variable)
cat signing_key.pem

Store the private key as the HELLOJOHN_JWT_SIGNING_KEY environment variable.

Security: Never commit signing keys to source control. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.).

Email Provider (Required)

HelloJohn sends transactional emails for:

• Email verification
• Magic link sign-in
• Password reset
• MFA OTP
• Organization invitations

You need an SMTP server or transactional email provider:

• Resend — developer-friendly, free tier
• Postmark — high deliverability
• SendGrid
• Amazon SES — low cost at volume

See the SMTP Configuration guide for setup.

Checklist

Before proceeding to deployment:

• PostgreSQL 14+ provisioned and accessible
• Database user created with schema creation privileges
• Ed25519 signing key generated and stored securely
• Domain name pointed to your server
• TLS certificate provisioned (or Caddy auto-provisioning configured)
• Email/SMTP provider credentials obtained
• Redis provisioned (optional but recommended)
• Docker 24+ and Docker Compose v2 installed (if using Docker)
• Firewall rules: only ports 80 and 443 exposed publicly

Next Steps

• Docker Compose Deployment
• Kubernetes Deployment
• Environment Variables
• SMTP Configuration