Operating moxzidalpha

How do I run this as a service: health, metrics, logs, shutdown, TLS?

Running moxzid as a service is a supervised process with a state directory, a token, and a reverse proxy in front. The constraint that decides most of the layout: moxzid does not terminate TLS and has no TLS stack in the binary, so the proxy is not optional for anything that leaves the host — the bearer token crosses the wire in plaintext without it.

Probes#

The listener binds before recovery, deliberately: a server that is invisible until it is ready is indistinguishable from one that is wedged. The 503 body carries what recovery is doing (reading the manifest, recovering <name>), so a long journal replay is legible. Wait on readiness in scripts:

until [ "$(curl -sf http://127.0.0.1:7000/health/ready)" = ready ]; do sleep 0.25; done

Shutdown#

SIGTERM and SIGINT are the graceful path: the message in flight finishes, nothing new starts, every actor is checkpointed, and the process exits 0 after printing shutdown: N actor(s) checkpointed. Give it room — TimeoutStopSec=60 — because the in-flight message runs to completion; it is not preempted. A hard kill is also safe, it is merely slower to come back, since the restart replays a journal instead of reading a snapshot.

systemd#

# /etc/systemd/system/moxzid.service
[Unit]
Description=moxzid Motoko actor server
After=network-online.target

[Service]
ExecStart=/usr/local/bin/moxzid -m /etc/moxzi/actors.json -s /var/lib/moxzi -l 127.0.0.1:7000
Environment=MOXZID_TOKEN=change-me        # or an EnvironmentFile= with 0600 perms
Restart=on-failure
TimeoutStopSec=60
User=moxzi
StateDirectory=moxzi

[Install]
WantedBy=multi-user.target

Docker#

services:
  moxzid:
    build: .            # the repo's Dockerfile, or your registry's image
    ports: ["7000:7000"]
    environment:
      MOXZID_TOKEN: change-me
    volumes:
      - moxzi-state:/state
      - ./actors.json:/app/actors.json:ro
volumes:
  moxzi-state:

Inside a container moxzid binds 0.0.0.0, which is exactly why the token is not optional there: a non-loopback bind without one is refused at startup.

TLS, in a reverse proxy#

# Caddyfile — TLS, HTTP/2, automatic certificates
actors.example.com {
    reverse_proxy 127.0.0.1:7000
}

nginx is the same idea: a stock proxy_pass http://127.0.0.1:7000; block with your certificates. Rate limiting, IP allowlists and origin restrictions belong here too — none of them exist in the binary, and saying so is more useful than half-implementing them.

Metrics#

GET /metrics (with the token) serves Prometheus exposition text.

scrape_configs:
  - job_name: moxzid
    authorization: { credentials: change-me }
    static_configs: [{ targets: ["127.0.0.1:7000"] }]

Reading them: a trap spike on one actor with a flat line on the rest is that actor's bug, not the server's. A falling moxzid_actor_cycles that reaches zero produces 402s — POST /cycles/<actor> with a decimal amount refills it. Growing moxzid_actor_heap_bytes past --snapshot-below silently moves that actor onto the WAL path, which lengthens recovery.

Logs#

Server output is human prose on stderr by default. --log-json switches to one JSON line per event:

{"ts":1787342315926,"event":"job","kind":"call","actor":"9c13…","method":"add","ok":"true","ms":"18"}

Heartbeat and timer ticks are deliberately not logged — they fire every second forever and would bury the lines you are grepping for. Metrics jobs are excluded for the same reason. The actors' own debug output is separate: GET /logs/<actor> takes and clears it, GET /events/<actor> streams it as SSE, and --verbose forwards it to the server's stderr.

Resource limits#

All per actor, all flags.

Failure to fix#

What this is not#

Single node: no clustering, no replication, nothing coordinating two moxzids. One shared token: no roles. No TLS in process. No certificates. Zero-downtime process replacement is not built — but upgrading an actor does not restart the server, which covers the common case. The behaviour contract is scripts/moxzid_*.sh; run them against your build rather than trusting this page.

Next#

• Persistence and durability — checkpoints, replay, and the backup recipe.
• Authentication — the token, the open routes, and what must never be exposed.
• The HTTP API — every endpoint with its request and response shape.