conjurer/docs/deployment/DEPLOYMENT_GUIDE.md

Conjurer Deployment Guide

This document walks through deploying the Conjurer stack (Discord bot, music service, librarian service) on two Raspberry Pi 4s and one Windows host, first with plain Docker Compose, then with a future Kubernetes setup.

1. Current Hardware Layout

• Windows PC: Stores persistent data (JSON memories, configs, music catalogue). Shares folders over the network (SMB) for the Pis.
• Raspberry Pi A (“radio”): Runs the Liquidsoap/liq radio pipeline and the musician service (Flask + file watcher).
• Raspberry Pi B (“bot”): Runs the Discord bot, communication bridge, and librarian Flask service.

You can rebalance as follows:

Service	Recommended Host	Notes
Discord bot + comms	Raspberry Pi B	Needs outbound internet, moderate CPU
Librarian service	Raspberry Pi B	CPU-heavy during Crossref queries; keep close to bot
Musician service	Raspberry Pi A	Has direct disk access to music, same box as Liquidsoap
Data storage	Windows	Expose via SMB; mount inside containers

2. Prepare Shared Storage on Windows

1. Create directories, e.g. C:\Conjurer\config, C:\Conjurer\logs, C:\Conjurer\music, C:\Conjurer\playlists, C:\Conjurer\secrets.
2. Copy your existing JSON settings (settings.json, pamiec.json, pamiec_muzyki.json, system_gpt_settings.json, etc.) into config.
3. Create blank placeholder files if they do not exist yet.
4. Share the root folder (C:\Conjurer) over SMB with read/write access for the Pi user (create credentials if necessary).

3. Configure Environment Files

1. On your workstation, copy the example env files:

   cp docker/env/bot.env.example docker/env/bot.env
   cp docker/env/musician.env.example docker/env/musician.env
   cp docker/env/librarian.env.example docker/env/librarian.env
   

2. Edit each docker/env/*.env to replace HACKME! with real values:
   • DISCORD_TOKEN, OPENAI_API_KEY, CONJURER_API_KEY (use the same value for all services).
   • ANTHROPIC_API_KEY — only if you want the Claude backend (see “AI backend switch” below). Safe to leave unset while running on GPT.
   • For musician/librarian, adjust mounts to the SMB paths you will mount on the Pis, e.g. /mnt/conjurer/music.
   • Set CONJURER_CROSSREF_MAILTO to a real email as required by Crossref.
3. If you rely on .netrc, copy it to C:\Conjurer\secrets\.netrc and set CONJURER_NETRC_FILE accordingly. The bot reads netrc machines discord, openai, anthropic, assemblyai, spotipy, youtube.

AI backend switch (GPT ↔ Claude)

The AI chat features run on one backend at a time, selected by a single switch:

• Startup: CONJURER_AI_CONFIG=gpt (default) or =claude in bot.env. Unset falls back to the "active" key in system_gpt_settings.json, then "gpt".
• Runtime: the $gadaj_teraz <config> Discord command (Vykidailo only) flips the backend live and persists the choice.
• The named configs (which provider, which models) live in system_gpt_settings.json — add more there. Claude needs ANTHROPIC_API_KEY; GPT needs OPENAI_API_KEY. Image generation (imaginuje sobie:) and personal assistants always use OpenAI regardless of the switch (Anthropic has no equivalent), and degrade quietly if OPENAI_API_KEY is absent.

4. Install Docker on Raspberry Pis and Windows

Raspberry Pi

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo reboot

# Install docker compose plugin
sudo apt-get install docker-compose-plugin

Windows

• Install Docker Desktop.
• Enable WSL2 backend and expose the shared Windows folders to the containers (Docker Desktop settings → Resources → File Sharing).

5. Deploy Musician Service (Pi A)

1. SSH into Raspberry Pi A.
2. Mount the Windows SMB share:

   sudo mkdir -p /mnt/conjurer
   sudo apt-get install cifs-utils
   sudo mount -t cifs //WINDOWS_HOST/Conjurer /mnt/conjurer -o user=YOURUSER
   

   Add an entry to /etc/fstab for persistence.
3. Copy the repo to the Pi or git clone it.
4. On Pi A, create override compose file (optional) pointing volumes to /mnt/conjurer.
5. Start only the musician service:

   docker compose up --build -d musician
   

   Alternatively, duplicate docker-compose.yml, strip other services, and run docker compose up -d.

6. Deploy Bot + Librarian (Pi B)

1. Repeat SMB mount on Pi B (same mount path).
2. Copy repo / pull latest changes.
3. Create .env files with tokens (or copy from control machine).
4. Start bot and librarian:

   docker compose up -d bot librarian
   

7. Optional: Run Supporting Liquidsoap Radio

• Keep Liquidsoap on Pi A as-is, using the same music directories. Ensure the musician container has read access to those directories (bind mount).

8. Verifying

1. docker ps on each Pi to confirm containers running.
2. Inspect logs under the mounted logs directory (/mnt/conjurer/logs).
3. Join Discord server; issue commands to confirm functionality.
4. Hit health endpoints manually (e.g. curl http://PIB:5000/conjurer).

Rebalancing Suggestions

• If librarian CPU spikes become an issue, move it to Pi A or another host.
• If you add a dedicated NAS, mount the network share read-only for the musician container and read/write for other services.

9. Future Kubernetes Deployment (Outline)

Hardware Considerations

• Minimum three nodes for HA: use the existing two Pis plus one additional Pi 4 (8 GB preferred). Use Windows PC as storage provider via NFS/SMB CSI driver or as a data gateway.
• Consider Pi clusters with USB SSDs for better I/O.

Cluster Setup Steps

1. Install a lightweight Kubernetes distribution (e.g., k3s) on each Pi:

   curl -sfL https://get.k3s.io | sh -
   # On additional nodes
   curl -sfL https://get.k3s.io | K3S_URL=https://MASTER:6443 K3S_TOKEN=HACKME sh -
   

2. Install MetalLB for load balancer support on LAN.
3. Configure persistent volumes using:
   • nfs-subdir-external-provisioner pointing to Windows share (ensure Windows host supports NFS or run an NFS gateway on another machine).
   • Alternatively, attach individual USB drives to each Pi and use local-path-provisioner for node-local storage.
4. Create Kubernetes Secret objects for tokens (DISCORD_TOKEN, etc.).
5. Define Deployment manifests for each service (bot, musician, librarian) and associated Services.
6. Expose Discord bot ports via NodePort or Ingress.
7. Use StatefulSet if you need stable identity for the musician service (due to local storage).

Optimisation Tips

• Keep CPU-heavy librarian pods optionally on a beefier node; use nodeSelector/affinity to pin workloads.
• Consider splitting the persistent storage: music on Pi A (USB disk), logs and configs on Pi B, backups on Windows.
• For improved reliability, add at least one extra Pi for quorum and to host the communication bridge if the bot node fails.

Summary Checklist

1. Prepare Windows shares & tokens.
2. Configure docker/env/*.env using HACKME! templates as reference.
3. Install Docker on Pis, mount network shares.
4. Launch musician on Pi A, bot + librarian on Pi B.
5. Verify Discord functionality and API endpoints.
6. Plan Kubernetes migration when ready (k3s + MetalLB + storage provisioner).