Music Craft uses the Sonoxel backend for its public library. The Paper server carries local files and radio audio over the Minecraft connection; the Sonoxel Cloudflare Worker handles public library requests; and the Sonoxel media service on the Lightsail VPS serves ticketed library audio and artwork. The Paper server can run on a separate host.
| Route | Purpose | Origin |
|---|---|---|
https://sonoxel-edge.sonoxel-edge.workers.dev |
Public control API for Paper and Fabric | Sonoxel Worker |
https://media.demonz.org |
Worker to private control API | Cloudflare Tunnel to http://127.0.0.1:8081 |
https://audio.demonz.org |
Ticketed MP3 and artwork | DNS-only A record to the VPS, Caddy HTTPS |
The Worker calls /v1/catalog, /v1/search, /v1/resolve, /v1/health, and /v1/ticket through the Tunnel. The Tunnel denies media paths. Caddy serves /v1/media/* and /v1/artwork/* on the audio hostname and denies other paths. Set SONOXEL_PUBLIC_BASE=https://audio.demonz.org in the API environment so tickets use the direct HTTPS route.
The Worker holds the origin credential and server key. Keep those values in Worker secrets and /etc/sonoxel/api.env; never add them to the Paper config or repository. The default Paper api-url points to https://sonoxel-edge.sonoxel-edge.workers.dev. The Worker name in edge/wrangler.toml does not determine the account's workers.dev subdomain.
On the Lightsail instance, allow inbound TCP 80 and 443 for HTTPS. Allow TCP 22 for administration, preferably limited to the administrator's IP. Keep ports 8080, 8081, and 2333 private. The Paper host needs its Minecraft port, normally TCP 25565, plus outbound HTTPS for the Worker, Radio Browser, and station streams. Local music and radio need no additional inbound Paper port.
In the demonz.org Cloudflare account, set audio to a DNS-only A record for the VPS and publish media through the Cloudflare Tunnel. The media Tunnel route must point to http://127.0.0.1:8081. The Tunnel connector initiates outbound connections; restricted egress may need TCP or UDP 7844. The Worker can remain in a separate Cloudflare account on workers.dev.
The deployment scripts in infra/lightsail/ install the API, Lavalink plugin, Caddy route, and systemd units under the Sonoxel paths. Build the separate Sonoxel Lavalink repository before running infra/lightsail/publish.ps1. Configure Worker secrets before deploying edge/.
Verify the public Worker and origin routes with these checks:
GET https://sonoxel-edge.sonoxel-edge.workers.dev/v1/health -> 200
GET https://media.demonz.org/v1/health -> 200
GET https://media.demonz.org/v1/media/probe -> 404
GET https://audio.demonz.org/v1/media/probe -> 401
On the VPS, run the private smoke test after deployment:
sudo bash /tmp/sonoxel-release/smoke.sh
sudo bash -c 'set -a; source /etc/sonoxel/api.env; python3 /tmp/sonoxel-release/load-smoke.py'
systemctl is-active sonoxel-api sonoxel-lavalink caddy cloudflaredThe load smoke issues 100 short range requests. It does not establish sustained 100-listener capacity; measure a sustained run separately and compare usage with the Lightsail transfer meter. The private /v1/usage endpoint reports API media reservations for the current UTC month.
Install the Paper 26.3 plugin and set plugins/MusicCraft/config.yml:
server-id: primary
api-url: https://sonoxel-edge.sonoxel-edge.workers.devChoose a stable, unique server-id for each Paper server, then restart it. Install the matching Fabric 26.3 mod and Fabric API on each client. No control service credentials are required in Paper's config.