[Docs] Add service how-tos

4 files changed, 307 insertions, 0 deletions

diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md
index 289f028f2..9ef1ddde6 100644
--- a/docs/source/how-to/index.md
+++ b/docs/source/how-to/index.md
@@ -2,4 +2,18 @@
 
 A collection of guides covering common issues that might be encountered using Deluge.
 
+## GTK UI
+
 - [Set default torrent application](set-mime-type.md)
+
+## Deluge as a service
+
+Services are used to start applications on system boot and leave them running
+in the background. They will also stop the application nicely on system
+shutdown and automatically restart them if they crash.
+
+The Deluge daemon deluged and Web UI deluge-web can both be run as services.
+
+- [Create systemd services for Linux](systemd-service.md)
+- [Create launchd services for macOS](launchd-service.md)
+- [Create NSSM services for Windows](nssm-service.md)
diff --git a/docs/source/how-to/launchd-service.md b/docs/source/how-to/launchd-service.md
new file mode 100644
index 000000000..b988a19e3
--- /dev/null
+++ b/docs/source/how-to/launchd-service.md
@@ -0,0 +1,50 @@
+# How to create launchd services for macOS
+
+The following launchd script uses a separate user deluge, this is optional
+but recommended for security. To create a new deluge user follow the
+​[Apple help] steps.
+
+The paths to `deluged` and `deluge-web` assumes installation using [Homebrew]
+and will need modified if using other installation methods e.g. `Deluge.app`.
+
+## Daemon (deluged) service
+
+Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluged.plist`
+containing the following:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluged.plist
+    :language: xml
+```
+
+Set the service to load on startup and then start it:
+
+```console
+sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluged.plist
+sudo launchctl start org.deluge-torrent.deluged
+```
+
+## Web UI (deluge-web) service
+
+Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist`
+containing the following:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluge-web.plist
+    :language: xml
+```
+
+Set the service to load on startup and then start it:
+
+```console
+sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist
+sudo launchctl start org.deluge-torrent.deluge-web
+```
+
+## Logging
+
+Logging is enabled by default in the above script, error level, and can be
+modified as required.
+
+[apple help]: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac
+[homebrew]: https://brew.sh/
diff --git a/docs/source/how-to/nssm-service.md b/docs/source/how-to/nssm-service.md
new file mode 100644
index 000000000..1e39bf453
--- /dev/null
+++ b/docs/source/how-to/nssm-service.md
@@ -0,0 +1,38 @@
+# How to create NSSM services for Windows
+
+Download ​[NSSM] and read their usage page about installing.
+
+In order for the services to be stopped properly, use the debug application
+versions (ending in `-debug.exe`).
+
+## Daemon (deluged) service
+
+Create a `deluged` service:
+
+```console
+nssm install deluged
+```
+
+The following are minimum UI changes required for the service to work:
+
+```
+Path: C:\Program Files\Deluge\deluged-debug.exe
+Arguments: -c C:\config_location
+```
+
+## Web UI (deluge-web) service
+
+```console
+nssm install deluge-web
+```
+
+```
+Path: C:\Program Files\Deluge\deluge-web-debug.exe
+Arguments: -c C:\config_location
+```
+
+If Web UI is not accessible outside your machine (if you're running
+Deluge from a home server), you have to whitelist Deluge in your Windows
+Firewall for the `deluge-web` and `deluge-web-debug` executable.
+
+[nssm]: http://nssm.cc/
diff --git a/docs/source/how-to/systemd-service.md b/docs/source/how-to/systemd-service.md
new file mode 100644
index 000000000..6b785ad15
--- /dev/null
+++ b/docs/source/how-to/systemd-service.md
@@ -0,0 +1,205 @@
+# How to create systemd services for Linux
+
+This guide walks you through setting up Deluge systemd services on Linux.
+
+Ensure Deluge daemon `deluged` and Web UI `deluge-web` are installed. Use
+`which` to check installation paths and if necessary modify the service
+file `ExecStart` lines to point to alternative paths.
+
+## Create a service specific user
+
+For security it is best to run a service with a specific user and group.
+You can create one using the following command:
+
+```console
+sudo adduser --system  --gecos "Deluge Service" --disabled-password --group --home /var/lib/deluge deluge
+```
+
+This creates a new system user and group named `deluge` with no login access
+and home directory `/var/lib/deluge` which will be the default location for the
+config files.
+
+In addition you can add to the `deluge` group any users you wish to be able to
+easily manage or access files downloaded by Deluge, for example:
+
+```console
+sudo adduser <username> deluge
+```
+
+## Daemon (deluged) service
+
+Create the file `/etc/systemd/system/deluged.service` containing the following:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/systemd/deluged.service
+    :language: ini
+```
+
+### User configuration
+
+To run the service using the previously created user e.g. `deluge`, first
+create the service configuration directory:
+
+```console
+sudo mkdir /etc/systemd/system/deluged.service.d/
+```
+
+Then create a user file `/etc/systemd/system/deluged.service.d/user.conf` with
+the following contents:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/systemd/user.conf
+    :language: ini
+```
+
+### Start deluged service
+
+Now enable it to start up on boot, start the service and verify it is running:
+
+```console
+sudo systemctl enable /etc/systemd/system/deluged.service
+sudo systemctl start deluged
+sudo systemctl status deluged
+```
+
+### Umask for deluged downloaded files
+
+The `umask` in the service file can be modified to determine access to files
+downloaded by deluged (also applies to logging files). Some useful access
+values are detailed as follows:
+
+- `000` - full access for all users and groups.
+- `007` - only user and group that `deluged` is running as (e.g. `deluge`)
+  with no access from any other accounts.
+- `002` - user and group `deluged` is running as with read-only for all other
+  accounts.
+- `022` - user `deluged` is running as with read-only for all other accounts.
+
+The service for `deluged` must be stopped and started instead of just restarted
+after changes.
+
+## Web UI (deluge-web) service
+
+Create the file `/etc/systemd/system/deluge-web.service` containing the following:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/systemd/deluge-web.service
+    :language: ini
+```
+
+### User configuration
+
+To run the service using the previously created user e.g. `deluge`, first
+create the service configuration directory:
+
+```
+sudo mkdir /etc/systemd/system/deluge-web.service.d/
+```
+
+Then create a user file `/etc/systemd/system/deluge-web.service.d/user.conf` with
+the following contents:
+
+```eval_rst
+.. literalinclude:: ../../../packaging/systemd/user.conf
+    :language: ini
+```
+
+### Start deluge-web service
+
+Now enable it to start up on boot, start the service and verify it is running:
+
+```console
+sudo systemctl enable /etc/systemd/system/deluge-web.service
+sudo systemctl start deluge-web
+sudo systemctl status deluge-web
+```
+
+## Service logging
+
+Create a log directory for Deluge and give the service user (e.g. `deluge`), full access:
+
+```console
+sudo mkdir -p /var/log/deluge
+sudo chown -R deluge:deluge /var/log/deluge
+sudo chmod -R 750 /var/log/deluge
+```
+
+The deluge log directory is now configured so that user `deluge` has full
+access, group `deluge` read only and everyone else denied access. The `umask`
+specified in the services sets the permission of new log files.
+
+Enable logging in the service files by editing the `ExecStart` line, appending
+`-l` and `-L` options:
+
+```
+ExecStart=/usr/bin/deluged -d -l /var/log/deluge/daemon.log -L warning
+```
+
+```
+ExecStart=/usr/bin/deluge-web -d -l /var/log/deluge/web.log -L warning
+```
+
+See `deluged -h` for all available log-levels.
+
+Restart the services:
+
+```console
+sudo systemctl daemon-reload
+sudo systemctl restart deluged
+sudo systemctl restart deluge-web
+```
+
+### Log rotation
+
+To enable log rotation append `--logrotate` to the above `ExecStart` lines.
+
+## Conditionally start deluged for mount points
+
+If you have a USB disk drive or network drive that may not be immediately
+available on boot or disconnected at random then you may want the `deluged`
+service to wait for mount point to be ready before starting. If they are
+unmounted or disconnected then `deluged` is stopped. When they become available
+again `deluged` is started.
+
+Ensure you have added the correct drive details to `fstab` or equivalent so
+they are mounted at boot.
+
+List the available drive mounts:
+
+```console
+sudo systemctl -t mount
+```
+
+Look for your mount point in the `Description` column. Mounts are formatted
+similar to the mount point with `-`s replacing `/`s in the path.
+e.g.: `media-xyz.mount`
+
+Modify the `[Unit]` section of the `deluged.service` script by adding the
+details below, substituting `xyz.mount` for the mount you want the service
+to depend on:
+
+```ini
+[Unit]
+Description=Deluge Bittorrent Client Daemon
+# Start after network and specified mounts are available.
+After=network-online.target xyz.mount
+Requires=xyz.mount
+# Stops deluged if mount points disconnect
+BindsTo=xyz.mount
+```
+
+For multiple mount points add a space between additional entries. e.g.:
+
+```init
+After=network-online.target xyz.mount abc.mount def.mount
+```
+
+Modify the `[Install]` section to ensure the deluged service is started when
+the mount point comes back online:
+
+```ini
+[Install]
+WantedBy=multi-user.target xyz.mount
+```
+
+Reference: [systemd.unit](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiresMountsFor=)