Restructured Documentation

2026-09-05 14:08:43 -06:00
parent c4bd235eba
commit 289769a601
281 changed files with 5403 additions and 3563 deletions
@@ -0,0 +1,147 @@
+---
+tags:
+  - Gitea
+  - Zensical
+  - GitOps
+---
+
+## Purpose
+Install and register the host-based Gitea Actions runner that synchronizes this documentation repository into `/srv/zensical/docs`.  The Zensical account, watchdog service, and destination directory must already exist from the Zensical deployment.
+
+## Install the Host Runner
+Now is time for the arguably most-important stage of deployment, which is setting up a [Gitea Act Runner](https://docs.gitea.com/usage/actions/act-runner).  This is how document changes in a Gitea repository will propagate automatically into Zensical's `/srv/zensical/docs` folder.
+
+```sh
+# Install Dependencies
+sudo apt install -y nodejs npm git rsync curl
+
+# Create dedicated Gitea runner service account
+sudo useradd --system --create-home --home /var/lib/gitea_runner --shell /usr/sbin/nologin gitearunner || true
+
+# Allow the runner to write documentation changes
+sudo usermod -aG zensical gitearunner
+
+# Allow the runner to start and stop Zensical Watchdog Service
+sudo tee /etc/sudoers.d/gitearunner-systemctl > /dev/null <<'EOF'
+gitearunner ALL=NOPASSWD: /usr/bin/systemctl start zensical-watchdog.service, /usr/bin/systemctl stop zensical-watchdog.service
+EOF
+sudo chmod 440 /etc/sudoers.d/gitearunner-systemctl
+sudo chown root:root /etc/sudoers.d/gitearunner-systemctl
+sudo visudo -c
+
+# Download Newest Gitea Runner Binary (https://gitea.com/gitea/act_runner/releases)
+cd /tmp
+wget https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-linux-amd64
+sudo install -m 0755 act_runner-0.2.13-linux-amd64 /usr/local/bin/gitea_runner
+gitea_runner --version
+
+# Generate Gitea Runner Configuration
+sudo mkdir -p /etc/gitea_runner
+sudo chown gitearunner:gitearunner /etc/gitea_runner
+sudo -u gitearunner gitea_runner generate-config > /etc/gitea_runner/config.yaml
+```
+
+### Configure Registration Token
+- Navigate to: "**<Gitea Repo> > Settings > Actions > Runners**"
+    - If you don't see this, it needs to be enabled.  Navigate to: "**<Gitea Repo> > Settings > "Enable Repository Actions: Enabled" > Update Settings**"
+- Click the "**Create New Runner**" button on the top-right of the page and copy the registration token somewhere temporarily.
+- Navigate back to the GuestVM running Zensical and run the following commands.
+
+```sh
+# Start Token Registration Process
+sudo -u gitearunner env HOME=/var/lib/gitea_runner /usr/local/bin/gitea_runner register --config /etc/gitea_runner/config.yaml
+
+# Gitea Instance URL: https://git.bunny-lab.io
+# Gitea Runner Token: <Gitea-Runner-Token>
+# Runner Name: zensical-docs-runner
+
+# Move Runner Config to Correct Location & Configure Permissions
+sudo mv /tmp/.runner /var/lib/gitea_runner/.runner
+sudo chown gitearunner:gitearunner /var/lib/gitea_runner/.runner
+sudo chmod 600 /var/lib/gitea_runner/.runner
+```
+
+### Create Service
+Now we need to configure the Gitea runner to start automatically via a service just like the Zensical Watchdog service.
+
+```sh
+# Create Gitea Runner Service
+sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <<'EOF'
+[Unit]
+Description=Gitea Actions Runner (gitea_runner)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Environment=HOME=/var/lib/gitea_runner
+User=gitearunner
+Group=gitearunner
+WorkingDirectory=/var/lib/gitea_runner
+ExecStart=/usr/local/bin/gitea_runner daemon --config /etc/gitea_runner/config.yaml
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Remove Container-Based Configurations to Force Runner to Run in Host Mode
+sudo sed -i \
+  '/^[[:space:]]*labels:/,/^[[:space:]]*cache:/{
+    /^[[:space:]]*labels:/c\  labels:\n    - "zensical-host:host"
+    /^[[:space:]]*cache:/!d
+  }' \
+  /etc/gitea_runner/config.yaml
+
+# Enable and Start the Service
+sudo systemctl daemon-reload
+sudo systemctl enable --now gitea-runner.service
+```
+
+### Repository Workflow
+Place the following file into your documentation repository at the given location and this will enable the runner to execute when changes happen to the repository data.
+
+```yaml title="gitea/workflows/automatic-deployment.yml"
+name: Automatic Documentation Deployment
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  zensical_deploy:
+    name: Sync Docs to https://kb.bunny-lab.io
+    runs-on: zensical-host
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+
+      - name: Stop Zensical Service
+        run: sudo /usr/bin/systemctl stop zensical-watchdog.service
+
+      - name: Sync repository into /srv/zensical/docs
+        run: |
+          rsync -rlD --delete \
+            --exclude='.git/' \
+            --exclude='.gitea/' \
+            --exclude='assets/' \
+            --exclude='schema/' \
+            --exclude='stylesheets/' \
+            --exclude='schema.json' \
+            --chmod=D2775,F664 \
+            . /srv/zensical/docs/
+
+      - name: Start Zensical Service
+        run: sudo /usr/bin/systemctl start zensical-watchdog.service
+
+      - name: Notify via NTFY
+        if: always()
+        run: |
+          curl -d "https://kb.bunny-lab.io - Zensical job status: ${{ job.status }}" https://ntfy.bunny-lab.io/gitea-runners
+
+```
+
+## Related Documentation
+- [Zensical Deployment](<../../../deployments/automation/Documentation/Zensical.md>) — Prepare the service account, watchdog, and destination directory first.
+- [Related Gitea Workflows](<../../../reference/Automation/Gitea Configuration Delivery.md>) — Find the connected deployments, procedures, and references for this subject.