Happier Docs
Deployment

Proxmox VE

Deploy Happier Server on Proxmox VE using community-scripts helper scripts.

This guide explains how to deploy Happier on Proxmox VE using the community-maintained Proxmox VE Helper-Scripts project (LXC-based “one command” installs).

What you get

  • A dedicated Debian LXC container running Happier Server with PGlite embedded database.
  • Optional served web UI from the same container.
  • Optional autostart via a systemd system service inside the container.
  • Optional Tailscale for remote access + HTTPS (recommended for phone access).
  1. In a browser, open helper-scripts.com and search for Happier.
  2. Copy the install command from the script page.
  3. Paste it into the Proxmox Shell (host) and follow the prompts.

If the script is not available on helper-scripts.com yet, you can run the installer directly from our ProxmoxVE fork:

tmp="$(mktemp)" \
  && curl -fsSL "https://raw.githubusercontent.com/happier-dev/ProxmoxVE/main/ct/happier.sh" -o "$tmp" \
  && bash "$tmp" \
  && rm -f "$tmp"

At the end, the installer prints:

  • Your container IP and local HTTP URL
  • If applicable, your public HTTPS URL
  • “Configure server” links (web + mobile deep link) so your app/web UI points to the right server
  • Next steps to connect a terminal/daemon

Local access:

  • http://<container-ip>:3005 (LAN)

If you select Tailscale during install, the stack typically binds to loopback and will not be reachable from your LAN IP. In that case, use the installer’s printed HTTPS URL instead.

  1. Run the Proxmox helper script install (above).
  2. Choose a remote access option:
    • Tailscale (recommended) if you want an HTTPS URL without opening ports.
    • Reverse proxy if you already have Caddy/Nginx/Traefik.
  3. Open the installer’s Configure server link on your phone (or https://app.happier.dev) and sign in / create an account.
  4. On the computer where you want to run the daemon/terminal, run:
    • happier server add --server-url https://<your-server-url> --use
    • happier auth login
  5. If you installed Dev box, follow the printed “connect daemon” step and restart the stack/service.

Happier has two separate “things to connect”:

  • Your app/web UI needs to be configured to talk to your server
  • Your terminal/daemon needs to be connected to your account on that server

The Proxmox installer does not automatically authenticate for you. It prints the exact commands/links you need for the full flow.

1) Ensure you have a public HTTPS URL (remote access)

If you only access Happier from your LAN, plain HTTP can work.

For remote access (phone / outside your LAN), the web UI requires HTTPS (secure context). Use one of:

  • Tailscale Serve (recommended): easiest end-to-end HTTPS
  • Reverse proxy (Caddy / Nginx / Traefik): terminate TLS and proxy to the container

If you use a reverse proxy, the Proxmox installer will ask you for your public HTTPS URL and persist it in:

  • /home/happier/.happier/stacks/main/env as HAPPIER_STACK_SERVER_URL=https://<your-domain>

If you need to change it later, edit the same file and restart the stack/service.

Advanced: reverse proxy (Caddy / Nginx)

For a reverse proxy setup, you typically terminate TLS on your proxy and forward to:

  • http://<container-ip>:3005

Make sure your proxy supports WebSockets and forwards the usual “real URL” headers:

  • Host
  • X-Forwarded-Proto
  • X-Forwarded-Host
  • X-Forwarded-For

Also make sure the stack knows its public URL (for correct deep links/QR codes):

  • HAPPIER_STACK_SERVER_URL=https://<your-domain> in /home/happier/.happier/stacks/main/env

Then restart:

  • su - happier -c "/home/happier/.happier-stack/bin/hstack service restart --mode=system" (if autostart enabled)
  • su - happier -c "/home/happier/.happier-stack/bin/hstack start --restart" (manual start)

Caddy (recommended for simplest HTTPS)

Caddyfile:

happier.example.com {
  reverse_proxy http://<container-ip>:3005
}

If you’re running Caddy on the Proxmox host or another machine, replace <container-ip> with your container’s LAN IP.

Nginx (manual config)

Server block snippet:

server {
  listen 443 ssl http2;
  server_name happier.example.com;

  # TLS config omitted (use certbot, or your existing TLS setup)

  location / {
    proxy_pass http://<container-ip>:3005;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

If you use a UI-driven reverse proxy (e.g. Nginx Proxy Manager / Traefik), make sure “WebSocket support” is enabled and the upstream is http://<container-ip>:3005.

2) Configure your app/web UI to use your server

Use the installer’s printed “Configure server” links first. They:

  • pre-fill your server URL
  • help avoid “wrong server” confusion when you later connect a terminal/daemon

If you missed the output, re-print the links from inside the container:

  • /home/happier/.happier-stack/bin/hstack auth login --print --method=mobile --no-open

This will print:

  • A Configure server link (web + mobile deep link)
  • A Connect terminal link (web + mobile deep link) that includes server=...

Open the configure link first, confirm, then sign in/create your account.

If you chose not to serve the web UI from your Proxmox container, use:

  • the mobile app (recommended), or
  • the hosted web app at https://app.happier.dev and set the server there

3) Connect the terminal/daemon

Continue following the same hstack auth login output:

  • If you’re using the mobile app: scan the QR code / open the mobile deep link
  • If you’re using the web app: open the URL in a browser where you’re signed in

Because the link includes the server URL, the app/web UI can safely prompt you to switch servers (if needed) before approving the connection.

4) Start (or restart) the daemon (Dev box mode)

If you installed Dev box (server-light + daemon), the daemon is configured to wait for authentication on first install.

After login completes:

  • If autostart is enabled: /home/happier/.happier-stack/bin/hstack service restart --mode=system
  • Otherwise: /home/happier/.happier-stack/bin/hstack start --restart

Using Happier from another machine (common setup)

If you installed Server only on Proxmox, you’ll typically run the daemon/terminal from your laptop/desktop and point it at your Proxmox server.

On your laptop/desktop:

  • Save and switch to your self-hosted server:
    • happier server add --server-url https://<your-server-url> --use
  • Then connect your terminal/daemon:
    • happier auth login

This persists the server URL locally, then prints:

  • “Configure server” links (so you can point the app/web UI at your server)
  • “Connect terminal” links (so you can approve the machine connection)

For ongoing profile switching and multi-server usage, see Features → Multi-server.

Installer prompts (what they mean)

Installation type

  • Dev box (server-light + daemon): Installs the server and the daemon tooling. The installer starts the server; the daemon may require authentication before it can run.
  • Server only (no daemon): Installs only the server.

Serve the web UI

  • Yes: Builds the UI and serves it from the server.
  • No: Skips UI dependencies/build for a faster install.

Autostart at boot

  • Yes: Installs a systemd system service inside the container.
  • No: You start it manually.

Remote access / HTTPS

  • Tailscale (recommended): Installs Tailscale in the container and can set up an HTTPS URL via Tailscale Serve.
  • Reverse proxy: You terminate TLS yourself (Caddy / Nginx / Traefik / etc).
  • None: Local network only.

If you choose Tailscale, you can optionally paste a Tailscale pre-auth key (recommended: ephemeral, one-time). If you skip it (or leave it blank), the installer will still install Tailscale and you can enroll later from inside the container.

Tailscale enrollment (auto vs manual)

Tailscale enrollment is optional and depends on your tailnet policy:

  • Auto-enroll (optional): provide a pre-auth key during install. If it works, the installer will attempt to bring the node online and enable Tailscale Serve.
  • Manual enroll (always works): skip the key during install (or leave it blank), then run tailscale up later inside the container.

If enrollment fails or a key is rejected/expired/revoked, the installer prints a “Login URL” (when available) and the exact manual commands to run.

Manual enrollment commands (inside the container):

tailscale up
tailscale set --operator=happier
su - happier -c "/home/happier/.happier-stack/bin/hstack tailscale enable"
su - happier -c "/home/happier/.happier-stack/bin/hstack tailscale url"

HStack release channel

The installer runs hstack setup via npx (npm). You can choose which HStack build you want:

  • Stable (recommended): installs @happier-dev/stack@latest
  • Preview: installs @happier-dev/stack@next
  • Custom: pin a version (or a different npm spec)

Non-interactive overrides:

  • HAPPIER_PVE_HSTACK_CHANNEL=stable|preview (preview maps to npm @next)
  • HAPPIER_PVE_HSTACK_PACKAGE='@happier-dev/stack@<tag-or-version>' (takes precedence)

HTTPS guidance (important)

For remote usage, the Happier web UI needs HTTPS (secure context). Typical setups:

  • Tailscale Serve (easiest): gives you an HTTPS URL without opening ports.
  • Reverse proxy: terminate TLS on your network edge and proxy to http://<container-ip>:3005 (ensure WebSockets are supported).

Post-install: common commands

Enter the container from the Proxmox host:

  • pct enter <CTID>

Service management (if you enabled autostart):

  • su - happier -c "/home/happier/.happier-stack/bin/hstack service status --mode=system"
  • su - happier -c "/home/happier/.happier-stack/bin/hstack service logs --mode=system"
  • su - happier -c "/home/happier/.happier-stack/bin/hstack service tail"

If you chose Dev box (server-light + daemon), the server/UI can run before the daemon is authenticated. To connect it:

  1. Enter the container:
    • pct enter <CTID>
  2. Switch to the happier user:
    • su - happier
  3. Run mobile login (recommended):
    • /home/happier/.happier-stack/bin/hstack auth login --no-open --method=mobile

After login succeeds:

  • If autostart is enabled, restart the service so it starts the daemon too:
    • /home/happier/.happier-stack/bin/hstack service restart --mode=system
  • Or start the stack manually:
    • /home/happier/.happier-stack/bin/hstack start --restart

You can verify status with:

  • /home/happier/.happier-stack/bin/hstack auth status

If you enabled Tailscale but skipped the key, enroll later:

  • tailscale up
  • su - happier -c "/home/happier/.happier-stack/bin/hstack tailscale enable"
  • su - happier -c "/home/happier/.happier-stack/bin/hstack tailscale url"

Updating

At the moment the Proxmox helper script does not provide an in-place updater. The safest update paths are:

  • Re-run the installer in a fresh container, then migrate your data.
  • Or, update from inside the container using hstack (advanced; follow the hstack documentation for your deployment).

Docker

Deploy the Happier Server using Docker / Docker Compose.

Environment variables

Configuration for the Happier Server.

On this page

What you getInstall (recommended)Quick start (recommended)After install: recommended onboarding flow1) Ensure you have a public HTTPS URL (remote access)Advanced: reverse proxy (Caddy / Nginx)2) Configure your app/web UI to use your server3) Connect the terminal/daemon4) Start (or restart) the daemon (Dev box mode)Using Happier from another machine (common setup)Installer prompts (what they mean)Installation typeServe the web UIAutostart at bootRemote access / HTTPSTailscale enrollment (auto vs manual)HStack release channelHTTPS guidance (important)Post-install: common commandsDev box mode: connect the daemon (recommended)Updating