Skip to content

index.mdx

Latest commit

 

History

History
63 lines (43 loc) · 3.35 KB

index.mdx

File metadata and controls

63 lines (43 loc) · 3.35 KB
title Deployment
description Overview of ways to self-host the Happier Server.

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).
  • 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.
  • Docker (recommended starting point): build from this repo’s Dockerfile and run with Docker / Docker Compose.
  • 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

Quick decision (recommended)

  • Want a managed service on a host/VPS (plus rollback + optional auto-update): use Self-host runtime (hstack self-host install).
  • Already using a supervisor (Docker/Compose/k8s/Nomad/systemd): use Docker or the runner (@happier-dev/relay-server) and update on restart.
  • Developing or customizing from source: use repo-local mode (or hstack setup-from-source for stack-based local workflows).

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.