deploy to VPS via rsync, add versioned book paths

Replace GitHub Pages deployment with rsync-over-SSH to the VPS.
Each book now builds to a versioned path (e.g. start-os/0.4.0.x/)
controlled by versions.conf, with nginx handling version inference
and legacy redirects.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: MattDHill

.github/workflows/deploy.yml

@@ -7,15 +7,13 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: "pages"
+  group: "deploy"
   cancel-in-progress: false
 
 jobs:
-  build:
+  build-and-deploy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -37,10 +35,6 @@ jobs:
           curl -sSL https://github.com/rust-lang/mdBook/releases/download/${MDBOOK_VERSION}/mdbook-${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz
           sudo mv mdbook /usr/local/bin/mdbook
 
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
-
       - name: Install mdbook-tabs
         run: |
           cargo install mdbook-tabs --version 0.3.4
@@ -55,18 +49,75 @@ jobs:
           npm ci
           npm run generate-llms-txt
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./docs
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.DOCS_DEPLOY_KEY }}" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          ssh-keyscan -H start9.com >> ~/.ssh/known_hosts
+          cat >> ~/.ssh/config <<EOF
+          Host docs-vps
+            HostName start9.com
+            User root
+            IdentityFile ~/.ssh/deploy_key
+            IdentitiesOnly yes
+          EOF
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Deploy to VPS
+        run: |
+          source versions.conf
+          DEST="/var/www/html/docs.start9.com"
+
+          # Sync each book's versioned directory
+          rsync -az --delete docs/start-os/$START_OS_VERSION/ docs-vps:$DEST/start-os/$START_OS_VERSION/
+          rsync -az --delete docs/start-tunnel/$START_TUNNEL_VERSION/ docs-vps:$DEST/start-tunnel/$START_TUNNEL_VERSION/
+          rsync -az --delete docs/packaging/$PACKAGING_VERSION/ docs-vps:$DEST/packaging/$PACKAGING_VERSION/
+
+          # Sync per-book llms.txt into versioned directories (unversioned URLs redirect here)
+          rsync -az docs/start-os/llms.txt docs/start-os/llms-full.txt docs-vps:$DEST/start-os/$START_OS_VERSION/
+          rsync -az docs/start-tunnel/llms.txt docs/start-tunnel/llms-full.txt docs-vps:$DEST/start-tunnel/$START_TUNNEL_VERSION/
+          rsync -az docs/packaging/llms.txt docs/packaging/llms-full.txt docs-vps:$DEST/packaging/$PACKAGING_VERSION/
+
+          # Sync landing page and global llms.txt files
+          rsync -az docs/index.html docs-vps:$DEST/index.html
+          rsync -az docs/llms.txt docs/llms-full.txt docs-vps:$DEST/
+
+      - name: Generate and upload nginx book_versions.conf
+        run: |
+          source versions.conf
+
+          cat > book_versions.conf <<'NGINX'
+          # Auto-generated by deploy workflow — do not edit manually
+
+          # Extract book name from URI
+          map $uri $book_name {
+              default "";
+              ~^/(start-os|start-tunnel|packaging|start-wrt)(/|$) $1;
+          }
+
+          # Latest version per book
+          map $book_name $latest_book_version {
+              default "";
+          NGINX
+
+          echo "    \"start-os\" \"$START_OS_VERSION\";" >> book_versions.conf
+          echo "    \"start-tunnel\" \"$START_TUNNEL_VERSION\";" >> book_versions.conf
+          echo "    \"packaging\" \"$PACKAGING_VERSION\";" >> book_versions.conf
+
+          cat >> book_versions.conf <<'NGINX'
+          }
+
+          # Version resolution: maps book + ?version= param to directory name
+          NGINX
+
+          echo 'map "$book_name:$arg_version" $resolved_book_version {' >> book_versions.conf
+          echo '    default "";' >> book_versions.conf
+          echo "    \"~^start-os:0\\.4\\.0(\\.|$)\" \"$START_OS_VERSION\";" >> book_versions.conf
+          echo "    \"~^start-tunnel:1\\.0(\\.|$)\" \"$START_TUNNEL_VERSION\";" >> book_versions.conf
+          echo "    \"~^packaging:0\\.4\\.0(\\.|$)\" \"$PACKAGING_VERSION\";" >> book_versions.conf
+          echo "}" >> book_versions.conf
+
+          rsync -az book_versions.conf docs-vps:/etc/nginx/includes/book_versions.conf
+
+      - name: Reload nginx
+        run: ssh docs-vps 'nginx -t && nginx -s reload'

ARCHITECTURE.md

@@ -59,9 +59,32 @@ The `theme/` directory at repo root is the single source of truth for styling. E
 - Theme toggle
 - Favicon
 
+## Versioning
+
+Each book is versioned independently via `versions.conf` at repo root:
+
+```bash
+START_OS_VERSION="0.4.0.x"
+START_TUNNEL_VERSION="1.0.x"
+PACKAGING_VERSION="0.4.0.x"
+```
+
+Build output goes to `docs/<book>/<version>/` (e.g. `docs/start-os/0.4.0.x/`). The `site-url` is set via environment variable at build time so mdbook generates correct search indexes and canonical URLs for the versioned path.
+
 ## Build Pipeline
 
-`build.sh` runs `mdbook build` in each book directory. Output goes to `docs/<book-name>/`. The landing page is copied to `docs/index.html`. CI then generates `llms.txt` and `llms-full.txt` for LLM consumption.
+`build.sh` sources `versions.conf` and runs `mdbook build` in each book directory with versioned output paths. The landing page is copied to `docs/index.html`. CI then generates `llms.txt` and `llms-full.txt` for LLM consumption.
+
+## Deployment
+
+Deployment is via GitHub Actions (`.github/workflows/deploy.yml`):
+
+1. Build all books and generate llms.txt
+2. rsync each versioned book directory to the VPS at `/var/www/html/docs.start9.com/`
+3. Generate and upload `book_versions.conf` (nginx map config) from `versions.conf`
+4. Reload nginx
+
+The deploy key is stored as the `DOCS_DEPLOY_KEY` GitHub Actions secret.
 
 ## Scripts
 
@@ -71,4 +94,4 @@ The `theme/` directory at repo root is the single source of truth for styling. E
 
 ## Cross-Book Links
 
-mdBook validates links within a single book. Links between books use absolute paths (`/start-tunnel/user-manual/devices.html`) and are not validated at build time. There are only a handful of these.
+mdBook validates links within a single book. Links between books use unversioned absolute paths (`/start-tunnel/user-manual/devices.html`) — nginx redirects these to the latest versioned path. These are not validated at build time. There are only a handful of these.

build.sh

@@ -1,14 +1,21 @@
 #!/bin/bash
 set -e
 
+source versions.conf
+
 # Clean output
 rm -rf docs
 mkdir -p docs
 
-# Build books
-(cd start-os && mdbook build)
-(cd start-tunnel && mdbook build)
-(cd packaging && mdbook build)
+# Build books with versioned paths
+(cd start-os && MDBOOK_OUTPUT__HTML__SITE_URL="/start-os/$START_OS_VERSION/" \
+  mdbook build -d "../docs/start-os/$START_OS_VERSION")
+
+(cd start-tunnel && MDBOOK_OUTPUT__HTML__SITE_URL="/start-tunnel/$START_TUNNEL_VERSION/" \
+  mdbook build -d "../docs/start-tunnel/$START_TUNNEL_VERSION")
+
+(cd packaging && MDBOOK_OUTPUT__HTML__SITE_URL="/packaging/$PACKAGING_VERSION/" \
+  mdbook build -d "../docs/packaging/$PACKAGING_VERSION")
 
 # Landing page
 cp landing/index.html docs/index.html

versions.conf

@@ -0,0 +1,3 @@
+START_OS_VERSION="0.4.0.x"
+START_TUNNEL_VERSION="1.0.x"
+PACKAGING_VERSION="0.4.0.x"