Refactor and clarify setup_selfbuild.md and setup_debian.md

docs/bot/setup_debian.md

@@ -5,7 +5,7 @@ sidebar_label: Installation on Debian
 
 <!-- cspell:ignore SUIDSGID, EPERM, tunables -->
 
-# Installation on Debian
+# Installation
 
 :::tip
 
@@ -14,106 +14,149 @@ This installation method is intended for experienced sysadmins.
 
 :::
 
-## Installation
+## Prerequisites & System User
 
-install git curl and sudo
+### Install System Packages
 
-```shell
-apt update && apt install -y git curl sudo
+Update `apt` and install required tools **as your root user**:
+
+```bash
+apt update
+apt install -y git curl sudo
 ```
 
-install node 20 from the node source repo, the full instructions can be found at https://nodesource.com/products/distributions
+- `git` : version control
+- `curl` : data transfer
+- `sudo` : execute commands as root
+
+### Create User
+
+Create the `draupnir` system user (no login shell):
+
+```bash
+useradd --system --home-dir /opt/draupnir draupnir
+```
 
-```shell
+### Install Node.js (v20)
+
+Draupnir requires Node.js 20.x. Install via NodeSource:
+
+```bash
 curl -fsSL https://deb.nodesource.com/setup_20.x -o nodesource_setup.sh
 bash nodesource_setup.sh
-apt update && apt install nodejs -y
+apt update
+apt install -y nodejs
 ```
 
-install yarn via npm
+Verify Node.js version:
 
-```shell
-npm install --global yarn
+```bash
+node --version
+# Should output v20.x.x
 ```
 
-create the directory to clone the repo
+## Install Yarn
 
-```shell
-mkdir /opt/mod-bot
+```bash
+npm install --global [email protected]
+yarn --version
 ```
 
-clone the repo and fetch the tags
+## Setup Directories & Permissions
 
-```shell
-git clone https://github.com/the-draupnir-project/Draupnir.git /opt/mod-bot/Draupnir
+Clone the repository:
+
+```bash
+git clone https://github.com/the-draupnir-project/Draupnir.git /opt/draupnir
 ```
 
-```shell
-git -C /opt/mod-bot/Draupnir fetch --tags
+Create the data directory:
+
+```bash
+mkdir -p /var/lib/draupnir
 ```
 
-create the directory for draupnirs datastorage
+Change ownership to `draupnir`:
 
-```shell
-mkdir /opt/mod-bot/Draupnir/datastorage
+```bash
+chown draupnir:draupnir /var/lib/draupnir
+chown -R draupnir:draupnir /opt/draupnir
 ```
 
-add corepack
+## Build Draupnir
 
-```shell
-yarn global add corepack
+Switch to the `draupnir` user:
+
+```bash
+su - draupnir
 ```
 
-add a user to run the bot
-this user will be used by systemd to run the bot since there is no need to run it with root permissions
+Then within that shell:
+
+Fetch all tags:
 
-```shell
-useradd -m draupnir
+```bash
+cd /opt/draupnir
+git fetch --tags
 ```
 
-give ownership of the draupnir directory to the bot user
+Check out the latest tag:
 
-```shell
-chown -R draupnir:draupnir /opt/mod-bot/Draupnir
+```bash
+latest_tag=$(git tag --sort=version:refname | tail -n1)
+git checkout "$latest_tag"
 ```
 
-build the bot with yarn
+### Install Dependencies & Build
 
-```shell
-sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && yarn install"
-sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && yarn build"
+Run as `draupnir`:
+
+```bash
+yarn install
+yarn build
 ```
 
-## Edit the config
+- `yarn install` installs dependencies
+- `yarn build` compiles TypeScript into `lib/`
+
+## Configure Draupnir
 
-copy the default config to production.yaml
+Still under `draupnir`:
 
-```shell
-cp /opt/mod-bot/Draupnir/config/default.yaml /opt/mod-bot/Draupnir/config/production.yaml
+Copy the default config:
+
+```bash
+cp /opt/draupnir/config/default.yaml /opt/draupnir/config/production.yaml
 ```
 
-change the path of the datadirectory from the default to the directory we created earlier since the default dir is for the docker setup
+Update the data path:
 
-```shell
-sed -i 's|dataPath: "/data/storage"|dataPath: "/opt/mod-bot/Draupnir/datastorage"|' /opt/mod-bot/Draupnir/config/production.yaml
+```bash
+sed -i 's|dataPath: "/data/storage"|dataPath: "/var/lib/draupnir"|' /opt/draupnir/config/production.yaml
 ```
 
-edit the production config:
-the most important things to configure are the `homeserverUrl:`, the `rawHomeserverUrl:`, the `accessToken:` and the `managementRoom:`
+Edit production settings:
 
-```shell
-nano /opt/mod-bot/Draupnir/config/production.yaml
+```bash
+nano /opt/draupnir/config/production.yaml
 ```
 
-## Example systemd service
+Set at least:
 
-copy this to `/etc/systemd/system/draupnir.service` and enable with `systemctl enable draupnir`, then simply start with `systemctl start draupnir`
+- `homeserverUrl:` (e.g., `https://matrix.example.com`)
+- `rawHomeserverUrl:` (e.g., `https://matrix.example.com`)
+- `accessToken:` (your bot's access token)
+- `managementRoom:` (e.g., `!roomid:example.com`)
 
-:::tip
+Exit the `draupnir` user shell:
 
-before you attempt to start the service, make sure that the management room for draupnir exists on your homeserver and is joinable by draupnir (either public room or invite the bot account in advance)
+```bash
+exit
+```
 
-:::
+## Create Systemd Service
+
+As your root user, create `/etc/systemd/system/draupnir.service`:
 
 ```ini
 [Unit]
@@ -122,15 +165,16 @@ Description=Draupnir
 #After=matrix-synapse.target        # You can enable this if your matrix server is synapse and you have installed workers via the official instructions
 
 [Service]
-ExecStart=/usr/bin/node /opt/mod-bot/Draupnir/lib/index.js --draupnir-config /opt/mod-bot/Draupnir/config/production.yaml
-WorkingDirectory=/opt/mod-bot/Draupnir
+ExecStart=/usr/bin/node /opt/draupnir/lib/index.js --draupnir-config /opt/draupnir/config/production.yaml
+WorkingDirectory=/opt/draupnir
 Restart=always
 User=draupnir
 Environment=PATH=/usr/bin:/usr/local/bin
 Environment=NODE_ENV=production
 SyslogIdentifier=draupnir
 
-ReadWritePaths=/opt/mod-bot/Draupnir
+ReadWritePaths=/opt/draupnir
+ReadWritePaths=/var/lib/draupnir
 NoNewPrivileges=yes
 PrivateDevices=yes
 PrivateTmp=yes
@@ -155,36 +199,71 @@ SystemCallFilter=@system-service
 WantedBy=multi-user.target
 ```
 
-## Updating the bot
+Reload systemd, enable and start:
+
+```bash
+systemctl daemon-reload
+systemctl enable --now draupnir
+systemctl status draupnir
+```
+
+# Update
 
-if you want to update && upgrade everything, use the draupnir useraccount in order to not create conflicts with filepermissions/ownerships
+When a new release is out:
 
-stop the bot
+### Stop Service
 
-```shell
+```bash
 systemctl stop draupnir
 ```
 
-pull updates from github with
+### Update Source Code
+
+Switch to the `draupnir` user:
+
+```bash
+sudo -u draupnir -i
+```
+
+Then within that shell:
 
-```shell
-sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && git pull && git fetch --tags"
+Pull latest changes:
+
+```bash
+cd /opt/draupnir
+git pull
+```
+
+Fetch all tags:
+
+```bash
+git fetch --tags
 ```
 
-install/update yarn
+Check out the latest tag:
+
+```bash
+latest_tag=$(git tag --sort=version:refname | tail -n1)
+git checkout "$latest_tag"
+```
+
+### Rebuild Application
+
+Run as `draupnir`:
 
-```shell
-sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && yarn install"
+```bash
+yarn install
+yarn build
 ```
 
-build the bot
+Exit the `draupnir` user shell:
 
-```shell
-sudo -u draupnir bash -c "cd /opt/mod-bot/Draupnir && yarn build"
+```bash
+exit
 ```
 
-then simply start the bot again with
+### Restart Service
 
-```shell
-systemctl restart draupnir
+```bash
+systemctl start draupnir
 ```

docs/bot/setup_selfbuild.md

@@ -21,18 +21,53 @@ This guide is meant to be read in conjunction with [Draupnir parameters and opti
 These instructions are to build and run draupnir without using [Docker](./setup_docker.md).
 You need to have installed `yarn` 1.x and Node 20.
 
-```bash
-git clone https://github.com/the-draupnir-project/Draupnir.git
-cd draupnir
-git fetch --tags
+## 1. Clone the Repository & Fetch Tags
+
+1. Clone Draupnir and enter the directory
+   ```bash
+   git clone https://github.com/the-draupnir-project/Draupnir.git draupnir
+   cd draupnir
+   ```
+2. Fetch all tags
+   ```bash
+   git fetch --tags
+   ```
+3. Check out the latest release tag
+   ```bash
+   latest_tag=$(git tag --sort=version:refname | tail -n1)
+   git checkout "$latest_tag"
+   ```
+
+## 2. Install Dependencies & Build
 
+```bash
 yarn install
 yarn build
+```
+
+- `yarn install` installs all required packages
+- `yarn build` compiles the TypeScript source into `lib/`
+
+## 3. Configure Draupnir
+
+1. Copy the default configuration
+   ```bash
+   cp config/default.yaml config/production.yaml
+   ```
+2. Edit `production.yaml`
+   ```bash
+   nano config/production.yaml
+   ```
+3. **Recommended:** change the data path  
+   The default `dataPath: "/data"` is meant for Docker setups. Point it to wherever you prefer, for example:
+   ```yaml
+   dataPath: "/var/lib/draupnir/storage"
+   ```
+
+## 4. Run Draupnir
 
-# Copy and edit the config. It *is* recommended to change the data path,
-# as this is set to `/data` by default for dockerised draupnir.
-cp config/default.yaml config/production.yaml
-nano config/production.yaml
+Start Draupnir with your production configuration:
 
+```shell
 node lib/index.js --draupnir-config ./config/production.yaml
 ```