Skip to content

Documentation Server (docs)

Overview

The BarnesBears documentation website is a static MkDocs site served by Nginx from an unprivileged Proxmox LXC. Its authoritative Markdown source lives in a private GitHub repository; the container pulls approved changes and rebuilds the site automatically.

Property Value
Hostname docs
IP address 192.168.10.95
Platform Proxmox LXC (unprivileged, per deployment plan)
Operating system Debian 13 (Trixie; verify with cat /etc/os-release)
Web server Nginx on HTTP port 80
Site generator MkDocs 1.x + Material 9.x, installed in a Python virtual environment
Internal hostname docs.barnesbears.xyz (Traefik integration planned; confirm when enabled)
GitHub repository 29w211barnes/barnesbears-docs (private)
GitHub access Read-only SSH deploy key
Publishing systemd service + timer, checks about every 5 minutes

Architecture

Browser editor / ChatGPT / Wadsworth (planned)
                     |
               GitHub private repo
                     |
          read-only SSH deploy key
                     |
            docs LXC (192.168.10.95)
             |                 |
          git fetch       Python venv
             |                 |
          local repo ------ MkDocs build
                               |
                   /var/www/barnesbears-docs
                               |
                          Nginx :80
                               |
                    Traefik (planned)

GitHub is the source of truth; the generated HTML is disposable. The container never needs GitHub write access.

Important paths

Path Purpose
/opt/barnesbears-docs Local checkout of the GitHub repository
/opt/barnesbears-docs/mkdocs.yml Site configuration and navigation
/opt/barnesbears-docs/docs/ Markdown source and static assets
/opt/mkdocs-venv Python virtual environment
/var/www/barnesbears-docs Generated static website
/etc/nginx/sites-available/barnesbears-docs Nginx site configuration
/usr/local/sbin/update-barnesbears-docs Git pull and site build script
/etc/systemd/system/barnesbears-docs-update.service Oneshot updater service
/etc/systemd/system/barnesbears-docs-update.timer Periodic updater timer
/root/.ssh/barnesbears_docs Private read-only deploy key; never commit
/root/.ssh/config SSH host alias github-barnesbears

Nginx

The active site serves the generated directory on port 80, using a server block equivalent to:

server {
    listen 80;
    server_name docs.barnesbears.xyz 192.168.10.95;
    root /var/www/barnesbears-docs;
    index index.html;
    location / { try_files $uri $uri/ =404; }
    access_log /var/log/nginx/docs-access.log;
    error_log /var/log/nginx/docs-error.log;
}

Nginx serves HTTP internally; Traefik will terminate TLS when the router is configured. Internal-only access requires an actual LAN/VPN access policy, not merely private DNS.

Initial installation

As root on the Debian LXC:

apt update
apt install -y git python3 python3-venv python3-pip nginx ca-certificates
mkdir -p /opt/barnesbears-docs /var/www/barnesbears-docs
git clone git@github-barnesbears:29w211barnes/barnesbears-docs.git /opt/barnesbears-docs
python3 -m venv /opt/mkdocs-venv
/opt/mkdocs-venv/bin/pip install -r /opt/barnesbears-docs/requirements.txt
cd /opt/barnesbears-docs
/opt/mkdocs-venv/bin/mkdocs build --clean --site-dir /var/www/barnesbears-docs

The github-barnesbears alias requires a deploy key and SSH configuration; see Updating Documentation.

Operations and checks

systemctl status nginx --no-pager
nginx -t
systemctl list-timers barnesbears-docs-update.timer
systemctl status barnesbears-docs-update.timer --no-pager
journalctl -u barnesbears-docs-update.service -n 50 --no-pager
curl -I http://192.168.10.95/

To run the update immediately:

systemctl start barnesbears-docs-update.service
journalctl -u barnesbears-docs-update.service -n 30 --no-pager

A successful oneshot service can show inactive (dead) after it finishes.

Backup and recovery

  • Back up the LXC using Proxmox backup procedures.
  • The private GitHub repository holds the Markdown source, site configuration, and version history.
  • Preserve or reissue the read-only deploy key separately; never put private keys in Git.
  • Rebuild the LXC using the steps above, restore Nginx and systemd configuration, and clone the repository.
  • Maintain an offline copy of essential recovery instructions in case GitHub, AD, DNS, Traefik, or Proxmox is unavailable.

Known limitations / planned improvements

  • The current updater fast-forwards the checkout before building. If a build fails, previously published HTML usually remains, but the local checkout has advanced. Improve this later with a staged build and atomic publication.
  • GitHub polling occurs on the systemd timer, not instantly.
  • Traefik routing and LAN-only access controls were not confirmed when this page was written.
  • Wadsworth's GitHub write workflow is planned but not yet confirmed.
  • The site is static; Markdown editing happens in GitHub, not on the served pages.