Skip to content

Quick start: Hub, first Scout, first endpoint

What you'll have at the end: a running Hub you can sign in to, one enrolled Scout (web-01), one endpoint (shop.example.com) observed, scored, and adopted under management with a renewal profile — the smallest complete Cyphers deployment.

This is the condensed end-to-end walk. Every step links the full page that owns its details; when something here is too terse, follow the link.

Prerequisites:

  • A Linux x86-64 host for the Hub with Docker Engine 24+ and Docker Compose v2, and the packaged release tarball (cyphers-ng-<version>-linux-amd64-docker.tar.gz).
  • A second Linux host that serves TLS (the future Scout host) with root access and network reach to the Hub.
  • Full requirements: Hub — install procedure and Scout — install procedure.

Time: about 30 minutes.

Mock values used throughout — substitute your real ones:
Hub https://hub.example.internal (UI on 443, PKI/REST on 8443)
Scout web-01, install root /opt/cyphers
Endpoint shop.example.com

Step 1 — Install the Hub and sign in

The quickest supported path is the packaged Docker install — the primary path on Hub — install procedure, which also covers the no-Docker bare-tarball route and the full environment variable reference. Condensed:

tar xzf cyphers-ng-<version>-linux-amd64-docker.tar.gz
cd cyphers-ng-<version>-linux-amd64-docker
docker load < docker/cyphers-hub.tar && docker load < docker/scout.tar
mkdir -p /opt/cyphers && cp .env.example /opt/cyphers/.env && cp docker-compose.yml /opt/cyphers/

Edit /opt/cyphers/.env — the stack refuses to start without the first four, and you should never ship the default database password:

CYPHERS_CA_KEY_PASSPHRASE=<strong passphrase>
ADMIN_PASSWORD=<strong initial admin password>
CYPHERS_CA_URL=https://hub.example.internal:8443
CYPHERS_NATS_ADVERTISED_HOST=hub.example.internal
DB_PASSWORD=<strong password>

Then start it and wait for readiness:

cd /opt/cyphers
docker compose up -d
curl http://localhost:8443/readyz

Migrations run automatically, and — because ADMIN_PASSWORD is set — the admin user is created for you (username admin unless you also set ADMIN_USERNAME). No separate create-admin step is needed on this path.

You should now see /readyz answer with "overall": "ok", and https://hub.example.internal/login show the Sign in page. Sign in with Username admin and the Password from .env. You land on Manage — an empty estate, which is correct: nothing is observed yet.

Step 2 — Enroll your first Scout

On Scouts, click Add Scout. In the Add a Scout dialog, enter web-01 as the Installer Scout name and click Download installer. Copy the downloaded file to the target host and run it as root:

scp install-web-01.sh you@web-01:/tmp/
ssh you@web-01 sudo /tmp/install-web-01.sh

The installer embeds a live enrollment token

Single-use, expires in 1 hour. Treat the file as a secret in transit and delete it after a successful install. (The dialog's Create enrollment alternative yields a raw command instead, for hosts that already have the Scout binary.)

The script installs the binary to /opt/cyphers, enrolls, and starts the cyphers-scout systemd service — full detail, including custom install roots and what lands where, in Scout — install procedure.

You should now see web-01 in the Enrolled Scouts table with status active and a Last seen that advances within a minute.

Step 3 — Track your first endpoint

On the Scout's host, append the endpoint to the targets file and trigger a cycle (the file is re-read every scan cycle; the reload just starts one now instead of waiting):

$ echo "shop.example.com:443" >> /opt/cyphers/targets.conf
$ sudo systemctl reload cyphers-scout

You should now see, within a couple of minutes, a row for shop.example.com on Manage, labelled Untracked — observed serving, scored, not yet under management. That's the expected resting state. (Full walk, including the cert-dirs file that later authorizes renewal delivery: Track a new endpoint.)

Step 4 — Create a renewal profile

Under Settings → Certificate issuance → Renewal Profiles, click New Profile and fill in:

Field Value
Profile Name le-http01-staging
Contact Email ops@example.com
Issuer Type Public ACME
Provider Let's Encrypt
Environment Staging
Validation Method HTTP-01

Leave the rest at defaults and click Create Profile. Every field, and when to choose differently, is on Hub — renewal profiles.

Staging first

The form's own hint is the rule: "Start with staging to validate your setup, then switch to production." Staging certificates are issued by Let's Encrypt's test environment and are not browser-trusted — use this profile to prove the pipeline works, then edit the profile's Environment to Production (or create a production profile) before renewing an endpoint real clients depend on.

You should now see the profile in the Renewal Profiles table with issuance HTTP-01 and env staging.

Step 5 — Adopt the endpoint

Back on Manage, the shop.example.com row offers Adopt. Pick le-http01-staging in the Renewal profile select and click Apply.

You should now see the row leave the Not managed section and render as a managed endpoint. Adoption changes management state only — nothing has been ordered: the first renewal happens when you click Renew Now (offered on the row as Needs Renewal once the certificate is inside its renewal window) or when autopilot's window arrives. The renewal walkthroughs pick it up from here: Adopt an endpoint for what adoption did and didn't do, and Renew through a third-party CA for a full click-by-click renewal. If a renewal click is refused, that is the pre-flight doing its job before any order exists — look the message up in Recover from refusals.

Step 6 — Read the Manage row

One row now tells you the endpoint's whole story. Read it left to right:

  • State chip — Healthy when both vantages agree and nothing needs attention; Partial when only one vantage has evidence; Needs Renewal when the certificate is inside its renewal window (and the row's action becomes Renew Now). The chip and the single action always move together — the action offered is the one appropriate to the state.
  • Score ring — the Cyphers Score, 0–100. An Internal only tag beside it means the score rests on Scout evidence alone — the Hub has not observed the endpoint externally yet.
  • The hostname is the way in — click it to open the endpoint's detail drawer, which carries the full readiness verdict, the certificate, and the destructive or multi-field actions the table deliberately doesn't. From there, Findings breaks the score down deduction by deduction, Renewals lists every renewal with its outcome, and Scout ops shows the assigned Scout and its recent commands.

You should now see a scored, managed endpoint whose row you can read — which is the whole product loop: observe, score, manage, renew.

Where to go next