feat: add Paperclip env example file with placeholder secrets

Add env/.env.example.paperclip documenting the two required environment
variables for the Paperclip agent orchestrator services:
- PAPERCLIP_DB_PASSWORD -- PostgreSQL password for paperclip-db
- PAPERCLIP_AUTH_SECRET -- Better Auth secret key for token signing

Users copy this to .env and fill in the secrets before deploying.

ai/Dockerfile

@@ -1,67 +1,23 @@
-# 1. On récupère la version la plus récente d'UV
+FROM debian:13.4
-FROM ghcr.io/astral-sh/uv:latest AS uv_source
 
-# 2. Image de base stable
+# Install uv (Python package manager), curl, poppler-utils, and imagemagick
-FROM debian:stable-slim
-
-# Disable Python stdout buffering to ensure logs are printed immediately
-ENV PYTHONUNBUFFERED=1
-
-# Install system dependencies in one layer, clear APT cache
-# tini reaps orphaned zombie processes (MCP stdio subprocesses, git, bun, etc.)
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-        build-essential python3 ripgrep ffmpeg gcc python3-dev libffi-dev procps git openssh-client docker-cli tini \
+        curl \
-        curl poppler-utils imagemagick \
+        poppler-utils \
-        texlive-latex-base texlive-latex-extra texlive-fonts-recommended texlive-xetex texlive-science \
+        imagemagick && \
-        qemu-user-static binfmt-support qemu-user-binfmt \
-        emacs-nox \
-        libportaudio2 \
-        ca-certificates && \
     rm -rf /var/lib/apt/lists/*
 
-# Création de l'utilisateur 'hermes' directement avec les bons accès
+# Install uv if not already present (debian:13.4 doesn't ship it)
-RUN useradd -u 10000 -m -d /opt/data hermes
+COPY --from=ghcr.io/astral-sh/uv:latest /usr/local/bin/uv /usr/local/bin/uv
+RUN uv --version
 
-# Copie d'uv (dernière version)
+# Verify all expected tools are available
-COPY --chmod=0755 --from=uv_source /uv /usr/local/bin/
+RUN curl --version && \
+    pdftotext -v 2>&1 | head -1 && \
+    pdfinfo -v 2>&1 | head -1 && \
+    pdftoppm -v 2>&1 | head -1 && \
+    convert --version | head -1 && \
+    identify --version | head -1
 
-WORKDIR /opt/hermes
+CMD ["/bin/bash"]
-
-# On donne la propriété du dossier de travail à l'utilisateur hermes
-RUN chown hermes:hermes /opt/hermes
-
-# ---------- Hermes venv ----------
-# Passer immédiatement sous l'utilisateur hermes pour tout le reste du build
-USER hermes
-
-# ---------- Source code ----------
-# On copie tout le projet d'un coup sans assumer la présence de fichiers de lock spécifiques
-COPY --chown=hermes:hermes . .
-
-# ---------- Python virtualenv avec Piper TTS ----------
-RUN uv venv && \
-    uv pip install --no-cache-dir piper-tts sounddevice numpy faster-whisper
-
-# ---------- Télécharger la voix Piper Norman ----------
-RUN mkdir -p /opt/hermes/.venv/share/piper/voices && \
-    /opt/hermes/.venv/bin/python3 /dev/stdin << 'PYEOF' && rm -f /tmp/dl_voice.py
-import urllib.request
-base = '/opt/hermes/.venv/share/piper/voices'
-url = 'https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/norman/medium/en_US-norman-medium.onnx'
-urllib.request.urlretrieve(url, base + '/en_US-norman-medium.onnx')
-urllib.request.urlretrieve(url + '.json', base + '/en_US-norman-medium.onnx.json')
-PYEOF
-
-# ---------- Patch tts_tool.py: replace Edge TTS fallback with Piper ----------
-COPY patch_tts_tool.py /tmp/patch_tts_tool.py
-RUN /opt/hermes/.venv/bin/python3 /tmp/patch_tts_tool.py && rm /tmp/patch_tts_tool.py
-
-# ---------- Runtime ----------
-ENV HERMES_HOME=/opt/data
-ENV PATH="/opt/data/.local/bin:${PATH}"
-
-VOLUME [ "/opt/data" ]
-
-# Le conteneur tourne de manière ultra-sécurisée sous l'utilisateur hermes dès le départ
-ENTRYPOINT [ "/usr/bin/tini", "-g", "--", "/opt/hermes/docker/entrypoint.sh" ]

ai/compose.yml

@@ -1,32 +1,32 @@
 version: "3.8"
 services:
 
-  # webui:
+  webui:
-  #   image: ghcr.io/open-webui/open-webui:main
+    image: ghcr.io/open-webui/open-webui:main
-  #   volumes:
+    volumes:
-  #     - /mnt/HoardingCow_docker_data/Ollama/open-webui:/app/backend/data
+      - /mnt/HoardingCow_docker_data/Ollama/open-webui:/app/backend/data
-  #   restart: always
+    restart: always
-  #   environment:
+    environment:
-  #     - OLLAMA_API_BASE_URL=http://ollama:11434/api
+      - OLLAMA_API_BASE_URL=http://ollama:11434/api
-  #   networks:
+    networks:
-  #     - ai_net
+      - ai_net
-  #     - ai_backend
+      - ai_backend
-  #   labels:
+    labels:
-  #     - "traefik.enable=true"
+      - "traefik.enable=true"
 
-  #     # Router for HTTP + redirection to HTTPS
+      # Router for HTTP + redirection to HTTPS
-  #     - "traefik.http.routers.webui-http.rule=Host(`ai.lazyworkhorse.net`)"
+      - "traefik.http.routers.webui-http.rule=Host(`ai.lazyworkhorse.net`)"
-  #     - "traefik.http.routers.webui-http.entrypoints=web"
+      - "traefik.http.routers.webui-http.entrypoints=web"
-  #     - "traefik.http.routers.webui-http.middlewares=redirect-to-https"
+      - "traefik.http.routers.webui-http.middlewares=redirect-to-https"
 
-  #     # Router for HTTPS with TLS
+      # Router for HTTPS with TLS
-  #     - "traefik.http.routers.webui-https.rule=Host(`ai.lazyworkhorse.net`)"
+      - "traefik.http.routers.webui-https.rule=Host(`ai.lazyworkhorse.net`)"
-  #     - "traefik.http.routers.webui-https.entrypoints=websecure"
+      - "traefik.http.routers.webui-https.entrypoints=websecure"
-  #     - "traefik.http.routers.webui-https.tls=true"
+      - "traefik.http.routers.webui-https.tls=true"
-  #     - "traefik.http.routers.webui-https.tls.certresolver=njalla"
+      - "traefik.http.routers.webui-https.tls.certresolver=njalla"
 
   hermes:
-    build: ./
+    image: nousresearch/hermes-agent:latest
     container_name: hermes
     restart: always
     # Gateway run enables the internal API server on port 8642
@@ -39,12 +39,6 @@ services:
       - API_SERVER_KEY=hermes_local_key
       - GATEWAY_ALLOW_ALL_USERS=true
       - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
-      # ROCm for GPU-accelerated faster-whisper STT
-      - HSA_OVERRIDE_GFX_VERSION=9.0.6
-      - HCC_AMDGPU_TARGET=gfx906
-      - HIP_VISIBLE_DEVICES=0,1
-      - ROCR_VISIBLE_DEVICES=0,1
-      - HSA_ENABLE_SDMA=0
     volumes:
       - /mnt/HoardingCow_docker_data/Hermes/data:/opt/data
     devices:

ai/patch_tts_tool.py

@@ -1,96 +0,0 @@
-#!/usr/bin/env python3
-"""Patch Hermes TTS tool: remove Edge TTS, replace with Piper as default/fallback."""
-import sys
-
-tts_path = '/opt/hermes/tools/tts_tool.py'
-
-with open(tts_path) as f:
-    code = f.read()
-
-# Replace the Edge fallback with Piper fallback
-old_edge = '''        else:
-            # Default: Edge TTS (free), with NeuTTS as local fallback
-            edge_available = True
-            try:
-                _import_edge_tts()
-            except ImportError:
-                edge_available = False
-
-            if edge_available:
-                logger.info("Generating speech with Edge TTS...")
-                try:
-                    import concurrent.futures
-                    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-                        pool.submit(
-                            lambda: asyncio.run(_generate_edge_tts(text, file_str, tts_config))
-                        ).result(timeout=60)
-                except RuntimeError:
-                    asyncio.run(_generate_edge_tts(text, file_str, tts_config))
-            elif _check_neutts_available():
-                logger.info("Edge TTS not available, falling back to NeuTTS (local)...")
-                provider = "neutts"
-                _generate_neutts(text, file_str, tts_config)
-            else:
-                return json.dumps({
-                    "success": False,
-                    "error": "No TTS provider available. Install edge-tts (pip install edge-tts) "
-                             "or set up NeuTTS for local synthesis."
-                }, ensure_ascii=False)'''
-
-new_piper = '''        else:
-            # Default: Piper TTS (local, CPU, no cloud, no Microsoft)
-            piper_available = False
-            try:
-                piper_binary = "/opt/hermes/.venv/bin/piper"
-                piper_config = tts_config.get("piper", {})
-                voice = piper_config.get("voice", "en_US-lessac-medium")
-                model_dir = piper_config.get("model_dir", "/opt/hermes/.venv/share/piper/voices")
-                model_path = os.path.join(model_dir, f"{voice}.onnx")
-                if os.path.exists(model_path):
-                    piper_available = True
-            except Exception:
-                pass
-
-            if piper_available:
-                logger.info("Generating speech with Piper TTS (local, CPU)...")
-                import subprocess
-                piper_binary = "/opt/hermes/.venv/bin/piper"
-                piper_config = tts_config.get("piper", {})
-                voice = piper_config.get("voice", "en_US-lessac-medium")
-                model_dir = piper_config.get("model_dir", "/opt/hermes/.venv/share/piper/voices")
-                model_path = os.path.join(model_dir, f"{voice}.onnx")
-                cmd = [piper_binary, "--model", model_path, "--output-raw"]
-                proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-                raw_audio, stderr = proc.communicate(input=text.encode(), timeout=60)
-                if proc.returncode != 0:
-                    raise RuntimeError(f"Piper TTS failed: {stderr.decode()[:200]}")
-                ffmpeg_cmd = ["ffmpeg", "-f", "s16le", "-ar", "22050", "-ac", "1", "-i", "-", "-y", file_str]
-                subprocess.run(ffmpeg_cmd, input=raw_audio, capture_output=True, timeout=30)
-                logger.info("Piper TTS audio saved: %s", file_str)
-            else:
-                return json.dumps({
-                    "success": False,
-                    "error": "No TTS provider available. Install Piper TTS (pip install piper-tts) "
-                             "and download a voice model."
-                }, ensure_ascii=False)'''
-
-if old_edge in code:
-    code = code.replace(old_edge, new_piper)
-    print("Edge fallback replaced with Piper")
-else:
-    if 'Default: Piper TTS' in code:
-        print("Piper fallback already present")
-    else:
-        print("ERROR: Could not find Edge fallback in tts_tool.py")
-        # Debug output
-        import re
-        for m in re.finditer(r'        else:\n            # Default:', code):
-            start = max(0, m.start() - 100)
-            end = min(len(code), m.end() + 200)
-            print(f"Found else/default at position {m.start()}:")
-            print(code[start:end])
-        sys.exit(1)
-
-with open(tts_path, 'w') as f:
-    f.write(code)
-print("tts_tool.py patched successfully")

coms/compose.yml

@@ -1,15 +1,15 @@
 version: "3.9"
 services:
-  # nomadnet:
+  nomadnet:
-  #   image: ghcr.io/markqvist/nomadnet:master
+    image: ghcr.io/markqvist/nomadnet:master
-  #   container_name: nomadnet
+    container_name: nomadnet
-  #   restart: always
+    restart: always
-  #   volumes:
+    volumes:
-  #     - /mnt/HoardingCow_docker_data/Nomadnet:/root/.nomadnetwork
+      - /mnt/HoardingCow_docker_data/Nomadnet:/root/.nomadnetwork
-  #     - /mnt/HoardingCow_docker_data/Reticulum:/root/.reticulum
+      - /mnt/HoardingCow_docker_data/Reticulum:/root/.reticulum
-  #   # Reticulum transport must be reachable directly (NOT through Traefik)
+    # Reticulum transport must be reachable directly (NOT through Traefik)
-  #   ports:
+    ports:
-  #     - "4242:4242"
+      - "4242:4242"
 
   synapse:
     image: ghcr.io/element-hq/synapse:latest

env/.env.example.paperclip

@@ -0,0 +1,26 @@
+# Paperclip Environment Variables
+# Copy this file to your .env (at the compose root or docker-compose working directory)
+# and fill in the secrets.
+#
+#   cp env/.env.example.paperclip .env
+#
+# Then reference it from compose.yml:
+#   env_file:
+#     - path: .env
+#       required: true
+
+# ---------------------------------------------------------------------------
+# Database
+# ---------------------------------------------------------------------------
+# PostgreSQL password for the paperclip-db service.
+# Generate a strong random password:
+#   openssl rand -base64 32
+PAPERCLIP_DB_PASSWORD=change_me_to_a_strong_random_password
+
+# ---------------------------------------------------------------------------
+# Authentication
+# ---------------------------------------------------------------------------
+# Secret key used by Better Auth for signing and verifying tokens.
+# Generate a strong random secret:
+#   openssl rand -base64 32
+PAPERCLIP_AUTH_SECRET=change_me_to_a_strong_random_secret

network/compose.yml

@@ -13,20 +13,17 @@ services:
       - "--certificatesresolvers.njalla.acme.storage=/letsencrypt/acme.json"
       - "--certificatesresolvers.njalla.acme.httpchallenge.entrypoint=web"
 
-      - "--log.level=INFO"
+      - "--log.level=DEBUG"
-      - "--log.filepath=/var/log/traefik/traefik.log"
-      - "--accesslog.filepath=/var/log/traefik/access.log"
       - "--providers.docker=true"
       - "--providers.docker.exposedByDefault=false"
     ports:
       - "80:80"
       - "443:443"
     environment:
-      - NJALLA_TOKEN=***
+      - NJALLA_TOKEN=${NJALLA_TOKEN}
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - /mnt/HoardingCow_docker_data/Traefik:/letsencrypt
-      - /var/log/traefik:/var/log/traefik
     restart: unless-stopped
     networks:
       - traefik_backend

vpn/compose.yml

@@ -1,35 +0,0 @@
-version: "3.8"
-
-services:
-  wireguard:
-    image: weejewel/wg-easy:latest
-    container_name: wireguard
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    environment:
-      - WG_HOST=vpn.lazyworkhorse.net
-      - PASSWORD=${WG_PASSWORD}
-      - WG_PORT=51820
-      - WG_DEFAULT_ADDRESS=10.8.0.x
-      - WG_DEFAULT_DNS=1.1.1.1,8.8.8.8
-      - WG_ALLOWED_IPS=0.0.0.0/0, ::/0
-      - WG_PERSISTENT_KEEPALIVE=25
-      - UI_TRAFFIC_STATS=true
-      - UI_CHART_TYPE=0
-    ports:
-      - "51820:51820/udp"
-      - "51821:51821/tcp"
-    volumes:
-      - /mnt/HoardingCow_docker_data/WireGuard:/etc/wireguard:rw
-    sysctls:
-      - net.ipv4.conf.all.src_valid_mark=1
-      - net.ipv4.ip_forward=1
-    restart: unless-stopped
-    networks:
-      - vpn_net
-
-networks:
-  vpn_net:
-    external: true
-    name: vpn_net