From 2a6f7f88ef3e8a4c87565138bd5f5bd62ed813c3 Mon Sep 17 00:00:00 2001
From: root <root@claude.hynesy.com>
Date: Mon, 1 Jun 2026 04:46:58 +1000
Subject: [PATCH] feat(workers): systemd unit + push-workers.sh

Deploy README extended with workers bootstrap + note on the void2-db
SQL_ASCII cluster requiring client_encoding=UTF8 on Python clients.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 deploy/README.md            | 49 +++++++++++++++++++++++++++++++++++++
 deploy/push-workers.sh      | 27 ++++++++++++++++++++
 deploy/void-workers.service | 19 ++++++++++++++
 3 files changed, 95 insertions(+)
 create mode 100755 deploy/push-workers.sh
 create mode 100644 deploy/void-workers.service

diff --git a/deploy/README.md b/deploy/README.md
index bb4dda1..2c3b8e3 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -51,3 +51,52 @@ ssh root@void2-app 'cd /opt/void-server && npm run migrate'
 - `.env` is excluded from the rsync to avoid clobbering production secrets with dev values.
 - The push script uses `--omit=dev` to skip test deps on the target.
 - `tests/` is excluded — they're for the dev environment only.
+
+## Workers (Python void-workers — Plan 4+)
+
+Runs alongside void-server as a second systemd unit.
+
+One-time setup on CT 311:
+
+```bash
+apt install -y python3.12 python3.12-venv python3-pip \
+               ffmpeg tesseract-ocr tesseract-ocr-eng poppler-utils
+
+useradd -r -m -d /opt/void-workers -s /bin/bash voidworkers
+mkdir -p /opt/void-workers /var/lib/void/whisper-models
+chown voidworkers: /opt/void-workers
+chown -R voidworkers: /var/lib/void/whisper-models
+
+# voidworkers needs to read the shared blob store
+usermod -aG void voidworkers
+chmod -R g+rX /var/lib/void/blobs
+
+install -m 644 deploy/void-workers.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable void-workers
+```
+
+`/opt/void-workers/.env` (mode 600, owned by voidworkers):
+
+```
+DATABASE_URL=postgres://void:<pw>@192.168.1.215:5432/void
+BLOB_ROOT=/var/lib/void/blobs
+WHISPER_MODEL=small.en
+WHISPER_CACHE=/var/lib/void/whisper-models
+```
+
+Deploy after edits:
+
+```bash
+cd /project/src/void-v2
+./deploy/push-workers.sh
+```
+
+## SQL_ASCII cluster note
+
+`void2-db` was initialized as SQL_ASCII (not UTF-8). The data is already
+UTF-8 in practice but Python's psycopg refuses to decode without an
+explicit `client_encoding=UTF8` parameter. Workers set this on every
+connection (`lib/db/pool.py` equivalent in `workers/void_workers/`).
+Node's `pg` lib is more lenient and doesn't need this. If you ever
+re-initdb the cluster, use `--encoding=UTF8 --locale=C.UTF-8`.
diff --git a/deploy/push-workers.sh b/deploy/push-workers.sh
new file mode 100755
index 0000000..d5e84d7
--- /dev/null
+++ b/deploy/push-workers.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Push Python void-workers source to CT 311 and restart the service.
+# Run from /project/src/void-v2.
+
+TARGET=${TARGET:-root@192.168.1.13}
+REMOTE_DIR=${REMOTE_DIR:-/opt/void-workers}
+
+rsync -avz --delete \
+  --exclude .venv \
+  --exclude __pycache__ \
+  --exclude '*.egg-info' \
+  --exclude tests \
+  workers/ "$TARGET:$REMOTE_DIR/"
+
+ssh "$TARGET" "
+  cd $REMOTE_DIR
+  if [ ! -d venv ]; then
+    python3.12 -m venv venv
+  fi
+  . venv/bin/activate
+  pip install --quiet --upgrade pip
+  pip install --quiet -e '.[all]'
+  systemctl restart void-workers
+"
+echo "Workers deployed."
diff --git a/deploy/void-workers.service b/deploy/void-workers.service
new file mode 100644
index 0000000..263df34
--- /dev/null
+++ b/deploy/void-workers.service
@@ -0,0 +1,19 @@
+[Unit]
+Description=Void 2.0 workers
+After=network-online.target void-server.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=voidworkers
+WorkingDirectory=/opt/void-workers
+EnvironmentFile=/opt/void-workers/.env
+ExecStart=/opt/void-workers/venv/bin/python -m void_workers.runner
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+MemoryMax=6G
+
+[Install]
+WantedBy=multi-user.target