Self-hosting

Runner settings

What the runner reads at start, what it keeps, and where.

Ports

The runner is one container with one volume at /data. It listens on two ports:

8080, services' traffic, for the HTTPS proxy in front.
8081, the API, for the app that manages the runner: the panel, or plane on Zeroko Cloud. Keep it private. It also answers /healthz.

Environment

The environment holds only what the runner needs before its API answers:

Variable	Default
`ZEROKO_TOKEN`	required	The root API token, 32 characters or more
`ZEROKO_UID`, `ZEROKO_GID`	`1000`	The user and group the runner runs as, and that own `/data`

The runner starts as root only to give /data to that user and group, then runs as them. Started as another user (--user, or user: in Compose), it runs as that one and leaves /data as it is.

Settings

Everything else is a setting, kept in the runner's database. The panel changes them in System; through the API, GET /api/settings reads them and PATCH /api/settings changes some and restarts the runner in place. Services start again on their next request, and realtime connections close.

Setting	Default
`domain`	none	Services at `<name>.<domain>`; until it is set, none is served
`separator`	`.`	Between a service's name and the domain: `--` serves them at `<name>--<domain>` instead
`public_scheme`	`https`	The scheme clients use for services; `http` for local use
`max_body_mb`	`100`	Request body limit for services
`heap_mb`	`128`	V8 heap per service
`cpu_seconds`	`30`	Continuous CPU before a service is restarted
`cpu_seconds_per_minute`	`30`	CPU a service may use in any minute: past it, it waits (its requests are held, not failed) until the minute fits; `0` for no limit
`realtime_connections`	`1000`	Realtime connections a service holds at once
`rate_limit`	`0`	Requests a second each client (by address) may make to a service, with bursts of twice as many, unless the service has its own; `0` for none
`idle_seconds`	`600`	Idle time before a service's process stops
`max_processes`	`50`	Service processes at once, 25 to 60 MB each
`disk_mb`	`5120`	A service's disk quota, unless it has its own
`egress`	`true`	`false`: no service may make outbound requests

curl -X PATCH http://127.0.0.1:8081/api/settings \
  -H "Authorization: Bearer $ZEROKO_TOKEN" \
  -d '{"domain": "example.com"}'

Data

text

/data
├── runner.db       services, deployments, secrets (encrypted), vars, logs, jobs, metrics, tokens
├── master.key      the key of the secrets: keep it with the rest
├── bundles/        deployed code, by SHA-256
├── assets/         public/ files extracted from the bundles, recreated as needed
├── services/<id>/
│   ├── db/<binding>.sqlite
│   └── files/<binding>/{index.sqlite, blobs/}
├── run/            process directories, recreated on start
└── restore/        a backup being restored, until the runner restarts

Deleting a service deletes its deployments, secrets, vars, logs, jobs and data at once. Only one runner may use a data directory at a time.

PreviousThe panel NextBackups and upgrades