diff --git a/cmd/waku/node.go b/cmd/waku/node.go index 92da475e..196eda80 100644 --- a/cmd/waku/node.go +++ b/cmd/waku/node.go @@ -73,13 +73,15 @@ func scalePerc(value float64) float64 { const dialTimeout = 7 * time.Second +const nonRecoverableErrorCode = 166 + func nonRecoverErrorMsg(format string, a ...any) error { err := fmt.Errorf(format, a...) return nonRecoverError(err) } func nonRecoverError(err error) error { - return cli.Exit(err.Error(), 166) + return cli.Exit(err.Error(), nonRecoverableErrorCode) } // Execute starts a go-waku node with settings determined by the Options parameter diff --git a/docs/operators/how-to/setup-systemd.md b/docs/operators/how-to/setup-systemd.md new file mode 100644 index 00000000..da34e36b --- /dev/null +++ b/docs/operators/how-to/setup-systemd.md @@ -0,0 +1,88 @@ +# Set up a systemd service + +This page will take you through how to set up a `systemd` service for go-waku. + +`systemd` is used in order to have a command or a program run when your device boots (i.e. add it as a service). +Once this is done, you can start/stop enable/disable from the linux prompt. + +!!! abstract "`systemd`" + [`systemd`](https://systemd.io/) is a service manager designed specifically for Linux: it cannot be used on Windows / Mac. + You can find out more about `systemd` [here](https://fedoramagazine.org/what-is-an-init-system/). + +!!! note "Package manager installations" + When installing go-waku via your package manager, a user and service will already have been created for you and you can skip straight to the configuration section. + +### 1. Create the service file + +`systemd` services are created by placing a [service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) file in `/etc/systemd/system`, or, if go-waku was installed by a package manager, `/usr/lib/systemd/system`. + +A good starting point is the [example service file](https://raw.githubusercontent.com/waku-org/go-waku/scripts/linux/waku.service) in the go-waku repository. + +```sh +# Download example service file and save it to `/etc/systemd/system/go-waku.service` +curl -s https://raw.githubusercontent.com/waku-org/go-waku/scripts/linux/go-waku.service | sudo tee /etc/systemd/system/waku.service > /dev/null +``` + +The format of service files is documented in the [systemd manual](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html). + +!!! note + go-waku has two return codes for errors: + - `1` returned for recoverable errors + - `166` returned for non-recoverable errors. + The example service file uses 166 in `RestartPreventExitStatus` to prevent automated restarts for non recoverable errors. + +### 2. Configure your service + +Service is configured by editing the service file directly, or using `systemctl edit` to create an override. + +```sh +# Edit the systemd file to match your installation +sudo vi /etc/systemd/system/waku.service + +# If you installed go-waku via the package manager, use `systemctl edit` instead +sudo systemctl edit waku.service +``` + +!!! note + The example assumes go-waku was installed in `/usr/bin/waku`. + If you installed go-waku elsewhere, make sure to update this path. + +### 3. Notify systemd of the newly added service + +Every time you add or update a service, the `systemd` daemon must be notified of the changes: + +```sh +sudo systemctl daemon-reload +``` + +### 4. Start the service + +```sh +# start go-waku node +sudo systemctl start waku + +# (Optional) Set go-waku to start automatically at boot +sudo systemctl enable waku +``` + +### 5. Check the status of the service + +`systemctl status` will show if go-waku is up and running, or has stopped for some reason. + +```sh +sudo systemctl status waku.service +``` + +You can also follow the logs using the following command: + +```sh +sudo journalctl -uf waku.service +``` + +This will show you the waku logs at the default setting. Press `ctrl-c` to stop following the logs. + +To rewind logs — by one day, say — run: + +```sh +sudo journalctl -u waku.service --since yesterday +``` diff --git a/scripts/linux/fpm-build.sh b/scripts/linux/fpm-build.sh index b3700821..01397dbf 100755 --- a/scripts/linux/fpm-build.sh +++ b/scripts/linux/fpm-build.sh @@ -18,28 +18,28 @@ cp ${parent_path}/build/waku ${tmpdir} strip --strip-unneeded ${tmpdir}/waku +cp ${parent_path}/scripts/linux/waku.service ${tmpdir} + pushd ${tmpdir} -fpm_build () { - fpm \ - -s dir -t $1 \ - -p gowaku-${VERSION}-x86_64.$1 \ - --name go-waku \ - --license "MIT, Apache 2.0" \ - --version ${VERSION} \ - --architecture x86_64 \ - --depends libc6 \ - --description "Go implementation of Waku v2 protocol" \ - --url "https://github.com/waku-org/go-waku" \ - --maintainer "Richard Ramos " \ - waku=/usr/bin/waku -} +fpm \ + -s dir -t deb \ + -p gowaku-${VERSION}-x86_64.deb \ + --name go-waku \ + --license "MIT, Apache 2.0" \ + --version ${VERSION} \ + --architecture x86_64 \ + --depends libc6 \ + --description "Go implementation of Waku v2 protocol" \ + --url "https://github.com/waku-org/go-waku" \ + --maintainer "Richard Ramos " \ + --deb-systemd=waku.service \ + waku=/usr/bin/waku -fpm_build "deb" -fpm_build "rpm" - -ls +fpm -s deb -t rpm -p gowaku-${VERSION}-x86_64.rpm *.deb mv *.deb *.rpm ${parent_path}/build/. +ls ${parent_path}/build/. + popd diff --git a/scripts/linux/waku.service b/scripts/linux/waku.service new file mode 100644 index 00000000..1d40db7d --- /dev/null +++ b/scripts/linux/waku.service @@ -0,0 +1,44 @@ +# To configure the service, use `systemctl edit waku.service` +# and override the environment variables in this file +# +# To completely override the start command, override the `ExecStart` value +# instead by first emptying it, then specifying a new one: +# +# [Service] +# ExecStart= +# ExecStart=/usr/bin/waku --cluster-id=1 + +[Unit] +Description=Waku +Wants=network-online.target +After=network-online.target + +[Install] +WantedBy=multi-user.target + +[Service] +# TWN +Environment=CLUSTER_ID=1 + +# Default ports +Environment=TCP_PORT=9000 +Environment=REST_ENABLED=true +Environment=REST_PORT=8645 +Environment=METRICS_ENABLED=true +Environment=METRICS_PORT=8008 + +# Default group = waku +WorkingDirectory=/var/lib/waku +TimeoutSec=1200 +Restart=always + +# List of non-recoverable error codes +RestartPreventExitStatus=166 + +ExecStart=/usr/bin/waku \ + --cluster-id=${CLUSTER_ID} \ + --port=${TCP_PORT} \ + --rest=${REST_ENABLED} \ + --rest-port=${REST_PORT} \ + --metrics=${METRICS_ENABLED} \ + --metrics-port=${METRICS_PORT}