truenas-stacks/localsend-nomad/README.md

LocalSend trusted-lane receiver on N.O.M.A.D.

Repo-tracked Docker stack that runs a headless LocalSend receiver on N.O.M.A.D. with its own Trusted-LAN IP.

• Repo stack path: /home/fizzlepoof/repos/truenas-stacks/localsend-nomad
• Live stack path: /opt/localsend-nomad
• Trusted bind IP: 10.5.1.16
• Trusted VLAN: 51
• LocalSend ports: 53317/tcp, 53317/udp
• Inbox path on host: /home/fizzlepoof/private/inbox-secrets
• Advertised device name: Doris Trusted Inbox

Why this exists

N.O.M.A.D. lives on the Servers VLAN (10.5.30.7), but some operator handoff flows need a LocalSend receiver directly reachable from the Trusted LAN (10.5.1.0/24). This stack gives LocalSend its own Trusted-LAN address without moving the host itself off the Servers network.

Network model

• Docker uses a macvlan network with parent enp5s0.51.
• enp5s0.51 is the Trusted VLAN subinterface on N.O.M.A.D.'s primary NIC.
• Docker will create the VLAN subinterface automatically when the macvlan network is created.
• Same-host testing from N.O.M.A.D. to 10.5.1.16 is unreliable because macvlan isolates the host from the container's address on the same parent interface.
• Verify reachability from another Trusted-LAN peer instead, such as PD on 10.5.1.6.

LocalSend build provenance

The image is built locally from upstream 0w0mewo/localsend-cli at:

• commit: 54702513990eeb763e1615f274d5365442e3e393

Then it applies patches/localsend-cli-doris.patch, which keeps the receiver compatible with the LocalSend endpoint behavior already working in the existing Doris receiver flow.

Files

• docker-compose.yaml — live stack definition
• Dockerfile — reproducible CLI build from upstream + patch
• .env.example — deployment variables
• bin/prepare_nomad.sh — creates runtime dirs, validates config, optional --up
• patches/localsend-cli-doris.patch — repo-tracked patch applied during image build

Deploy / refresh on NOMAD

cd /opt/localsend-nomad
cp .env.example .env
./bin/prepare_nomad.sh --up

Verification

From N.O.M.A.D.:

docker compose --env-file .env ps
sudo docker logs --tail 50 localsend-trusted
systemctl --user status minerva-localsend-autosort.path --no-pager
systemctl --user status minerva-localsend-autosort.service --no-pager

From another Trusted-LAN host:

ping 10.5.1.16
nc -vz 10.5.1.16 53317

Then confirm Doris Trusted Inbox appears as a LocalSend target from a Trusted-LAN device.

Shared inbox / Minerva handoff

• The receiver writes into /home/fizzlepoof/private/inbox-secrets.
• Minerva's staging flow watches that shared inbox via minerva-localsend-autosort.path and runs /home/fizzlepoof/.local/bin/minerva-localsend-autosort.py.
• Sender-specific routing lives in /home/fizzlepoof/private/minerva-dropbox/sender-map.json.
• Metadata/manifests for staged items land under /home/fizzlepoof/private/minerva-dropbox/manifests/.
• If you need to confirm sender attribution, check both journalctl --user -u doris-localsend.service and docker logs localsend-trusted; the autosort helper reads both so Trusted-LAN receives keep sender-IP-aware routing.

Notes

• The container writes directly into /home/fizzlepoof/private/inbox-secrets on the host so the existing autosort / intake flow can keep using the same inbox path.
• This stack does not publish host ports; the dedicated Trusted-LAN IP is the service endpoint.
• If the upstream CLI behavior changes later, rebuild from a reviewed newer commit and update the patch or drop it if upstream no longer needs the workaround.