themodcrafttmc/nexcore repository overview

⁠NexCore

NexCore builds a GitHub-hosted web application inside a local OpenResty container. A single public master receives GitHub webhooks and sends deploy events to every matching local instance over a persistent server-sent events (SSE) connection. Master-connected instances no longer poll GitHub, while legacy polling remains available during migration.

Tracked project files are left untouched by default. NexCore adapts to each framework's normal output paths; legacy preset patching is available only through an explicit opt-in.

⁠Architecture

GitHub ── signed POST /webhooks/github ──▶ NexCore master
                                                   │
                                 authenticated SSE │
                       ┌───────────────────────────┼──────────────────────┐
                       ▼                           ▼                      ▼
                 local runner A              local runner B       local runner C
                 owner/site@main              owner/site@main       owner/api@main

The master routes each push by repository.full_name and branch. All connected instances subscribed to the same repository and branch are notified. Event IDs are retained in a bounded in-memory history so a reconnecting runner can receive pushes it missed during a short network interruption.

⁠Run the master

Generate two independent random secrets:

openssl rand -hex 32
openssl rand -hex 32

Build and start the public master:

docker build --target master -t nexcore-master .
docker run --name nexcore-master \
  -p 8080:8080 \
  -e MASTER_TOKEN='<runner-connection-secret>' \
  -e WEBHOOK_SECRET='<github-webhook-secret>' \
  nexcore-master

Expose port 8080 through HTTPS, then create a GitHub repository or organization webhook with:

• Payload URL: https://deploy.example.com/webhooks/github
• Content type: application/json
• Secret: the value of WEBHOOK_SECRET
• Events: push events only

GET /health returns the master status and current connection count. The webhook is accepted only when its HMAC-SHA256 signature is valid. Duplicate GitHub delivery IDs are ignored.

⁠Run local instances

Build the runner image:

docker build --target runner -t nexcore-runner .

Start one runner per deployment:

docker run --name nexcore-site \
  -p 8081:80 \
  -e MASTER_URL='https://deploy.example.com' \
  -e MASTER_TOKEN='<runner-connection-secret>' \
  -e GITHUB_URL='https://github.com/owner/repository.git' \
  -e GITHUB_TOKEN='<github-access-token>' \
  -e GITHUB_BRANCH='main' \
  nexcore-runner

The runner connects to the master before its initial deployment, then stays connected. A disconnected runner retries with exponential backoff up to 30 seconds. Pushes received while a build is already running are coalesced into one follow-up build at the newest revision.

For private networking, MASTER_URL can point directly at the master service (for example http://master:8080); only GitHub's webhook URL must be public.

⁠Gradual migration from polling

Existing runner configurations continue to work unchanged. In the default DEPLOY_MODE=auto, a runner uses the master when MASTER_URL is configured and falls back to the original Git polling watcher when it is absent.

Set DEPLOY_MODE=poll to keep a particular runner on polling during migration, even if a master URL is already available. Set DEPLOY_MODE=master when that runner must require the webhook master and should fail fast on missing master configuration.

⁠Configuration

Use different values for MASTER_TOKEN and WEBHOOK_SECRET, store both as deployment secrets, and rotate both if either is disclosed.

⁠Commands

• nextcli master starts the webhook/event master.
• nextcli watch performs an initial deploy, then uses master events or legacy polling according to DEPLOY_MODE.
• nextcli build performs one deploy and exits the watcher path.

Run the control-plane tests with npm test from the cli directory.