Update Servers/Documentation/Zensical.md
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
After many years of Material for MKDocs being updated with new features and security updates, it finally reached EOL around the end of 2025. The project maintainers started pivoting to a new successor called [Zensical](https://zensical.org/docs/get-started/). This document outlines my particular process for setting up a standalone documentation server within a virtual machine.
|
||||
|
||||
!!! info "Assumptions"
|
||||
It is assumed that you are deploying this server into `Ubuntu Server 24.04.2 LTS (Minimal)`. It is also assumed that you are running
|
||||
It is assumed that you are deploying this server into `Ubuntu Server 24.04.2 LTS (Minimal)`. It is also assumed that you are running every command as a user with superuser privileges (e.g. `root`).
|
||||
|
||||
### Setup Python Environment
|
||||
The first thing we need to do is install the necessary python packages and install the zensical software stack inside of it.
|
||||
@@ -12,6 +12,7 @@ sudo apt update && sudo apt upgrade -y
|
||||
sudo apt install -y nano python3 python3.12-venv
|
||||
mkdir -p /srv/zensical
|
||||
cd /srv/zensical
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install zensical
|
||||
zensical new .
|
||||
@@ -84,11 +85,126 @@ sudo systemctl reload nginx
|
||||
sudo systemctl enable nginx
|
||||
```
|
||||
|
||||
### Configure Zensical to Hotload Changes `Under Development`
|
||||
Since NGINX has taken over hosting the webpages, this does not need to be accessible from other servers, only NGINX itself which runs on the same host as Zensical. We only want to use the `zensical serve` command to keep a watchdog on the documentation folder and automatically rebuild the static site content when changes are detected. These changes are then served by NGINX's webserver. *We don't care about the IP:port exposed by this built-in Zensical server.
|
||||
### Create Zensical Watchdog Service
|
||||
Since NGINX has taken over hosting the webpages, this does not need to be accessible from other servers, only NGINX itself which runs on the same host as Zensical. We only want to use the `zensical serve` command to keep a watchdog on the documentation folder and automatically rebuild the static site content when changes are detected. These changes are then served by NGINX's webserver.
|
||||
|
||||
```sh
|
||||
cd /srv/zensical
|
||||
source .venv/bin/activate
|
||||
zensical serve
|
||||
```
|
||||
# Create Service User, Assign Access, and Lockdown Zensical Data
|
||||
sudo useradd --system --home /srv/zensical --shell /usr/sbin/nologin zensical || true
|
||||
sudo chown -R zensical:zensical /srv/zensical
|
||||
sudo find /srv/zensical -type d -exec chmod 2775 {} \;
|
||||
sudo find /srv/zensical -type f -exec chmod 664 {} \;
|
||||
|
||||
# Make Zensical Binary Executable for Service
|
||||
sudo chmod +x /srv/zensical/.venv/bin/zensical
|
||||
|
||||
# Add Additional User(s) to Folder for Extra Access (Such as Doc Runners)
|
||||
sudo usermod -aG zensical nicole
|
||||
|
||||
# Create Service
|
||||
sudo tee /etc/systemd/system/zensical-watchdog.service > /dev/null <<'EOF'
|
||||
[Unit]
|
||||
Description=Zensical Document Changes Watchdog (zensical serve)
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=zensical
|
||||
Group=zensical
|
||||
WorkingDirectory=/srv/zensical
|
||||
|
||||
# Run the venv binary directly; no activation needed
|
||||
ExecStart=/srv/zensical/.venv/bin/zensical serve
|
||||
|
||||
Restart=always
|
||||
RestartSec=2
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Start & Enable Automatic Startup of Service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now zensical-watchdog.service
|
||||
```
|
||||
|
||||
### Create Gitea 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
|
||||
# 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
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Obtain & Configure Gitea Runner 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 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 Gitea Runner 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
|
||||
|
||||
Reference in New Issue
Block a user