Requirements

Hardware, software, and infrastructure requirements for running Pug.

Runtime

Requirement	Version	Notes
Go	1.23+	Build the server and workers
Docker	20+	Local infra via `make infra-up`
Docker Compose	2+	Multi-service local stack

Production deployments can run binaries directly without Docker.

Infrastructure services

Service	Version	Purpose	HA notes
PostgreSQL	15+	Auth, orgs, projects, config	Read replicas supported
ClickHouse	24+	Event storage, analytics queries	Cluster for scale
NATS	2.10+	Async pipeline, JetStream required	3-node cluster minimum

CLI commands

The pug binary provides all operations:


# Server
pug server                    # Connect RPC API
 
# Workers
pug worker events             # Event ingestion + enrichment
pug worker profile            # Profile writes (identify, alias)
pug worker email              # Magic link + transactional email
pug worker scheduler          # Scheduled jobs
 
# Migrations
pug postgres migrate          # Postgres schema migrations
pug clickhouse migrate        # ClickHouse schema migrations
pug nats migrate              # NATS stream setup

In development, make dev starts the server and all workers together with hot reload.

Hardware sizing

Development / staging

Component	Spec
Server	2 vCPU, 4 GB RAM
Postgres	1 vCPU, 2 GB RAM, 20 GB disk
ClickHouse	2 vCPU, 4 GB RAM, 50 GB disk
NATS	1 vCPU, 1 GB RAM

Handles ~100 events/second comfortably.

Production (small)

Component	Spec
API server	2 vCPU, 4 GB RAM (scale horizontally)
Workers	2 vCPU, 4 GB RAM (one process per worker type)
Postgres	2 vCPU, 8 GB RAM, 100 GB SSD
ClickHouse	4 vCPU, 16 GB RAM, 500 GB SSD
NATS	2 vCPU, 4 GB RAM

Handles ~1,000 events/second, ~100M stored events.

Production (large)

Component	Spec
API server	4+ replicas, 4 vCPU each
Workers	Scale event worker horizontally
Postgres	Primary + 2 read replicas, 16 GB RAM
ClickHouse	3-node cluster, 32 GB RAM each
NATS	3-node cluster

Handles ~10,000+ events/second. Contact the team for ClickHouse sharding guidance at higher volumes.

Network requirements

Port	Service	Access
8080	API server	Public (behind TLS terminator)
5432	Postgres	Internal only
8123	ClickHouse HTTP	Internal only
4222	NATS	Internal only

The API server is the only public-facing component. All other services should be on a private network.

Production checklist

TLS termination configured (nginx, Caddy, or cloud load balancer)
X-Forwarded-For forwarded correctly for geo enrichment
Postgres automated backups enabled
ClickHouse backup strategy defined
NATS JetStream persistence on durable storage
Secrets in a secrets manager, not in .env files
Monitoring on worker lag, API latency, ClickHouse disk usage
Log aggregation configured