Self-Hosting

Run the full Pug stack on your own infrastructure. Self-hosting gives you full data ownership, custom deployment topology, and air-gapped operation.

Backend repo: cotton (Go module github.com/pug-sh/pug, CLI binary pug)
Dashboard repo: cotton-ui

When to self-host

Self-host	Use Pug Cloud
Data must stay in your VPC	Fastest time to value
Custom compliance requirements	Managed infra and upgrades
Existing Postgres/ClickHouse/NATS
Air-gapped environments

Architecture


                    ┌─────────────┐
  Browser/Mobile    │  cotton-ui  │  Dashboard (React)
       │            └──────┬──────┘
       │                   │ JWT
       ▼                   ▼
  ┌─────────────┐   ┌─────────────┐
  │  Web SDK    │   │  Go server  │  Connect RPC API (pug server)
  └──────┬──────┘   └──────┬──────┘
         │ API key          │
         └────────┬─────────┘
                  │
         ┌────────▼────────┐
         │      NATS       │  JetStream message queue
         └────────┬────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│ Event  │  │ Profile  │  │  Email   │
│ worker │  │ worker   │  │  worker  │
└───┬────┘  └────┬─────┘  └────┬─────┘
    │            │              │
    ▼            ▼              ▼
┌──────────────────┐    ┌──────────────┐
│   ClickHouse     │    │  PostgreSQL  │
│  (analytics)     │    │  (config)    │
└──────────────────┘    └──────────────┘

Stack components

Component	Purpose
Postgres	Auth, orgs, projects, config, soft-delete state
ClickHouse	Event storage and analytics queries
NATS	Async event pipeline and worker communication
Go server	Connect RPC API (`pug server`)
Workers	Event enrichment, profiles, email

Quick start (development)


git clone git@github.com:fivebitsio/cotton.git
cd cotton
cp .env.example .env
make infra-up    # Start Postgres, NATS, ClickHouse via Docker
make migrate     # Run all database migrations
make dev         # Start server + all workers with hot reload

Verify the API is running:


curl http://localhost:8080/health

Point the Web SDK at your local API:


init('PROJECT_ID', {
  apiKey: 'KEY',
  endpoint: 'http://localhost:8080'
})

Connect the dashboard


git clone git@github.com:fivebitsio/cotton-ui.git
cd cotton-ui
cp .env.example .env
# Set VITE_API_URL=http://localhost:8080
pnpm install
pnpm dev

Topics

Requirements

Hardware, software, and CLI commands for running the stack.

Configuration

Environment variables for the server, workers, and stores.

Development

Local workflow, testing, and architecture docs.

Production deployment

For production, additionally configure:

TLS termination at a load balancer (nginx, Caddy, cloud LB)
Postgres read replicas for dashboard query load
ClickHouse cluster for analytics scale
NATS cluster (3 nodes minimum) for HA
Secrets management (Vault, AWS Secrets Manager, etc.)
Monitoring and alerting on worker lag and ClickHouse disk

See Requirements for sizing guidance.

SDK configuration

Point SDK endpoint to your API base URL:


init('PROJECT_ID', {
  apiKey: 'KEY',
  endpoint: 'https://api.yourcompany.com'
})

No other SDK changes required — the same @poluruprvn/pug-web package works against any Pug backend.