Skip to content

Commit e08ccea

Browse files
confuserconfuser
authored
docs(webui): restructure install guide into hub-and-spoke + add deployment page (#502)
Splits the monolithic install.mdx into a hub at /docs/webui/install/ that covers prerequisites, the WebEnhancer plugin, env-var reference, security notes, and troubleshooting, plus three dedicated pages for the Docker Compose, browser /setup, and CLI wizard install paths. Adds a separate /docs/webui/deployment guide for production concerns: running under systemd or Docker, reverse-proxy snippets for Caddy, Apache and nginx (with Let's Encrypt), sub-directory installs via BASE_PATH, and the /health endpoint for monitoring. Teaches scripts/generate-navigation.mjs to honour an optional numeric navOrder front-matter field so the sidebar lists Install -> Docker -> Web installer -> CLI -> Deployment in that order; falls back to the existing alphabetical sort when navOrder is absent.
1 parent 378b1e7 commit e08ccea

8 files changed

Lines changed: 882 additions & 181 deletions

File tree

‎content/docs/webui/deployment.mdx‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
layout: 'docs'
3+
title: 'Deployment'
4+
navTitle: 'Deployment'
5+
navOrder: 14
6+
category: 'Web UI'
7+
description: 'Run the BanManager WebUI in production: keep it alive with systemd or Docker, and serve it over HTTPS with Caddy, Apache, or nginx.'
8+
---
9+
This page covers everything you need to take a working WebUI install (see [Install](/docs/webui/install)) and put it in front of real users: a process manager so the WebUI restarts automatically on crash or reboot, and a reverse proxy so you can serve it over HTTPS on a real domain.
10+
11+
## Run as a service
12+
13+
You almost certainly want the WebUI to come back up after a crash or reboot. Pick whichever option matches your install:
14+
15+
### systemd (recommended for non-Docker installs)
16+
17+
The WebUI ships a setup helper that generates a `systemd` unit, enables it, starts it, and tails the journal so you can see whether the boot was successful:
18+
19+
```bash
20+
npx bmwebui setup systemd
21+
```
22+
23+
You'll be asked which user to run the service as (defaults to your current user — pick a non-root, non-sudo user for safety). The helper:
24+
25+
- Writes `/etc/systemd/system/bmwebui.service` based on the [bundled template](https://github.com/BanManagement/BanManager-WebUI/blob/master/cli/commands/setup/bmwebui.service.template).
26+
- Runs `sudo systemctl enable bmwebui.service` so it starts on boot.
27+
- Starts the service and waits up to 60 seconds for `http://localhost:PORT/` to respond.
28+
- Streams `journalctl -f` so you can watch the first boot.
29+
30+
The service uses `Restart=always`, runs `npm run build` as a `ExecStartPre`, then `node server.js`. It runs in the directory you executed `npx bmwebui setup systemd` from.
31+
32+
**Day-to-day commands:**
33+
34+
```bash
35+
sudo systemctl status bmwebui.service
36+
sudo systemctl restart bmwebui.service
37+
sudo journalctl -u bmwebui.service -f
38+
```
39+
40+
### Docker
41+
42+
The published Compose files (`docker-compose.prod.yml` and `docker-compose.prod-no-db.yml`) already declare `restart: unless-stopped`, so Docker handles restart-on-crash and restart-on-boot for you. Nothing extra is required.
43+
44+
To restart manually after a config change:
45+
46+
```bash
47+
docker compose restart webui
48+
```
49+
50+
### PM2 and other managers
51+
52+
PM2, Forever, and similar managers all work with the WebUI — point them at `node server.js` in the install directory. They aren't covered in detail here.
53+
54+
---
55+
56+
## Reverse proxy (HTTPS)
57+
58+
For any non-Docker public install you'll want a reverse proxy in front of the WebUI to:
59+
60+
- Terminate TLS so users get HTTPS.
61+
- Add HTTP→HTTPS redirects.
62+
- Optionally mount the WebUI on a sub-path (e.g. `https://example.com/banmanager`).
63+
64+
The WebUI ships templates and helper commands for the three most common reverse proxies. Pick whichever you're already comfortable with — for greenfield installs, **Caddy** is the easiest because it manages HTTPS automatically.
65+
66+
> **Don't forget `TRUST_PROXY=true`.** When the WebUI sits behind a reverse proxy, set `TRUST_PROXY=true` in your `.env` so it reads `X-Forwarded-For` and `X-Forwarded-Proto`. Without it the WebUI thinks every request is coming from `127.0.0.1`, so the "Your connection is not encrypted" warning on `/setup` won't appear even when an external user is connecting over plain HTTP.
67+
68+
### Caddy (automatic HTTPS)
69+
70+
```bash
71+
npx bmwebui setup caddy
72+
```
73+
74+
Caddy provisions and renews a Let's Encrypt certificate automatically — there's no separate `certbot` step. The helper:
75+
76+
- Asks for your domain and (optional) sub-path.
77+
- Writes a snippet to `/etc/caddy/Caddyfile.d/<domain>.caddy`.
78+
- Validates the config and reloads Caddy.
79+
80+
Make sure your main `/etc/caddy/Caddyfile` includes the snippet directory:
81+
82+
```caddyfile
83+
import Caddyfile.d/*.caddy
84+
```
85+
86+
### Apache
87+
88+
```bash
89+
npx bmwebui setup apache
90+
```
91+
92+
Apache is auto-detected on both Debian (`/etc/apache2`) and RHEL (`/etc/httpd`). The helper:
93+
94+
- Writes a virtual host config to the right `sites-available` / `conf.d` directory.
95+
- Enables `proxy`, `proxy_http`, `proxy_wstunnel`, `rewrite`, and `headers` modules.
96+
- Reloads Apache.
97+
98+
To add HTTPS:
99+
100+
```bash
101+
# Debian / Ubuntu
102+
sudo apt install certbot python3-certbot-apache
103+
sudo certbot --apache -d example.com
104+
105+
# RHEL / Fedora
106+
sudo dnf install certbot python3-certbot-apache
107+
sudo certbot --apache -d example.com
108+
```
109+
110+
`certbot` rewrites the file you just generated to add HTTPS and a HTTP→HTTPS redirect.
111+
112+
### nginx
113+
114+
```bash
115+
npx bmwebui setup nginx
116+
```
117+
118+
The helper:
119+
120+
- Asks for your domain and (optional) sub-path.
121+
- Writes a config to `/etc/nginx/sites-available/<domain>` and symlinks it into `sites-enabled`.
122+
- Reloads nginx.
123+
124+
To add HTTPS via Let's Encrypt:
125+
126+
```bash
127+
sudo apt install certbot python3-certbot-nginx
128+
sudo certbot --nginx -d example.com
129+
```
130+
131+
`certbot` rewrites the generated config to add HTTPS and a HTTP→HTTPS redirect.
132+
133+
---
134+
135+
## Sub-directory installs (`BASE_PATH`)
136+
137+
To mount the WebUI on a sub-path (e.g. `https://example.com/banmanager`), set `BASE_PATH` in your `.env`:
138+
139+
```bash
140+
BASE_PATH=/banmanager
141+
```
142+
143+
Then re-build and restart so Next.js bakes the sub-path into the assets:
144+
145+
```bash
146+
npm run build
147+
sudo systemctl restart bmwebui.service # or: docker compose restart webui
148+
```
149+
150+
Finally, re-run the proxy helper (`npx bmwebui setup caddy|apache|nginx`) — it'll pick up the new `BASE_PATH` and generate a config that mounts the WebUI at that prefix. The proxy helpers will refuse to continue if `BASE_PATH` doesn't match the sub-path you enter, and remind you to re-build.
151+
152+
---
153+
154+
## Health monitoring
155+
156+
The WebUI exposes an unauthenticated `/health` endpoint suitable for uptime checks and load-balancer probes. It returns JSON like:
157+
158+
```json
159+
{
160+
"status": "ok",
161+
"version": "x.y.z",
162+
"migrations": "up-to-date",
163+
"admin": "present"
164+
}
165+
```
166+
167+
`status` is one of:
168+
169+
- `"ok"` — fully configured and serving traffic. HTTP 200.
170+
- `"setup_required"` — server is in setup mode. HTTP 200.
171+
- `"db_unreachable"` — database connection failed. HTTP 503 (so most uptime monitors will alert).

‎content/docs/webui/install.mdx‎

Lines changed: 0 additions & 176 deletions
This file was deleted.

0 commit comments

Comments
 (0)