docs: preserve lifecycle owner for Serve setup
This commit is contained in:
1 parent
56df987311
commit
816ebd5e47
1 file changed
+27
-19
+27
-19
@@ -71,28 +71,30 @@ WebUI through the maintained `start.sh` or systemd path.
|
||||
arbitrary generated password. Serve terminates HTTPS before proxying to the
|
||||
local HTTP backend, so `HERMES_WEBUI_SECURE=1` keeps the session cookie
|
||||
HTTPS-only.
|
||||
3. Stop any existing WebUI before changing its binding. A process listening on
|
||||
`0.0.0.0:8787` also answers the loopback health probe, so `start.sh` would
|
||||
otherwise report "already running" without applying the new host argument.
|
||||
Use `./ctl.sh stop` for a daemon started by `ctl.sh`. For any process
|
||||
supervisor — systemd, launchd, supervisord, runit, or s6 — use that
|
||||
supervisor's stop, unload, or down action from the
|
||||
[supervisor guide](supervisor.md), then verify it reports the service stopped
|
||||
and cannot auto-restart it. If WebUI was started directly, stop the exact
|
||||
listener using the PID instructions that `start.sh` prints. Do not continue
|
||||
until the previous listener has stopped.
|
||||
3. Restart WebUI through the same lifecycle owner that already manages it. A
|
||||
process listening on `0.0.0.0:8787` also answers the loopback health probe,
|
||||
so `start.sh` would otherwise report "already running" without applying the
|
||||
new host or reloading `HERMES_WEBUI_SECURE=1`.
|
||||
|
||||
Then pin and start the backend with launcher arguments, which override any
|
||||
conflicting host or port values from `.env`:
|
||||
For a daemon started by `ctl.sh`, keep ownership with the controller:
|
||||
|
||||
```bash
|
||||
./ctl.sh stop
|
||||
./ctl.sh start 8787 --host 127.0.0.1
|
||||
```
|
||||
|
||||
For a direct `start.sh` launch, stop the exact listener using the PID
|
||||
instructions that `start.sh` prints, verify it has stopped, then run:
|
||||
|
||||
```bash
|
||||
./start.sh 8787 --host 127.0.0.1
|
||||
```
|
||||
|
||||
For a systemd launch, keep the password (unless it is already configured
|
||||
through Settings) and `HERMES_WEBUI_SECURE=1` in the checkout's `.env`.
|
||||
Then adapt the unit from the [supervisor guide](supervisor.md) so its
|
||||
`ExecStart` pins host and port with arguments too:
|
||||
For systemd, launchd, supervisord, runit, or s6, use that supervisor's stop,
|
||||
unload, or down action from the [supervisor guide](supervisor.md), update its
|
||||
configured launch command with `8787 --host 127.0.0.1`, and start it again
|
||||
through the same supervisor. Do not launch `start.sh` directly while a
|
||||
supervisor owns the service. For example, a systemd unit uses:
|
||||
|
||||
```ini
|
||||
ExecStart=/bin/bash %h/hermes-webui/start.sh 8787 --host 127.0.0.1 --foreground
|
||||
@@ -100,8 +102,11 @@ WebUI through the maintained `start.sh` or systemd path.
|
||||
|
||||
Do not rely on systemd `Environment=` entries to override conflicting
|
||||
values in `.env`: `start.sh` loads that file after the service environment.
|
||||
Run `systemctl --user daemon-reload` and restart the stopped unit after
|
||||
editing it.
|
||||
Keep the password (unless it is already configured through Settings) and
|
||||
`HERMES_WEBUI_SECURE=1` in the checkout's `.env`; do not rely on systemd
|
||||
`Environment=` entries to override that later-loaded file. Stop the unit,
|
||||
edit it, run `systemctl --user daemon-reload`, and start it again. Do not
|
||||
continue until the selected lifecycle owner reports the new process running.
|
||||
|
||||
For a different trusted reverse proxy that sets `X-Forwarded-Proto: https`,
|
||||
`HERMES_WEBUI_TRUST_FORWARDED_PROTO=1` is the alternative. Keep the explicit
|
||||
@@ -165,10 +170,13 @@ server's Tailscale IP. Because this fallback uses plain HTTP, change the cookie
|
||||
setting before restarting WebUI while keeping the password non-empty:
|
||||
|
||||
```dotenv
|
||||
HERMES_WEBUI_PASSWORD=replace-with-a-strong-password
|
||||
HERMES_WEBUI_PASSWORD='replace-with-a-long-random-password'
|
||||
HERMES_WEBUI_SECURE=0
|
||||
```
|
||||
|
||||
Stop and restart through the same lifecycle owner described in step 3, changing
|
||||
that owner's host argument to `0.0.0.0`. For a direct launch only, run:
|
||||
|
||||
```bash
|
||||
./start.sh 8787 --host 0.0.0.0
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user