Restructured Documentation
Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 8s
Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 8s
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
---
|
||||
tags:
|
||||
- Gitea
|
||||
- Docker
|
||||
- GitOps
|
||||
---
|
||||
|
||||
## Purpose
|
||||
Configure the Docker-based Gitea runner and repository workflow described in the May 2025 GitOps experiment. The example synchronizes repository files into a bind-mounted destination and sends an ntfy notification.
|
||||
|
||||
!!! info "Dated Docker Runner Example"
|
||||
This is the configuration from the May 2025 runner experiment. Its Docker execution model and destination mounts differ from the Zensical host-runner workflow.
|
||||
|
||||
## Deploy the Docker Runner
|
||||
When it comes to deploying a runner, (*assuming you want to use a docker-based runner*) it has a few simple things that need to be configured, the `docker-compose.yml` and the `.env` files. These tell the runner to reach out to Gitea server to register the runner with the given repository that you generated a registration token on.
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
version: "3.8"
|
||||
services:
|
||||
app:
|
||||
image: docker.io/gitea/act_runner:latest
|
||||
environment:
|
||||
CONFIG_FILE: /config.yaml
|
||||
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
|
||||
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
|
||||
GITEA_RUNNER_LABELS: "${RUNNER_NAME}" # This can be anything, and is referenced by the workflow task(s) later.
|
||||
volumes:
|
||||
- /srv/containers/gitea-runner-mkdocs/config.yaml:/config.yaml # You have to manually make this file before you start the container
|
||||
- /srv/containers/material-mkdocs/docs/docs:/Gitops_Destination # This is where the repository data will be copied to
|
||||
```
|
||||
|
||||
```sh title=".env"
|
||||
INSTANCE_URL=https://git.bunny-lab.io
|
||||
RUNNER_NAME=gitea-runner-mkdocs
|
||||
REGISTRATION_TOKEN=<Generated Here: https://git.bunny-lab.io/bunny-lab/docs/settings/actions/runners>
|
||||
```
|
||||
|
||||
### Creating the `config.yaml`
|
||||
The oddball thing about the way that I configured the Gitea Act Runner was telling it to run the container in "host mode" which tells it to run the tasks / workflows directly on the container itself instead of spinning up an instanced container (referred to as "*Docker-in-Docker*"). This keeps things simpler, but requires us to add a line to the `config.yaml` located at `/srv/containers/gitea-runner-mkdocs/config.yaml`. You can use your preferred text editor to add the following to the file's contents. This tells the runner to use itself for the tasks instead of an instanced docker container.
|
||||
|
||||
```yaml title="/srv/containers/gitea-runner-mkdocs/config.yaml"
|
||||
container_engine: ""
|
||||
```
|
||||
|
||||
!!! info "Quick Config Command"
|
||||
|
||||
```sh
|
||||
mkdir -p /srv/containers/gitea-runner-mkdocs
|
||||
echo 'container_engine: ""' > "/srv/containers/gitea-runner-mkdocs/config.yaml"
|
||||
```
|
||||
|
||||
### Runner Workflow Task Files
|
||||
When it comes to telling the runner what to do and how to do it, you create what are called runner "**Workflows**". These files reside within `<RepoRoot>/.gitea/workflows` and are `.yaml` format. If you have any familiarity with Ansible, the similarities are staggaring. You can have multiple workflows for one repository, with different flows that fire-off on different runners. An example of the flow used to replace Git-Repo-Updater's functionality can be seen below.
|
||||
|
||||
In the workflow below, it spins up a runner within the Alpine Linux environment that the `docker.io/gitea/act_runner:latest` uses, then installs NodeJS, Git, and Rsync for the core functionality that mirrors Git-Repo-Updater:
|
||||
|
||||
```yaml title=".gitea/workflows/gitops-automatic-deployment.yml"
|
||||
name: GitOps Automatic Deployment
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
GitOps Automatic Deployment:
|
||||
runs-on: gitea-runner-mkdocs
|
||||
|
||||
steps:
|
||||
- name: Install Node.js, git, rsync, and curl
|
||||
run: |
|
||||
apk add --no-cache nodejs npm git rsync curl
|
||||
|
||||
- name: Checkout Repository
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Copy Repository Data to Production Server
|
||||
run: |
|
||||
rsync -a --delete --exclude='.git/' --exclude='.gitea/' . /Gitops_Destination/
|
||||
|
||||
- name: Notify via NTFY
|
||||
run: |
|
||||
curl -d "https://docs.bunny-lab.io - Workflow Completed" https://ntfy.bunny-lab.io/gitea-runners
|
||||
```
|
||||
|
||||
!!! note "`runs-on` Variable"
|
||||
In this example workflow file, we are targeting the previously-mentioned `gitea-runner-mkdocs` runner, which we gave that "label" in the docker-compose.yaml file's `GITEA_RUNNER_LABELS` variable. You can name these labels whatever you want, as a way of organizing which runners run which workflows associated with a repository when changes are made to the repository.
|
||||
|
||||
## Related Documentation
|
||||
- [Related Gitea Workflows](<../../../reference/Automation/Gitea Configuration Delivery.md>) — Find the connected deployments, procedures, and references for this subject.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user