Server flavors: happier-server-light vs happier-server

hstack supports two server “flavors”. You can switch between them globally (main stack) or per stack.

What’s the difference?

Both flavors use the same server codebase (the monorepo server package, typically apps/server), but run with different backends and storage assumptions.

happier-server-light (recommended default)

• No Docker required
• Uses SQLite by default (stack-local file), with optional embedded Postgres via PGlite
• Stores local public files under the stack directory
• Best choice for a stable “main” stack and quick local installs

Light stacks are isolated by default:

~/.happier/stacks/<stack>/server-light/files
~/.happier/stacks/<stack>/server-light/pglite
~/.happier/stacks/<stack>/server-light/happier-server-light.sqlite

Key env vars (stored in the stack env file):

• HAPPIER_SERVER_LIGHT_DATA_DIR
• HAPPIER_SERVER_LIGHT_FILES_DIR
• HAPPIER_SERVER_LIGHT_DB_DIR
• HAPPIER_DB_PROVIDER (optional; defaults to sqlite for light stacks)

Optional DB providers (light):

• sqlite (default)
• pglite (optional)

Note: HAPPIER_SERVER_LIGHT_DB_DIR defaults to .../server-light/pglite for historical reasons, even when using SQLite.

happier-server (full server)

• Docker-managed infra per stack (Postgres + Redis + Minio/S3)
• Closer to “production-like” behavior
• Useful when you need Redis/S3 semantics or want to reproduce full-server-only issues

Optional DB providers (full):

• postgres (default; Docker-managed per stack)
• mysql (supported, but requires an explicit DATABASE_URL; hstack does not provision MySQL)

Choosing a DB provider (power users)

You can select a DB provider without changing the interactive wizard:

# Light stacks (default is sqlite)
hstack stack new exp-light --server=happier-server-light --db-provider=sqlite
hstack stack new exp-pglite --server=happier-server-light --db-provider=pglite

# Full stacks (default is postgres)
hstack stack new exp-full --server=happier-server --db-provider=postgres

# MySQL requires an explicit DATABASE_URL
hstack stack new exp-mysql --server=happier-server --db-provider=mysql --database-url=mysql://user:[email protected]:3306/happier

Under the hood, this sets HAPPIER_DB_PROVIDER in the stack env file. For mysql, you must also provide DATABASE_URL.

Full server infra (no AWS required)

happier-server requires:

• Postgres (DATABASE_URL)
• Redis (REDIS_URL)
• S3-compatible object storage (S3_*)

hstack can manage this for you automatically per stack using Docker Compose (Postgres + Redis + Minio), so you do not need AWS S3.

This happens automatically when you run hstack start/dev --server=happier-server (or when a stack uses happier-server), unless you disable it with:

export HAPPIER_STACK_MANAGED_INFRA=0

If disabled, you must provide DATABASE_URL, REDIS_URL, and S3_* yourself.

UI serving with happier-server

The upstream happier-server does not serve the built UI itself.

For a “one URL” UX (especially with Tailscale), hstack starts a lightweight UI gateway that:

• serves the built UI at / (if a build exists)
• reverse-proxies API calls to the backend server
• reverse-proxies realtime websocket upgrades (/v1/updates)
• reverse-proxies public files (to local Minio)

This means hstack start --server=happier-server can still work end-to-end without requiring AWS S3 or a separate nginx setup.

Realtime networking note (polling fallback)

By default, Happier clients use Socket.IO / Engine.IO defaults (HTTP long-polling, then upgrade to WebSocket when possible). This is the most compatible option for restrictive networks and corporate proxies.

If you need to force WebSocket-only (rare), set:

• UI (Expo): EXPO_PUBLIC_HAPPIER_SOCKET_FORCE_WEBSOCKET=1
• CLI/daemon: HAPPIER_SOCKET_FORCE_WEBSOCKET=1

Migrating between flavors (light ⇢ full)

hstack includes an experimental migration helper that can copy core chat data from a happier-server-light stack into a happier-server stack (Docker Postgres):

hstack migrate light-to-server --from-stack=main --to-stack=full1

Optional: include local public files (server-light files/) by mirroring them into Minio:

hstack migrate light-to-server --from-stack=main --to-stack=full1 --include-files

Notes:

• This preserves IDs (session URLs remain valid on the target server).
• It also copies the HANDY_MASTER_SECRET from the source stack into the target stack’s secret file so auth tokens remain valid.
• Current limitation: the migration tool expects the source light stack to be --db-provider=pglite (SQLite light stacks are not supported yet).

Prisma behavior (why start is safer under LaunchAgents)

• hstack start is “production-like”. It avoids running heavyweight schema sync loops under launchd KeepAlive.
• hstack dev is for rapid iteration:
  • for happier-server: hstack runs prisma migrate deploy by default (configurable via HAPPIER_STACK_PRISMA_MIGRATE).
  • for happier-server-light:
    • hstack runs provider-specific light migrations (migrate:sqlite:deploy for SQLite by default, or migrate:light:deploy for PGlite when configured).

Important: for a given run (hstack start / hstack dev) you choose one flavor.

How to switch (main stack)

Use the srv helper (persisted in ~/.happier/stacks/main/env by default, or in your stack env file when using hstack stack ...):

hstack srv status
hstack srv use happier-server-light
hstack srv use happier-server
hstack srv use --interactive

This persists HAPPIER_STACK_SERVER_COMPONENT.

How to switch for a specific stack

Use the stack wrapper:

hstack stack srv exp1 -- status
hstack stack srv exp1 -- use happier-server-light
hstack stack srv exp1 -- use happier-server
hstack stack srv exp1 -- use --interactive

This updates the stack env file (typically ~/.happier/stacks/<name>/env).

One-off overrides (do not persist)

You can override the server flavor for a single run:

hstack start --server=happier-server-light
hstack start --server=happier-server

hstack dev --server=happier-server-light
hstack dev --server=happier-server

Flavor vs repo selection

There are two separate concepts:

• Flavor selection: which server flavor hstack runs
  • controlled by HAPPIER_STACK_SERVER_COMPONENT (via hstack srv use ...)
• Repo selection: which monorepo checkout/worktree the stack runs from
  • controlled by HAPPIER_STACK_REPO_DIR (via hstack wt use ... / hstack stack wt <stack> -- use ...)

SQLite note

SQLite is the default DB provider for happier-server-light. If you want embedded Postgres instead, create a light stack with --db-provider=pglite.