Docker, behind a proxy

deploy/docker-compose.yml is the self-hosted deployment: our own Caddy publishes one plain-HTTP port, serves the dashboard and the artifacts, and proxies what belongs to the hub. Nothing binds 80 or 443, the reverse proxy already fronting your server terminates TLS and forwards to EDGE_PORT.

What runsCopy Anchor Link

No database service: it connects to one you already run, MariaDB/MySQL or Postgres, over DATABASE_URL.

ImagesCopy Anchor Link

CI builds one image per deployable on every push to main and publishes it to GHCR, so a deploy is a pull and a restart rather than a Go cross-compile and a Next build on the machine holding the fleet's sockets:

make pull && make up

Each service's image is a variable, so pinning a release is naming its tag in .env — the numbers are the VERSION file's, one per deployable — and rolling back is naming the previous one:

HUB_IMAGE=ghcr.io/pokemaplx/magnemite/hub:1.0.4
#WEB_IMAGE=
#CADDY_IMAGE=

Building locally always wins over a published image, and is also the way out on a machine that cannot reach ghcr.io — where make up fails on the pull rather than quietly building what it could not fetch.

ConfigurationCopy Anchor Link

Everything comes from .env at the repo root. Copy .env.example:

EDGE_PORT=8090
MAGNEMITE_PUBLIC_URL=https://magnemite.example.com
DB_PROVIDER=mysql
DATABASE_URL=mysql://<user>:<password>@<host>:3306/<database>

Full list: environment reference.

openssl rand -base64 32   # AUTH_SECRET
openssl rand -base64 32   # HUB_INTERNAL_SECRET

Running itCopy Anchor Link

SERVICE=web narrows pull, build and up to one service — which is how a dashboard deploy leaves the hub, and the device sockets it holds, untouched.

Without make, both flags are required, the compose file lives under deploy/, .env at the repo root, and Compose would otherwise start with every variable blank:

docker compose --env-file .env -f deploy/docker-compose.yml pull
docker compose --env-file .env -f deploy/docker-compose.yml up -d
# or, building this checkout instead of pulling:
docker compose --env-file .env -f deploy/docker-compose.yml up -d --build

What your proxy must do?Copy Anchor Link

One virtual host, four requirements.

nginxCopy Anchor Link

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name magnemite.example.com;

  location / {
    proxy_pass http://127.0.0.1:8090;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_buffering off;          # SSE, and 170 MB bodies
    proxy_request_buffering off;  # log bundles the boxes upload
    client_max_body_size 0;
    proxy_read_timeout 3600s;     # idle SSE and slow downloads
  }
}

CaddyCopy Anchor Link

magnemite.example.com {
  reverse_proxy 127.0.0.1:8090 {
    flush_interval -1
  }
}

Caddy upgrades WebSockets and passes Range through on its own; flush_interval -1 is what stops it buffering the SSE stream.

Sign inCopy Anchor Link

Open your domain and log in with ADMIN_EMAIL / ADMIN_PASSWORD. The admin account is created when the hub boots. Optionally, run make seed to create a starter app target, two version sources, a group and a first enrollment token, printed once. Skip it and create the same things from Settings.

Build the Magisk moduleCopy Anchor Link

SERVER is the hub URL, the same value as MAGNEMITE_PUBLIC_URL:

make module SERVER=https://magnemite.example.com TOKEN=<enrollment token>
# → dist/magnemite-agent-1.0.0.zip

Windows: ./scripts/build-agent.ps1 -Server https://… -Token <token>.

Flash a boxCopy Anchor Link

adb push dist/magnemite-agent-1.0.0.zip /data/local/tmp/
adb shell "su -c 'magisk --install-module /data/local/tmp/magnemite-agent-1.0.0.zip'"
adb reboot

In bulk over the LAN: ./scripts/enroll.sh dist/magnemite-agent-1.0.0.zip -f hosts.txt.

The box enrolls itself on first boot and appears in the fleet table. That is the only time it needs hands-on work, yes! Every later update, the agent's own included, rides the socket it opened. Details in the agent on a box.

UpgradingCopy Anchor Link

git pull
make build
make up
make migrate

Rebuilding hub drops every device socket; agents reconnect with backoff and queued jobs resume. To leave them alone, rebuild the dashboard by itself:

make build up SERVICE=web