hestiacp-proxit

Per-domain, per-path reverse proxy for HestiaCP.

proxit adds a custom nginx proxy template to HestiaCP that lets each web domain define its own path → upstream routes — e.g. / → http://10.0.0.5:3000, /ma-assistant → http://10.0.0.5:8080 — editable from the Hestia WebUI domain-edit page (or the CLI), with full WebSocket support, and persistent across Hestia rebuilds, updates, and package upgrades.

It's ideal for putting a clean public hostname + Let's Encrypt cert in front of self-hosted apps (Home Assistant, n8n, Grafana, internal dashboards, …) without hand-editing nginx configs that get wiped on the next rebuild.

Not affiliated with HestiaCP. This is a third-party extension.

---

Features

• Per-domain, per-path routing, stored in a simple data file.
• WebSocket-ready — relays Upgrade/Connection and the 101 handshake (works with Home Assistant, etc.).
• Update-safe — the proxy template, hook and CLI live in Hestia's data/ and bin/ trees, which survive package upgrades. The only package-owned piece (the WebUI patch) is auto-reapplied after every apt/dpkg run.
• Switch-away safe — generated includes are named so that switching a domain back to another template can never collide and break nginx.
• WebUI + CLI — edit routes from the panel, or script them with v-* commands.
• Strict input validation on the CLI (paths and http(s)://host[:port][/path] targets only — rejects injection).

---

Requirements

• HestiaCP (tested on a current release; the nginx-proxy / apache-backend layout).
• Root access to the server.
• nginx as the front proxy (Hestia's default proxy setup).

---

Install

git clone https://forgejo.phillippepelzer.me/FiLL/hestiacp-proxit.git
cd hestiacp-proxit
sudo ./install.sh

The installer:

1. Installs the proxy template (proxit.tpl / proxit.stpl) and hook (proxit.sh) into $HESTIA/data/templates/web/nginx/.
2. Installs the CLI (v-change-web-domain-proxit, v-list-web-domain-proxit) into $HESTIA/bin/.
3. Installs the WebUI patch support into $HESTIA/data/proxit/ and applies the patch (backing up the originals first).
4. Installs an apt hook (/etc/apt/apt.conf.d/99-proxit-reapply) that re-applies the WebUI patch after any package update that overwrites it.

It does not modify any existing domain. Set HESTIA=/path if Hestia isn't at /usr/local/hestia.

---

Usage

WebUI

1. Edit a web domain in Hestia.
2. Set Proxy Template to proxit.
3. Add one or more path → target rows (e.g. / → http://127.0.0.1:3000).
4. Save — the domain is rebuilt and the routes go live.

CLI

List current mappings:

v-list-web-domain-proxit USER DOMAIN [shell|json|plain]

Set mappings (replaces all; ENTRIES is a newline-separated list of PATH TARGET):

v-change-web-domain-proxit USER DOMAIN $'/ http://127.0.0.1:3000\n/ma-assistant http://127.0.0.1:8080'

• Targets must be http(s)://host[:port][/path]; paths must start with /.
• The previous mapping is saved as <data>.prev for rollback.
• Rebuilds the domain (pass a 4th arg no to skip the reload).

---

How it works

data/users/<user>/proxit.<domain>.conf      (1) per-domain route data
        │  read by
templates/web/nginx/proxit.sh               (2) hook, run by Hestia on every
        │  generates                            add/rebuild of a proxit domain
<home>/<user>/conf/web/<domain>/
        nginx.proxit.conf / nginx.ssl.proxit.conf   (the location blocks)
        ▲  included by
templates/web/nginx/proxit.tpl / .stpl      (3) the proxy server blocks
web/edit/web/index.php + templates/pages/edit_web.php   (4) WebUI (patched)

1. Data — proxit.<domain>.conf, lines like LOCATION='/' TARGET='http://...'.
2. Hook — proxit.sh reads the data file and regenerates the per-domain location { … proxy_pass … } include (with WebSocket headers). Run automatically by Hestia on every domain add/rebuild.
3. Template — proxit.tpl / .stpl are the nginx proxy server blocks that include the generated routes.
4. WebUI — small marker-wrapped patches to two Hestia PHP files add the path → target editor when the proxy template is proxit.

Update-safety

Layers 1–3 live in Hestia's data//bin/ trees and survive updates untouched. The WebUI (layer 4) is package-owned, so data/proxit/reapply.sh (invoked by the apt DPkg::Post-Invoke hook) re-applies the patch after any package operation that overwrote it. It is idempotent and gated on php -l, so it never leaves a broken panel — if a Hestia update changes those PHP files so the diff no longer applies, it logs a warning and leaves the panel stock; the CLI keeps working regardless.

The WebUI patch is version-sensitive (it's a diff against specific Hestia source files). On a Hestia version where it can't apply cleanly, regenerate the diffs in data/proxit/patches/ and run data/proxit/reapply.sh. The proxy routing and CLI do not depend on the WebUI patch.

---

Uninstall

sudo ./uninstall.sh

Switch any domains off the proxit proxy template before uninstalling. The uninstaller reverts the WebUI patch, removes the template/hook/CLI/apt-hook, and leaves your per-domain proxit.*.conf data files in place (delete them manually if you want them gone).

---

License

GPL-3.0. See LICENSE. HestiaCP is GPL-3.0; the WebUI patch diffs are derived from its source.