docs/workflows/Automation/Gitea/Publish Zensical Documentation with a Host Runner.md

tags

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. This is how document changes in a Gitea repository will propagate automatically into Zensical's /srv/zensical/docs folder.

# 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: " > Settings > Actions > Runners"
  • If you don't see this, it needs to be enabled. Navigate to: " > 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.

# 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.

# 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.

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 — Prepare the service account, watchdog, and destination directory first.
• Related Gitea Workflows — Find the connected deployments, procedures, and references for this subject.