Deployment

This section describes how to deploy your own Happier Server (the sync backend). It does not cover deploying Happier’s website/docs.

What you deploy

• Happier Server: HTTP API + Socket.IO realtime sync, plus optional background work depending on configuration.
• Your clients (CLI / app / web) point to your server URL (for example https://api.example.com).

Supported ways to run it

• Managed self-host runtime (installer + service + rollback + optional auto-update).
  • See: Self-host runtime (installer vs runner)
• Run from a monorepo clone (repo-local mode): use yarn from the repo root to run a stackless local stack, install a service, and configure Tailscale.
  • See: Run from a monorepo clone (repo-local mode)
• Docker (recommended starting point): build from this repo’s Dockerfile and run with Docker / Docker Compose.
  • See: Docker
• Configuration reference: see Environment variables for the complete server runtime env surface.
• Canonical env template: apps/server/.env.example
• HStack (stack CLI): a guided workflow that can run the server for you (documentation maintained separately).
  • Remote daemon bootstrap over SSH: /docs/hstack/remote-daemon
  • Remote self-host server install over SSH: /docs/hstack/remote-server

Server flavors (high level)

Happier Server supports two “flavors” that share the same API + internal logic; the difference is which storage backends are used:

• Full: external Postgres (default) or MySQL 8+ + S3/Minio-compatible storage (default) or local files (HAPPIER_FILES_BACKEND=local); optional Redis for multi-replica realtime.
• Light: SQLite (default) or embedded Postgres (PGlite) stored on disk; local file storage served by the server at GET /files/*.

If you’re deploying a shared server for multiple users/devices, you likely want full. If you want the easiest single-node setup, start with light.

Scaling (high level)

You can run the server in one process (simple), or split into roles:

• SERVER_ROLE unset → all (default): API + realtime + background work in one process.
• SERVER_ROLE=api: API + realtime only (clients connect here).
• SERVER_ROLE=worker: background work only (no HTTP).

For multi-replica API deployments, enable Redis fanout (REDIS_URL + HAPPIER_SOCKET_ADAPTER=redis-streams) and configure sticky sessions at your load balancer.

See Docker for concrete examples.

Reverse proxy basics

In production, run the API behind a reverse proxy that:

• Terminates TLS
• Supports WebSockets (Upgrade headers)
• Uses sensible timeouts for long-lived connections
• Keeps secrets in your deployment platform (env vars), not in git

If you serve /files/* from the server (light flavor), ensure your proxy allows those routes.