SciMesh/mkdocs/standalone.md

Standalone (split) setup

The single-binary coordinator serve mode is the default for a scientist on one machine. The standalone setup splits the platform into separate processes — the coordinator, the userservice, and any number of workers — typically on different machines, backed by PostgreSQL. This is the cluster deployment.

Browser (operator)
   │
   ▼
┌──────────────────────────────┐       ┌───────────────────────────┐
│  coordinator  (port 8080)    │       │  userservice (port 8081)  │
│  jobs · tasks · artifacts    │◄─────►│  users · roles · keys     │
│  PostgreSQL DB "scimesh"     │  JWT  │  PostgreSQL DB             │
└──────────────┬───────────────┘ secret │  "scimesh_users"          │
               │                        └───────────────────────────┘
               │  HTTP (workers connect out)
               ▼
      worker-agent × N  (COORDINATOR_URL, WORKER_AUTH_TOKEN)
        └─ python -m scimesh.worker.task   (needs Python + scimesh)

Each component is a separate process; workers never touch a database — they only talk to the coordinator over HTTP.

What each component needs

Component	Binary	Configuration
Coordinator	coordinator (SCIMESH_DB=postgres)	DATABASE_URL, COORDINATOR_ADDR, COORDINATOR_TOKEN, COORDINATOR_STORAGE_DIR, JWT_SECRET, USERSERVICE_URL, PUBLIC_COORDINATOR_URL
Userservice	the users/ service	USERSERVICE_ADDR, DATABASE_URL (its own DB), JWT_SECRET (must match the coordinator), BOOTSTRAP_ADMIN_EMAIL / BOOTSTRAP_ADMIN_PASSWORD
Worker	worker-agent	COORDINATOR_URL, WORKER_AUTH_TOKEN, WORK_DIR, TASK_RUNNER (JSON array), CPU_COUNT, MEMORY_MB

JWT_SECRET is the one secret shared between the coordinator and the userservice: the userservice signs tokens with it, the coordinator verifies them. It must be at least 32 bytes and identical on both.

Option A — Docker Compose (fastest)

The repository ships compose files for the whole split stack: PostgreSQL for both services, migrations, the coordinator, and the userservice:

cd coordinator
JWT_SECRET='change-me-32-bytes-minimum' \
BOOTSTRAP_ADMIN_EMAIL='root@scimesh.local' \
BOOTSTRAP_ADMIN_PASSWORD='choose-a-strong-password' \
  docker compose -f docker-compose.yml -f docker-compose.users.yml up -d --build

Then install workers on any machines with Python. The worker's own setup wizard walks through the rest — URL, token or worker key, work directory — and starts the worker for you:

curl -fsSL https://raw.githubusercontent.com/emil28092005/SciMesh/main/install.sh | bash -s worker
# the installer opens the local wizard at http://127.0.0.1:12700 automatically

On a headless server (no desktop environment), RDKit needs a few X11 libraries that desktops already ship — install them once with apt:

sudo apt-get install -y libxrender1 libxext6 libxcursor1 libxfixes3 libxi6 libxrandr2

Or configure by hand:

export COORDINATOR_URL=http://COORDINATOR_HOST:8080
export WORKER_AUTH_TOKEN="$COORDINATOR_TOKEN"   # the coordinator's shared token
export WORK_DIR=~/scimesh-worker
worker-agent

Option B — Manual binaries

1. Provision PostgreSQL (two databases, or one server and CREATE DATABASE):

   ./coordinator setup --yes \
     --db 'postgres://scimesh:scimesh@db-host:5432/scimesh?sslmode=disable' \
     --env-file /etc/scimesh/coordinator.env
   

   The wizard creates the database when missing and writes the .env with a generated JWT_SECRET. The userservice needs its own database — create it and apply users/migrations (e.g. with the migrate CLI):

   createdb scimesh_users
   migrate -path users/migrations \
     -database 'postgres://scimesh:scimesh@db-host:5432/scimesh_users?sslmode=disable' up
   

2. Run the userservice with the same JWT_SECRET:

   cd users && make build   # builds the binary into users/bin/
   USERSERVICE_ADDR=':8081' \
   DATABASE_URL='postgres://scimesh:scimesh@db-host:5432/scimesh_users?sslmode=disable' \
   JWT_SECRET='<same secret>' \
   BOOTSTRAP_ADMIN_EMAIL='root@scimesh.local' \
   BOOTSTRAP_ADMIN_PASSWORD='choose-a-strong-password' \
     ./bin/userservice
   

3. Run the coordinator:

   ENV_FILE=/etc/scimesh/coordinator.env ./coordinator
   # or, without the .env:
   SCIMESH_DB=postgres \
   DATABASE_URL='postgres://scimesh:scimesh@db-host:5432/scimesh?sslmode=disable' \
   COORDINATOR_ADDR=':8080' \
   COORDINATOR_TOKEN='a-worker-token' \
   COORDINATOR_STORAGE_DIR='/var/lib/scimesh/artifacts' \
   JWT_SECRET='<same secret>' \
   USERSERVICE_URL='http://127.0.0.1:8081' \
   PUBLIC_COORDINATOR_URL='http://coordinator.example:8080' \
     ./coordinator
   

   The binary applies its embedded schema migrations on startup (AUTO_MIGRATE=false to disable when you manage them out of band).

4. Attach workers as in Option A (or via worker-agent setup). The UI login uses the userservice session; the workers use COORDINATOR_TOKEN or a worker key. The coordinator's admin console (/ui/admin) shows the whole cluster: jobs, worker fleet with trust controls, accounts and keys, workload switches and metrics.

Notes

• The coordinator and the userservice each keep their own PostgreSQL database — different bounded contexts, deliberately not shared.
• A worker can join by hostname or IP; only outbound HTTP from the worker to the coordinator is required (no inbound firewall rules on workers).
• For a quick all-in-one alternative, coordinator serve embeds all of this on one machine — see the home page.