📚 Zap Platform Documentation

Complete documentation for the Zap platform, including development guides, testing procedures, and infrastructure details

Core Documentation
Platform-wide documentation and guides
Topic Documentation
Specific guides and troubleshooting
External Links
INFRASTRUCTURE
Network overview and system architecture • Core Documentation

Infrastructure Reference

Last updated: 2026-02-28 Database connections: See DATABASES.md DNS management: AdGuard Home at http://adguard.lan (#dns_rewrites) Credentials: ~/.credentials (per-host passwords), project-level in each repo's private/credentials

---

Network Overview

Two subnets on the domestic LAN, each served by a dedicated Proxmox host:

SubnetGatewayProxmox HostPurpose
------------
192.168.1.0/24192.168.1.1titan.lan (.1.22)Legacy VMs/CTs, NAS, DNS, network services
192.168.2.0/24192.168.2.1phoebe.lan (.2.16)Primary workloads, LLM, production VMs

DNS for *.lan is managed by AdGuard Home on ca-server (192.168.1.97).

---

IP Allocation Scheme

192.168.2.0/24 (phoebe.lan)

RangeCategoryCurrent Assignments
---------
.1GatewayRouter
.10-.19Physical hosts / bare metaldelphi.lan=.15, phoebe.lan=.16
.20-.29(reserved)iris1.lan=.21
.30-.39Production VMsnaiad01.lan=.31, orcus.lan=.32
.40-.49LLM / AI servicesollama-phoebe.lan=.40, janus01.lan=.41
.50-.59Dev / testcursor-demo.lan=.50, zeno.lan=.51, dev.lan=.52
.60-.69Infrastructure servicestorrent-search.lan=.60
.70-.79(free)
.80-.89Databasesmerlin-db.phoebe.lan=.81, surrealdb01.lan=.80 — see DATABASES.md
.90-.99(free)

192.168.1.0/24 (titan.lan)

RangeCategoryCurrent Assignments
---------
.1GatewayRouter
.9-.14Jason CTs (dev/test containers)energystats=.9, sybil=.10, merlin01=.11, jason04=.12, jason05=.13, jason06=.14
.17End-user machinesparis.lan (Windows 11)
.19VPN containersvpn-fetch.lan
.20-.23Proxmox hosts + misc VMsovid=.20, juno=.21, titan=.22, hyperion=.23
.40-.44LLM / AIollama-titan.lan=.40, delphi01=.43, delphi-dt-12=.44
.50-.54Web / app VMszeus01=.50, zeus01-dev=.51, pindar=.52, neon=.53, argon=.54
.70-.71File serviceshephaestus=.70, nextcloud-test=.71
.80Databasesresolve-pg14.lan
.96-.99Network infrastructurelucerna/pi-hole=.96, adguard/ca-server=.97, pharos=.99
.200-.202NAS / storageds916=.200, ds1571=.201, atrium=.202

Rule

Before assigning a new static IP, always:

  • Check this document
  • Check AdGuard rewrites: http://adguard.lan/#dns_rewrites
  • Scan the subnet: ip neigh show | grep "192.168.X\."

    • ---

    Physical Hosts

    HostnameIPHardwareOSPurpose
    ---------------
    phoebe.lan192.168.2.16AMD desktop, RTX 3060 (12GB)Proxmox VE 8.2Primary hypervisor
    titan.lan192.168.1.22ServerProxmox VE 7.1Secondary hypervisor
    delphi.lan192.168.2.152x RTX 3090 (48GB VRAM)Ubuntu (bare metal)LLM inference, SearXNG
    atrium.lan192.168.1.202Synology DS916+DSMNAS (~35TB), CIFS shares
    ds1571192.168.1.201Synology DS1571DSMNAS (Textz archive)
    paris.lan192.168.1.17DesktopWindows 11End-user workstation

    ---

    Proxmox Inventory: phoebe.lan

    Virtual Machines

    VMIDNameIPStatusRAMCoresPurpose
    ---------------------
    232orcus192.168.2.32running16 GB6Main dev workstation VM (Ubuntu 22.04). Hosts all web apps via Apache.
    252dev.lan192.168.2.52running48 GB4Development/staging server
    400ollama-phoebe192.168.2.40running8 GB4Ollama LLM (RTX 3060 passthrough)
    231naiad01-u24DT192.168.2.31stopped32 GB6Web dev VM (Ubuntu 24.04 desktop)
    233orcus-clone--stopped16 GB6Backup clone of orcus
    100u22-DT-LVM--stopped32 GB8Template/test (Ubuntu 22.04 desktop, LVM)
    101u22-DT-ZFS--stopped8 GB6Template/test (Ubuntu 22.04 desktop, ZFS)
    102zeno-ZFS192.168.2.51stopped24 GB6Dev VM
    103zeno-LVM--stopped32 GB8Dev VM (LVM variant)
    104zeno-test--stopped32 GB8Test VM

    LXC Containers

    CTIDNameIPStatusRAMCoresPurpose
    ---------------------
    300vpn-fetch192.168.1.19 (DHCP)running512 MB2Alpine Linux. PIA WireGuard VPN + transmission-daemon for torrent downloads.
    301cursor-demo192.168.2.50stopped1 GB2Ubuntu 22.04. Cursor demo environment.
    302torrent-search192.168.2.60running2 GB2Ubuntu 22.04. Docker: Jackett + FlareSolverr for 1337x torrent search. PIA VPN.
    303merlin-db (legacy)192.168.2.81stopped2 GB2Ubuntu 22.04 + PostgreSQL 14. Kept for rollback safety.
    304merlin-db192.168.2.81running2 GB2Ubuntu 22.04 + PostgreSQL 16. Production database for Merlin. Migrated from 303 (2026-02-28). Apache: http://merlin-db.phoebe.lan/ — local info page with connection details.

    Storage

    NameTypeTotalUsedAvailable
    ---------------
    localdir6.6 GB10 MB6.5 GB
    local-zfszfspool7.2 GB656 MB6.5 GB
    atrium-imagescifs34.9 TB11.5 TB23.4 TB

    ---

    Proxmox Inventory: titan.lan

    Virtual Machines (active)

    VMIDNameIPStatusRAMCoresPurpose
    ---------------------
    102merlin01192.168.1.11running4 GB--Merlin agent / STT
    120zeus01192.168.1.50running8 GB--Zeus web app (production)
    121zeus01-dev192.168.1.51running8 GB--Zeus web app (dev)
    400ollama-titan192.168.1.40running8 GB--Ollama LLM (RTX 3060 passthrough)
    851j-u23s-01--running8 GB--Julian's Ubuntu 23 server
    896lucerna192.168.1.96running4 GB--Pi-hole / monitoring

    Virtual Machines (stopped -- templates, legacy, test)

    VMIDNameNotes
    ---------
    100ubuntu20-templateTemplate
    101chronos00-clone01Legacy
    104u24.04-LTSTemplate
    110athena01Auth service (stopped)
    210, 211jason210, jason211Test VMs
    220, 221iris0, iris1-u22-DTML/AI VMs (stopped)
    230, 231naiad-00, naiad01Web dev VMs (stopped, migrated to phoebe)
    701nextcloudtestTest
    800surrealdbDatabase VM (stopped)
    841janus01Messaging service (stopped)
    850, 860, 870TemplatesJulian's Ubuntu/MX templates
    861j-u23d-01Julian's Ubuntu 23 desktop (stopped)
    990hephaestusHigh-RAM compute (65 GB, stopped)
    995pve-test-ip72Network test

    LXC Containers

    CTIDNameIPStatusRAMPurpose
    ------------------
    880resolve-pg14192.168.1.80running2 GBPostgreSQL 14
    897ca-server192.168.1.97running512 MBAdGuard Home DNS + certificate authority
    981jason04192.168.1.12running6 GBDev container
    982jason05192.168.1.13running6 GBDev container (on 2.x subnet in DNS: 192.168.2.13)
    986jason02192.168.1.9running6 GBDev container
    988jason03192.168.1.10running6 GBDev container
    989jason06192.168.1.14running6 GBDev container (FastAPI, Matomo, energy charts)
    890pharos01192.168.1.99stopped1 GBNetwork monitoring (stopped)
    980jason-template192.168.1.12stopped6 GBTemplate
    985jason01-defunct192.168.1.9stopped6 GBDefunct
    987jason03-defunct192.168.1.10stopped6 GBDefunct

    ---

    External Servers

    NameIPProviderPurpose
    ------------
    du1161.35.36.240DigitalOceanProduction hosting (philanthropy-planner, concerts.freebyrd.live)
    du2142.93.45.250DigitalOceanDev/staging (dev.philoenic.com, dev.sso.merlin-ai.com)

    SSH access: ssh jd@161.35.36.240, ssh jd@142.93.45.250

    ---

    Key Services & Ports

    On orcus.lan (192.168.2.32)

    ServicePortURLNotes
    ------------
    Apache (web apps)443https://orcus.lanHosts ~15 vhosts (media-manager, zap, philoenic, prospecta, etc.)
    LLM Gateway443https://llm.orcus.lanApache reverse proxy to Ollama servers
    PostgreSQL 175432--zap database, zap-projects
    Centrifugo25001ws://orcus.lan:25001WebSocket server for real-time updates

    LLM Servers

    HostPortGPUModels
    ------------
    delphi.lan114342x RTX 3090 (48 GB)Large models (qwen3:30b, etc.)
    ollama-phoebe.lan11434RTX 3060 (12 GB)qwen3:8b (~63 tok/s)
    ollama-titan.lan11434RTX 3060 (12 GB)llama3.1:8b (~67 tok/s)

    Search & Torrents

    ServiceHostPortPurpose
    ------------
    SearXNGdelphi.lan8888Federated web + torrent search
    Jacketttorrent-search.lan9117Torrent indexer proxy (1337x via FlareSolverr)
    FlareSolverrtorrent-search.lan8191Cloudflare bypass for Jackett
    Transmissionvpn-fetch.lan9091BitTorrent client behind PIA VPN

    DNS & Network

    ServiceHostPortPurpose
    ------------
    AdGuard Homeca-server (192.168.1.97)80DNS server for *.lan, rewrite rules
    Pi-holelucerna (192.168.1.96)80Secondary DNS / monitoring

    ---

    Storage (NAS Mounts on orcus.lan)

    Mount PointRemote SharePurpose
    ---------
    /mnt/atrium-shared//atrium.lan/SHAREDMain shared storage
    /mnt/atrium-data//atrium.lan/DATAData archive
    /mnt/media-downloader//atrium.lan/SHARED/MOVIES-TV-AUDIO/MOVIES (in English)Downloaded films (A-Z subfolders)
    /mnt/merlin-backups//atrium.lan/JULIAN/backups-orcusDatabase backups (7 daily + 4 weekly + 3 monthly)
    /mnt/nas/zap-recordings//atrium.lan/DATA/zap-orcusZap recordings
    /mnt/atrium-celine//atrium.lan/CELINECeline's share
    /mnt/ds1571-textz//192.168.1.201/TextzDS1571 text archive

    Content type paths on NAS:

    TypePathSMB Path
    ---------
    Films (English)/mnt/media-downloader\\atrium\SHARED\MOVIES-TV-AUDIO\MOVIES (in English)
    TV/mnt/atrium-shared/MOVIES-TV-AUDIO/TV\\atrium\SHARED\MOVIES-TV-AUDIO\TV
    Documentaries/mnt/atrium-shared/MOVIES-TV-AUDIO/DOCUMENTARIES\\atrium\SHARED\MOVIES-TV-AUDIO\DOCUMENTARIES
    Animation/mnt/atrium-shared/MOVIES-TV-AUDIO/ANIMATION\\atrium\SHARED\MOVIES-TV-AUDIO\ANIMATION
    Foreign/mnt/atrium-shared/MOVIES-TV-AUDIO/MOVIES (not in English)\\atrium\SHARED\MOVIES-TV-AUDIO\MOVIES (not in English)

    ---

    VPN Configuration

    vpn-fetch.lan (CT 300 on phoebe)

    • OS: Alpine Linux
    • VPN: PIA WireGuard (currently connected to PIA server; region varies)
    • Purpose: Transmission torrent downloads routed through VPN
    • PostUp route: ip route add 192.168.0.0/16 via 192.168.1.1 (LAN access preserved)

      • torrent-search.lan (CT 302 on phoebe)

    • OS: Ubuntu 22.04
    • VPN: PIA WireGuard (UK region preferred, auto-reconnect every 12h via cron)
    • Purpose: Jackett + FlareSolverr Docker containers for 1337x torrent search
    • PostUp route: ip route add 192.168.0.0/16 via 192.168.2.1 (LAN access preserved)
    • Reconnect script: /usr/local/bin/pia-reconnect.sh
    • Cron: 0 /12 /usr/local/bin/pia-reconnect.sh >> /var/log/pia-reconnect.log 2>&1
    • Docker: Jackett (port 9117) + FlareSolverr (port 8191), compose file at /opt/torrent-search/docker-compose.yml
    • Jackett API key: stored in media-manager private/credentials
    ---

    Web Apps on orcus.lan

    All served via Apache with TLS (self-signed certs). Each vhost maps a subdomain to a /var/www// directory.

    SubdomainProjectRepoNotes
    ------------
    zap.orcus.lanZap platformmerlinai-com/zapMain platform: mail, calendar, projects, recordings
    media-manager.orcus.lanMedia Managermerlinai-com/media-managerFilm/TV discovery, torrent search & download
    philoenic.orcus.lanPhiloenicmerlinai-com/philoenic.comWine events (local dev; deployed to dev.philoenic.com)
    prospecta.orcus.lanProspectamerlinai-com/prospectaBusiness prospecting
    philanthropy-planner.orcus.lanPhilanthropy Plannermerlinai-com/philanthropy-plannerCC data explorer (deployed to du1)
    llm.orcus.lanLLM Gateway(part of zap)Reverse proxy to Ollama servers
    merlin-agent.orcus.lanMerlin Agent--Agent interface
    status.orcus.lanStatus page(part of zap)System status dashboard

    ---

    DNS Entries (AdGuard Rewrites)

    Managed at http://adguard.lan/#dns_rewrites. Grouped by IP:

    192.168.1.x

    IPHostnames
    ------
    .9energystats.lan
    .10sybil.lan
    .11merlin01.lan, merlin.lan, merlin-stt.lan
    .12jason04, jason04.lan, whisper-v1.jason04.lan
    .14jason06, jason06.lan, charts.energystats.lan, fastapi.jason06.lan, matomo.jason06.lan, test.multipage.lan, tls.jason06.lan
    .17paris.lan
    .19vpn-fetch.lan
    .20ovid.lan, sibyl, sibyl.ovid.lan
    .21juno.lan, wss.juno.lan
    .22proxmox.lan, titan.lan
    .23hyperion, hyperion.lan
    .40ollama-titan.lan
    .43delphi01, delphi01.lan
    .44delphi-dt-12.lan
    .50zeus01, zeus01.lan, zeus.lan, athena.zeus01.lan, energycharts.zeus01.lan, rd.merlin.lan, sso.zeus01.lan
    .51zeus01-dev, zeus01-dev.lan, pindar.lan, athena.zeus01-dev.lan, energycharts.zeus01-dev.lan, jd.merlin.lan, tls.zeus01-dev.lan
    .52pindar2.lan
    .53neon.lan, test-fastcgi
    .54argon.lan
    .70hephaestus, hephaestus.lan
    .71nextcloud-test.lan
    .80resolve-pg14.lan
    .96lucerna.lan, pi-hole.lan
    .97adguard.lan, ca-server, ca-server.lan
    .99pharos, pharos.lan, pharos01.lan
    .200ds916
    .201ds1571
    .202atrium.lan

    192.168.2.x

    IPHostnames
    ------
    .13jason05
    .15delphi, delphi.lan
    .16phoebe, phoebe.lan
    .21iris1, iris1.lan
    .31naiad01, naiad01.lan, naiad.lan, + sub-vhosts (aifutures, energystats, felix-project, freebird, getzap, pdf-ops, philoenic, philoenos)
    .32orcus.lan, + sub-vhosts (biz-cards, energystats-app, energystats, file-finder, llm, media-downloader, media-manager, merlin-agent, merlin, pdf-extraction, philanthropy-planner, philoenic, prospecta, status, zap-cal, zap-mail, zap)
    .40ollama-phoebe.lan
    .41janus01, janus01.lan, zap-msg.janus01.lan
    .50cursor-demo.lan
    .51zeno, zeno.lan
    .52dev, dev.lan
    .60torrent-search.lan
    .80surrealdb01, surrealdb01.lan
    .81merlin-db, merlin-db.phoebe.lan
    ← Back to Zap Projects 🖥️ Orcus Server Docs →