Skip to main content
Version: v5.7.0

0.1 Install and sign in

Included from Basic tier

After this you can: put the opschain binary on your PATH, start a server of your own, create the first admin credential and sign in from the command line.

Before you start — the opschain binary on your PATH: lesson 0.0 puts it there (a package manager or a verified download — macOS, Linux and Windows), then come back here once opschain version answers. This lesson is the root of every track.

In the GUI: the root URL lands on the login screen; once in, the profile menu (top right) names your login with a chip for the provider it came from.

One binary, one server, one login. In this lesson you check the binary, bring up a server of your own, get its first administrator credential, and sign in — ending with opschain whoami telling you who the server thinks you are. That last command is what the Academy's first-contact exercise checks.

1. Check the binary​

opschain version
opschain version v5.7.0 (commit 115eecc, built 2026-10-12T10:57:07Z)

The version shown above is the one this documentation ships inside — yours matches your binary. The commit and build timestamp here are illustrative: yours identify your exact build.

One binary carries everything: the CLI, the server (opschain server) and the runner (opschain runner). opschain doctor checks your host's capabilities (git is required; a container runtime unlocks optional step kinds).

2. Start a server​

If you already have a server to work against, skip to the login in step 4. Otherwise, the one-command way to evaluate the full server — PostgreSQL, the server and the GUI together — is the go-opschain Docker Compose (github.com/LimePoint/go-opschain): clone it, run ./configure (it asks a few questions and writes the compose's .env, including the database password as PGPASSWORD), then docker compose up. The server and the GUI answer at http://localhost:8443; the first boot prints the admin password once to the server's log (docker compose logs server | grep "initial admin password" — step 3 below). Its PostgreSQL answers database opschain as user opschain on port 5432, so a binary of your own can point at it with that DSN.

To bootstrap a server from this binary against a PostgreSQL database you already have (the compose's, or any other):

opschain server configure --store postgres://opschain@localhost:5432/opschain
opschain server start

Keep the password out of the DSN: put PGPASSWORD=… in $OPSCHAIN_HOME/server/keys.env and every parameter missing from the DSN resolves from the standard PG* variables.

server configure writes a complete runnable configuration to $OPSCHAIN_HOME/server/config.yaml — listen address (default 127.0.0.1:8443), store, blob root — plus generated key material in keys.env. Back those keys up: encrypted data is unrecoverable without them — and on PostgreSQL the token secret among them is a start requirement: a server that finds no OPSCHAIN_TOKEN_SECRET_KEY and no stored token.secret_key refuses to start by name rather than serve every caller unauthenticated as the superuser (opschain docs cli/server-start). For a fully annotated config covering every supported key:

opschain server configure --template > config.yaml

server start then brings up the whole system in one process: the API, the scheduler, the runner protocol — and the GUI, served at the root URL. Open http://127.0.0.1:8443/ in a browser and the web interface is there, talking to the same /api on the same port.

Choose the store deliberately. Without --store, the server runs on an embedded SQLite database, and that server is a development harness, labelled as one: it serves the run engine behind the run/step/log API, the runner and agent fleet, licensing and the home's local secret store — for tests, runner-fleet play and GUI development against its API (lesson 0.2 names the three postures) — but it holds no users, no estate, no templates, no workflow catalog, no notifications and no governance: every one of those families needs PostgreSQL, and under SQLite they answer with exactly this guidance. Three things make the harness visible: it binds to loopback (127.0.0.1:8443) unless you pass --listen or set listen: explicitly — it has no sign-in, so a non-loopback address is honoured but called out; it prints a startup notice naming the posture, what it serves and does not, and the address it bound; and it does not serve the GUI — the root URL answers a plain page saying the GUI needs a server on PostgreSQL. server configure prints the same guidance whenever the persisted store is the SQLite file. A server on SQLite knows no users, so there is nobody to sign in as: run the trial compose above, or give server configure a --store postgres://… DSN or set store: in config.yaml. PostgreSQL 18.6 or newer is the minimum for a new deployment; 17 is supported as the previous major; 16 and older are refused at start-up with a message naming this policy. Give server start --tls-cert/--tls-key for HTTPS; plain HTTP is acceptable for loopback development only. opschain docs config is the full configuration reference.

The very first start of a fresh installation asks you to accept the LimePoint End User Licence Agreement: in a terminal the agreement is printed and you type accept; for an unattended install pass --confirm-eula or set eula: {accepted: true} in config.yaml. Read it any time with opschain eula. Acceptance is recorded once in the server's store and never asked again; the matching api:eula:accepted audit event is written on PostgreSQL only — a server on the SQLite store keeps the acceptance record but records no event for it, as for the licence applied and removed events (opschain docs events).

3. Your first admin credential​

On a brand-new server (a store holding no users yet), the first start creates a local administrator for you: username admin, flagged break-glass, holding the Superuser policy. Its generated password is printed to the console exactly once:

opschain server: first boot: created local administrator "admin" (break-glass, superuser)
opschain server: initial admin password: … — store it now, it will not be shown again

Store it immediately (and rotate it at will with opschain admin users reset-password admin). For unattended installs set OPSCHAIN_BOOTSTRAP_ADMIN_PASSWORD in the server's environment and nothing is printed. (A server configured with security.posture: hardened never generates and prints a password: it requires that environment variable for the first boot and makes the admin rotate it on first login — see opschain docs identity.) From there you can create everyday users with opschain admin users create and change your own password with opschain passwd — no directory required; an enterprise directory plugs in later as a peer identity provider (lesson 7.5).

The opschain admin commands work with a plain opschain login session: the server authorises the caller through its access rules, which a superuser passes. A separate admin token is only for a server with no auth stack (the embedded store, started with --admin-token <value>); a PostgreSQL server refuses the token with a typed answer naming the alternatives — your own login, or a service-account API key (opschain tokens create) for automation.

4. Log in​

opschain login --server http://127.0.0.1:8443 --username admin

You are prompted for your password (never stored); the CLI exchanges the credentials for an API token, stores the token in your OS keychain (or a permission-locked file with --no-keychain), and records a context for the server — activated immediately so subsequent commands target it (lesson 0.3). Already have a token? Use --token instead of --username.

Check who the server thinks you are:

opschain whoami
Server: http://127.0.0.1:8443
Identity: admin
Provider: local
Break-glass: true
Superuser: true

Provider names the identity provider the account belongs to (local or ldap:<code>) — useful when one username exists under more than one provider. Break-glass: true is the bootstrap administrator's flag; an everyday user does not carry it.

opschain logout removes the stored token and deactivates the context.

5. The verified version​

Everything above is checkable from the server's own record: the login you just made was recorded as an api:auth:login event, and whoami is the server resolving your credential. The OpsChain Academy's first-contact exercise asks that same server both questions. Lesson 0.3 shows how to install and start the Academy agent; it needs a server with a PostgreSQL store, because a SQLite server knows no users.

Check yourself​

  • Does opschain whoami name you — and did you sign in after starting the exercise? The Academy's first-contact exercise reads the api:auth:login event raised since the attempt began, so a session from earlier does not count.
  • What does opschain whoami print after you sign in, and which of its fields names the server you are talking to?
  • Verified version: opschain academy runs the first-contact exercise against this lesson.

What you learned​

  • opschain version and opschain doctor tell you what you are running and what the host can do.
  • server configure writes the config and keys; server start runs the API, scheduler, runner protocol and GUI in one process — on PostgreSQL if you want users or the GUI. Without a store it is a loopback-bound development harness that says so at startup; the go-opschain Docker Compose is the one-command way to evaluate the full server.
  • The first boot prints the admin password exactly once; store it and rotate it.
  • opschain login records a context and a token; opschain whoami shows the identity the server resolves for it.

Next: lesson 0.2 — Local mode and server mode (opschain learn 0.2), or back to your track (opschain learn).