From 0f9aa11255c3881a5b33663135b17d42df637284 Mon Sep 17 00:00:00 2001 From: Henry Dollman Date: Thu, 1 Aug 2024 17:40:15 -0400 Subject: [PATCH] update docs for systemd / reorganize supplemental directory --- readme.md | 78 +---------- .../same-system/docker-compose.yml | 0 supplemental/guides/systemd.md | 125 ++++++++++++++++++ supplemental/systemd/readme.md | 60 --------- 4 files changed, 128 insertions(+), 135 deletions(-) rename supplemental/docker/{examples => }/same-system/docker-compose.yml (100%) create mode 100644 supplemental/guides/systemd.md delete mode 100644 supplemental/systemd/readme.md diff --git a/readme.md b/readme.md index 497622e..db47eb7 100644 --- a/readme.md +++ b/readme.md @@ -61,73 +61,9 @@ If you don't need network stats, remove that line from the compose file and map ### Binary -#### Beszel Agent +> [!TIP] +> If using Linux, see [guides/systemd.md](/supplemental/guides/systemd.md) for a script to install the hub or agent as a system service. The agent installer will be built into the web UI in the future. -##### Prerequisites - -- Debian or Ubuntu distribution - -- System administrator privileges - -##### Installation - -To install Beszel Agent, follow these steps: - -1. Download the Beszel Agent installation script: wget https://raw.githubusercontent.com/henrygd/beszel/master/install-agent.sh - -2. Make the script executable: chmod +x install-agent.sh - -3. Run the script with the desired options: - -- ./install-agent.sh -k -p (specify the SSH key and port) - -- ./install-agent.sh -h (display the help message) - -4. Follow the prompts to complete the installation - -##### Uninstallation - -1. To uninstall Beszel Agent, follow these steps: - -2. Run the installation script with the -u option: ./install-agent.sh -u - -Follow the prompts to complete the uninstallation - -#### Beszel Hub - -##### Prerequisites - -- Debian or Ubuntu distribution - -- System administrator privileges - -##### Installation - -To install Beszel Hub, follow these steps: - -1. Download the Beszel Hub installation script: wget https://raw.githubusercontent.com/henrygd/beszel/master/install-hub.sh - -2. Make the script executable: chmod +x install-hub.sh - -3. Run the script: - -- ./install-hub.sh - -- ./install-hub.sh -h (display the help message) - -4. Follow the prompts to complete the installation - -##### Uninstallation - -To uninstall Beszel Hub, follow these steps: - - - -1. Run the installation script with the -u option: ./install-hub.sh -u - -2. Follow the prompts to complete the uninstallation - -### Alternative Binary Download and run the latest binaries from the [releases page](https://github.com/henrygd/beszel/releases) or use the commands below. #### Hub @@ -154,18 +90,10 @@ Running the agent directly: PORT=45876 KEY="{PASTE_YOUR_KEY}" ./beszel-agent ``` -#### Running as a system service (Linux) - -See [supplemental/systemd](/supplemental/systemd) for instructions on running in the background using systemd. - -In the future there will be a one line command for installing the binary and setting up the service. - #### Updating Use `./beszel update` and `./beszel-agent update` to update to the latest version. -If using systemd, run `sudo systemctl restart beszel` and `sudo systemctl restart beszel-agent` to restart the services. - ## Environment Variables ### Hub @@ -263,7 +191,7 @@ Connectivity can be tested by running `telnet `. ### Connecting the hub and agent on the same system using Docker -If using host network mode for the agent but not the hub, you can add your system using the hostname `host.docker.internal`, which resolves to the internal IP address used by the host. See [example docker-compose.yml](/supplemental/docker/examples/same-system/docker-compose.yml). +If using host network mode for the agent but not the hub, you can add your system using the hostname `host.docker.internal`, which resolves to the internal IP address used by the host. See [example docker-compose.yml](/supplemental/docker/same-system/docker-compose.yml). If using host network for both, you can use `localhost` as the hostname. diff --git a/supplemental/docker/examples/same-system/docker-compose.yml b/supplemental/docker/same-system/docker-compose.yml similarity index 100% rename from supplemental/docker/examples/same-system/docker-compose.yml rename to supplemental/docker/same-system/docker-compose.yml diff --git a/supplemental/guides/systemd.md b/supplemental/guides/systemd.md new file mode 100644 index 0000000..68fb515 --- /dev/null +++ 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 +``` diff --git a/supplemental/systemd/readme.md b/supplemental/systemd/readme.md deleted file mode 100644 index 14907be..0000000 --- a/supplemental/systemd/readme.md +++ /dev/null @@ -1,60 +0,0 @@ -## Run the hub as a system service (Linux) - -This runs the hub in the background continuously using systemd. - -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 -```