Add deploy documentation and deploy script

Author: C4ptainCrunch

.github/workflows/deploy.yml

@@ -16,13 +16,29 @@ jobs:
         env:
           WEBHOOK_SECRET: ${{ secrets.DEPLOY_WEBHOOK_SECRET }}
         run: |
-          REF="refs/tags/${{ github.event.workflow_run.head_branch }}"
+          TAG="${{ github.event.workflow_run.head_branch }}"
+          REF="refs/tags/$TAG"
           PAYLOAD="{\"ref\":\"$REF\"}"
           SIGNATURE="sha256=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | cut -d' ' -f2)"
-          RESPONSE=$(curl -sf --max-time 120 \
+
+          HTTP_CODE=$(curl --max-time 120 \
+            -o /tmp/deploy-output.txt \
+            -w "%{http_code}" \
             -X POST \
             -H "Content-Type: application/json" \
             -H "X-Hub-Signature-256: $SIGNATURE" \
             -d "$PAYLOAD" \
             "https://dochub.be/webhook/dochub-deploy")
-          echo "$RESPONSE"
+
+          echo "=== Deploy output ==="
+          cat /tmp/deploy-output.txt
+
+          if [ "$HTTP_CODE" != "200" ]; then
+            echo "Webhook returned HTTP $HTTP_CODE"
+            exit 1
+          fi
+
+          if ! grep -q "Deployed $TAG" /tmp/deploy-output.txt; then
+            echo "Deploy did not complete successfully"
+            exit 1
+          fi

DEPLOY.md

@@ -0,0 +1,140 @@
+# Auto-deploy
+
+Pushing a tag triggers an automatic deploy. Tests must pass first.
+
+## Flow
+
+```
+Tag push
+  → python-tests.yml runs
+    → deploy.yml triggers (on workflow_run success)
+      → POSTs HMAC-signed payload to https://dochub.be/webhook/dochub-deploy
+        → server validates signature, runs deploy.sh
+          → output returned to GitHub Action logs
+```
+
+## How to deploy
+
+Push a tag matching the `YYYY.M.N` format:
+
+```bash
+git tag 2026.4.0 && git push origin 2026.4.0
+```
+
+Check the **Actions** tab for deploy output, or on the server:
+
+```bash
+journalctl -fu dochub-webhook
+```
+
+## What `deploy.sh` does
+
+1. Validates the tag format
+2. Acquires a file lock (prevents concurrent deploys)
+3. `git fetch --tags --prune origin && git checkout $TAG`
+4. `uv run manage.py migrate --noinput`
+5. `uv run manage.py collectstatic --noinput`
+6. `sudo systemctl restart dochub-gunicorn dochub-celery`
+
+If any step fails, `set -e` stops the script before restarting services, so the old code keeps running.
+
+## GitHub secret
+
+`DEPLOY_WEBHOOK_SECRET` (repo Settings > Secrets and variables > Actions) must match the secret in `/etc/webhook/hooks.json` on the server.
+
+## Server-side components
+
+These files live on the server only (not in git):
+
+| File | Purpose |
+|------|---------|
+| `/srv/dochub/deploy.sh` | Thin wrapper that `exec`s the repo's `deploy.sh` |
+| `/etc/webhook/hooks.json` | Webhook config: HMAC validation, ref check, runs as `dochub` |
+| `/etc/systemd/system/dochub-webhook.service` | Runs `webhook` on `127.0.0.1:9000` |
+| `/etc/caddy/Caddyfile` | Proxies `/webhook/*` to the webhook service |
+| `/etc/sudoers.d/dochub-deploy` | Allows `dochub` to restart services without password |
+
+## Appendix: server-side file contents
+
+### `/srv/dochub/deploy.sh`
+
+```bash
+#!/bin/bash
+# Thin wrapper — real logic lives in /srv/dochub/source/deploy.sh (versioned in git)
+exec /srv/dochub/source/deploy.sh "$@"
+```
+
+### `/etc/webhook/hooks.json`
+
+```json
+[
+  {
+    "id": "dochub-deploy",
+    "execute-command": "/srv/dochub/deploy.sh",
+    "command-working-directory": "/srv/dochub",
+    "include-command-output-in-response": true,
+    "trigger-rule": {
+      "and": [
+        {
+          "match": {
+            "type": "payload-hmac-sha256",
+            "secret": "<DEPLOY_WEBHOOK_SECRET>",
+            "parameter": {
+              "source": "header",
+              "name": "X-Hub-Signature-256"
+            }
+          }
+        },
+        {
+          "match": {
+            "type": "regex",
+            "regex": "^refs/tags/",
+            "parameter": {
+              "source": "payload",
+              "name": "ref"
+            }
+          }
+        }
+      ]
+    },
+    "pass-arguments-to-command": [
+      {
+        "source": "payload",
+        "name": "ref"
+      }
+    ]
+  }
+]
+```
+
+### `/etc/systemd/system/dochub-webhook.service`
+
+```ini
+[Unit]
+Description=DocHub deploy webhook
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/webhook -hooks /etc/webhook/hooks.json -ip 127.0.0.1 -port 9000
+User=dochub
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### `/etc/caddy/Caddyfile` (relevant block)
+
+```
+handle_path /webhook/* {
+    rewrite * /hooks{uri}
+    reverse_proxy localhost:9000
+}
+```
+
+### `/etc/sudoers.d/dochub-deploy`
+
+```
+dochub ALL=(root) NOPASSWD: /bin/systemctl restart dochub-gunicorn dochub-celery
+```

deploy.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -euo pipefail
+
+TAG="${1#refs/tags/}"
+
+# Validate tag name to prevent injection
+if [[ ! "$TAG" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?(-[a-zA-Z0-9.]+)?$ ]]; then
+  echo "Invalid tag format: $TAG" >&2
+  exit 1
+fi
+
+# Prevent concurrent deploys
+exec 200>/tmp/dochub-deploy.lock
+flock -n 200 || { echo "Deploy already running, skipping" >&2; exit 1; }
+
+cd /srv/dochub/source
+git fetch --tags --prune origin
+git checkout "$TAG"
+/srv/dochub/.local/bin/uv run manage.py migrate --noinput
+/srv/dochub/.local/bin/uv run manage.py collectstatic --noinput
+sudo /bin/systemctl restart dochub-gunicorn dochub-celery
+echo "Deployed $TAG"