update docs for systemd / reorganize supplemental directory

2025-10-19 01:39:34 +08:00 · 2024-08-01 17:40:15 -04:00
parent 092f09b084
commit 0f9aa11255
4 changed files with 128 additions and 135 deletions
--- a/supplemental/guides/systemd.md
+++ b/supplemental/guides/systemd.md
@@ -0,0 +1,125 @@
+# Installing as a Linux systemd service
+
+This is useful if you want to run the hub or agent in the background continuously, including after a reboot.
+
+## Install script (recommended)
+
+There are two scripts, one for the hub and one for the agent. You can run either one, or both.
+
+The install script creates a dedicated user for the service (`beszel`), downloads the latest release, and installs the service.
+
+> [!NOTE]
+> You need system administrator privileges to run the install script. If you encounter a problem, please [open an issue](https://github.com/henrygd/beszel/issues/new).
+
+### Hub
+
+Download the script:
+
+```bash
+curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh
+```
+
+#### Install
+
+```bash
+./install-hub.sh
+```
+
+#### Uninstall
+
+```bash
+./install-hub.sh -u
+```
+
+#### Update
+
+```bash
+sudo /opt/beszel/beszel update && sudo systemctl restart beszel
+```
+
+### Agent
+
+Download the script:
+
+```bash
+curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh
+```
+
+#### Install
+
+You may optionally include the SSH key and port as arguments. Run `./install-agent.sh -h` for more info.
+
+```bash
+./install-agent.sh
+```
+
+#### Uninstall
+
+```bash
+./install-agent.sh -u
+```
+
+#### Update
+
+```bash
+sudo /opt/beszel-agent/beszel-agent update && sudo systemctl restart beszel-agent
+```
+
+## Manual install
+
+1. Create the system service at `/etc/systemd/system/beszel.service`
+
+```bash
+[Unit]
+Description=Beszel Hub Service
+After=network.target
+
+[Service]
+# update the values in the curly braces below (remove the braces)
+ExecStart={/path/to/working/directory}/beszel serve
+WorkingDirectory={/path/to/working/directory}
+User={YOUR_USERNAME}
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+2. Start and enable the service to let it run after system boot
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable beszel.service
+sudo systemctl start beszel.service
+```
+
+## Run the agent as a system service (Linux)
+
+This runs the agent in the background continuously using systemd.
+
+1. Create the system service at `/etc/systemd/system/beszel-agent.service`
+
+```bash
+[Unit]
+Description=Beszel Agent Service
+After=network.target
+
+[Service]
+# update the values in curly braces below (remove the braces)
+Environment="PORT={PASTE_YOUR_PORT_HERE}"
+Environment="KEY={PASTE_YOUR_KEY_HERE}"
+ExecStart={/path/to/directory}/beszel-agent
+User={YOUR_USERNAME}
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+2. Start and enable the service to let it run after system boot
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable beszel-agent.service
+sudo systemctl start beszel-agent.service
+```