Install the Controller¶
The Controller is the JANUS management component. It hosts the Management API and the bundled WebUI, keeps the configuration of record in Git, projects runtime state into PostgreSQL, and compiles configuration into the desired state that each Gateway applies. The Controller never touches the data plane itself.
Operator / browser
|
v
Controller Management API · WebUI · Self-Service Portal
| Git-backed configuration · PostgreSQL state
| compiles per-Gateway desired state
v
Gateway node(s) receive and apply the compiled state
For where the Controller sits relative to the rest of a deployment, see Architecture overview. To author configuration once it is running, see Configuration.
Prerequisites¶
| Requirement | Detail |
|---|---|
| Operating system | Debian 13 (trixie), amd64 |
| Database | PostgreSQL, local or external — an external database is a first-class configuration, nothing is localhost-specific |
| Desired-state Git | a repository reachable over ssh://, https://, or as a local path |
| Privileges | root/sudo to install the package and manage the service |
| Operator CLI | install janus-cli (provides /usr/bin/janus) on the host from which you will issue operator commands |
The Controller requires no reverse proxy: it installs and runs with no Caddy
present. The optional janus-caddy package adds a reference HTTPS front door
(see TLS and the front door).
Packages¶
| Package | Contents |
|---|---|
janus-controller |
the Controller, the WebUI, the Self-Service Portal, database migrations |
janus-caddy (optional) |
the reference HTTPS front door (Caddy), wired for JANUS |
janus-cli |
the janus operator CLI |
Install¶
# Controller only, or with the reference front door:
sudo apt-get install -y ./janus-controller_<version>_amd64.deb
sudo apt-get install -y ./janus-controller_<version>_amd64.deb ./janus-caddy_<version>_amd64.deb
# the operator CLI:
sudo apt-get install -y ./janus-cli_<version>_amd64.deb
The package installs:
| Path | Purpose |
|---|---|
/usr/bin/janus-controller |
the Controller |
/usr/bin/janus-webui |
the bundled WebUI (an API client) |
/usr/bin/janus-portal |
the Self-Service Portal |
/usr/share/janus/migrations/*.sql |
versioned, forward-only database migrations |
/etc/janus/controller.yaml |
Controller configuration (conffile) |
/etc/janus/controller.env |
environment — DSN/password (conffile, 0640 root:janus-controller) |
/usr/lib/systemd/system/janus-controller.service |
the Controller service |
/usr/lib/systemd/system/janus-webui.service |
the WebUI service |
/usr/lib/systemd/system/janus-portal.service |
the Self-Service Portal service |
/var/lib/janus/controller/ |
Controller state (Git work directory) |
/var/lib/janus/controller/git/ |
the desired-state Git work directory |
The package creates the system user and group janus-controller and enables
(does not start) janus-controller.service, janus-webui.service and
janus-portal.service. janus-controller depends on ca-certificates and
adduser, and merely Suggests: janus-caddy — it never requires Caddy.
Configure PostgreSQL¶
Create a role and database. Both a local and a remote PostgreSQL are supported identically:
sudo -u postgres psql <<'SQL'
CREATE ROLE janus LOGIN PASSWORD 'change-me';
CREATE DATABASE janus OWNER janus;
SQL
Point the Controller at the database in the database: block of
/etc/janus/controller.yaml (for the default local database, host: 127.0.0.1,
port: 5432, name: janus, user: janus):
The password is never stored in controller.yaml. Put it in
/etc/janus/controller.env:
or override the whole connection string:
Migrations are applied automatically at Controller start. A migration failure fails the start: the Controller never serves a misleading "healthy" partial state.
Configure the desired-state Git repository¶
Git is the desired-state source of truth. Configure it in the git: block of
/etc/janus/controller.yaml:
git:
repository: ssh://git@git.example.net:2222/team/janus-config.git
branch: main
workDir: /var/lib/janus/controller/git
pollInterval: 30
transport: ssh
auth:
kind: ssh-key
sshUser: git
sshKeyFile: /etc/janus/credentials/git_ssh_key
trust:
kind: ssh-known-hosts
sshKnownHostsFile: /etc/janus/credentials/git_known_hosts
- The configuration names secrets by file path; it never contains them. Place
controlled keys and a
known_hostsfile under/etc/janus/credentials/. - Host-key and certificate verification is never relaxed. An unknown or changed SSH host key, or an untrusted HTTPS certificate, fails the fetch closed.
- A repository URL must not embed credentials.
- A fresh, empty repository can be bootstrapped by the Controller: on first reconciliation it materializes the branch and treats the current head as the observed revision. Direct Git administration remains supported.
Configuration keys¶
/etc/janus/controller.yaml — the most relevant keys:
| Key | Meaning |
|---|---|
network.allowedPublicIPv4, network.allowedPublicIPv6 |
public prefix aggregates the Controller may manage or delegate |
database.host, database.port, database.name, database.user |
PostgreSQL connection (password lives in controller.env) |
git.repository, git.branch, git.workDir, git.pollInterval |
desired-state repository and poll cadence |
git.transport, git.auth.*, git.trust.* |
transport, authentication and trust profile |
managementApi.listen |
Management API listener (also serves /healthz and /readyz) |
webui.listen |
WebUI listener |
portal.listen |
Self-Service Portal listener |
auth.local.enabled, auth.sessionAbsoluteSeconds, auth.sessionIdleSeconds |
local authentication and session lifetimes |
delivery.autoApply, delivery.gateways[] |
optional delivery of compiled state to Gateway nodes (see below) |
Environment variables (/etc/janus/controller.env): JANUS_DB_PASSWORD (or the
DSN override JANUS_DATABASE_URL). The config-file locator variables
JANUS_CONTROLLER_CONFIG select which file is read; they never carry a
listener value.
The configuration-file resolution order for the Controller is: --config flag,
then JANUS_CONTROLLER_CONFIG, then /etc/janus/controller.yaml.
Listeners and ports¶
Both listeners default to loopback and are operator-configurable:
| Listener | Key | Default |
|---|---|---|
Management API (also /healthz, /readyz) |
managementApi.listen |
127.0.0.1:8081 |
| WebUI | webui.listen |
127.0.0.1:8080 |
| Self-Service Portal | portal.listen |
127.0.0.1:8082 |
| PostgreSQL | its own configuration | 127.0.0.1:5432 |
An address is host:port. A configured value is used verbatim; JANUS never
widens a configured address to a wildcard and never rewrites it back to
loopback. A DNS name is rejected — a listener is a local binding decision. An
invalid or unbindable address fails the start rather than being silently
defaulted. The historically named health.listen key is still honoured as a
deprecated alias for managementApi.listen and prints a warning.
Binding a wider address (for example an explicit management IP) is a deliberate operator decision with a network-policy consequence.
TLS and the front door¶
The Management API, WebUI and Portal are ordinary HTTP listeners. In the
reference deployment, TLS is terminated by Caddy on :443 via the optional
janus-caddy package:
HTTPS :443 (Caddy)
+---- /api/v1/* -> 127.0.0.1:8081 Management API
`---- everything -> 127.0.0.1:8080 WebUI
janus-caddyinstalls/etc/janus/caddy/Caddyfileand acaddy.servicedrop-in (both conffiles), enablescaddy.service, and validates the Caddyfile before every start.- Caddy preserves the request unchanged and adds only
X-Forwarded-*provenance headers. JANUS takes no authentication or authorization decision from a forwarded header. - Because the browser session cookie is
__Host-/Secure, the WebUI login flow requires HTTPS. A plain-HTTP or headless deployment mints an API token instead (below). - The reference front door uses Caddy's internal CA (no public DNS, no ACME).
Its root certificate is written to
/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt; install it into a client's trust store to trust the front door. Verification is never disabled.
You may instead place any compatible ingress (nginx, HAProxy, an F5, a Traefik, an ALB, …) in front of the loopback listeners, or bind an explicit management address directly. The proxy is a deployment choice, not a JANUS dependency.
First-run: establish the administrator¶
There is no default credential. Until an administrator exists, the
administrative routes fail closed with 503. Create the first administrator
from the Controller host:
# The admin subcommands talk to PostgreSQL directly, so they need the database
# password from /etc/janus/controller.env (the systemd unit loads that file as its
# EnvironmentFile; a manual invocation must load it too, or it fails with a
# PostgreSQL SASL authentication error).
sudo env JANUS_DB_PASSWORD="$(sudo sed -n 's/^JANUS_DB_PASSWORD=//p' /etc/janus/controller.env)" \
/usr/bin/janus-controller admin bootstrap \
--username admin --password-file /etc/janus/credentials/bootstrap.txt
Alternatively, source the environment file first and run the command as the
janus-controller service user:
sudo bash -c 'set -a; . /etc/janus/controller.env; set +a; \
exec runuser -u janus-controller -- /usr/bin/janus-controller admin bootstrap \
--username admin --password-file /etc/janus/credentials/bootstrap.txt'
The password is read from a file (--password-file) or from stdin
(--password-stdin) — never from a command-line argument. The janus-controller
admin subcommands are bootstrap, create-token, status,
enable-break-glass, disable-break-glass and rotate-break-glass. The
top-level janus-controller commands are run, config validate, config
compile, config migrate and admin.
Issue an API token without a browser¶
sudo -u janus-controller /usr/bin/janus-controller admin create-token \
--username admin --name ops-cli --scopes gateway:read,gateway:admin --ttl 24h
The token is printed exactly once. Use it with the janus operator CLI,
through the HTTPS front door (install the front door's CA into the trust store
first):
export JANUS_CONTROLLER_URL=https://<controller-front-door>
export JANUS_TOKEN=jns_...
janus enrollment list --state pending
janus enrollment approve <gateway-id>
Start and verify¶
sudo systemctl start janus-controller janus-webui janus-portal
sudo systemctl start caddy # reference front door only
systemctl status janus-controller janus-webui janus-portal --no-pager
curl -fsS http://127.0.0.1:8081/healthz # process is alive
curl -fsS http://127.0.0.1:8081/readyz # ready: DB reachable + a last-known-good revision exists
journalctl -u janus-controller -n 40 --no-pager
Health versus readiness
/healthz proves only that the process is alive. /readyz proves the
Controller is ready — that PostgreSQL is reachable and a
last-known-good revision exists. A running process does not imply a healthy
service. Both endpoints are loopback-only; :443 is the front door.
Both services log the address they actually bound. The Controller logs its Git transport/trust/auth profile, database migration status and reconciliation results, and never logs a secret.
Optional: deliver state to Gateway nodes¶
Reconciliation produces a compiled desired state per enabled Gateway object.
Delivery — and, optionally, application — is installation configuration in the
delivery: block of controller.yaml:
delivery:
autoApply: true # request application after the Gateway validates
gateways:
- name: gw1 # must match the desired-state Gateway object's name
endpoint: https://gw1.example.net:9443
connectTimeoutSeconds: 10
requestTimeoutSeconds: 30
- With no
delivery:block the Controller reconciles and compiles but does not deliver — a legitimate state on an installation with no Gateway nodes yet. - Delivery mTLS is automatic. The Controller's per-Gateway client certificate
and key are issued by the dedicated control-plane CA and renewed automatically;
the Gateway's server certificate (also issued by that CA) is verified against
the Gateway's enrolled identity. There is no operator certificate ceremony:
tlsCert/tlsKey/caCert/expectedIdentitymay be omitted, and are only used to override the automatic identity with externally managed material. autoApplyrequires the Gateway to haveagent.applyHelperPathset (see Gateway installation).- Delivery is distinct from application:
delivered != applied. The Operations screen reports each state separately. - Certificate verification is never disabled.
Upgrade behaviour¶
sudo apt-get install -y ./janus-controller_<new-version>_amd64.deb
# (preflight and migrate the desired-state repository — see below)
sudo systemctl restart janus-controller janus-webui janus-portal
controller.yaml,controller.envand theCaddyfileare conffiles: an administrator's edits are preserved across an upgrade, not overwritten.- New database migrations are applied on start. Desired state is not a database concern: JANUS never rewrites your desired-state repository on upgrade.
- The enrolled-gateway trust table and the PostgreSQL database survive an upgrade unchanged.
- A running unit is restarted onto the new binary; the enrolled gateways are not re-enrolled and do not need to be re-approved.
Upgrading the desired-state repository (required from 0.23.0)¶
From 0.23.0 the relationships MSP → Tenant, Deployment → Tenant and GatewayNode → Tenant are identity-bearing: the tenant's immutable UUID is authoritative and its name is advisory display metadata. A repository authored before this change carries the older name-only form for those references. Such a reference no longer validates — it is refused rather than silently matched by name — so the controller keeps the last accepted state instead of applying a repository whose references are not pinned to durable identity.
Bring the repository to the canonical form with the local, operator-run migration.
It reads a working copy of the desired-state repository, resolves each legacy name
to the tenant's existing UUID (no new identity is invented) and rewrites the
reference as {uuid, name}, keeping the name readable for Git. It never commits,
pushes or touches a remote, and never runs implicitly.
# 1. Preflight — non-zero exit if any legacy reference remains.
janus-controller config migrate-references --check --path /path/to/desired-state
# 2. Inspect the exact proposed change (read-only).
janus-controller config migrate-references --dry-run --path /path/to/desired-state
# 3. Apply, then review and commit through your normal Git workflow.
janus-controller config migrate-references --path /path/to/desired-state
git -C /path/to/desired-state diff # comments and key order are preserved
# ... commit and push as usual; the controller picks up the new revision
- Deterministic and idempotent. A second run reports nothing to do; re-running never changes an already-pinned reference.
- Fail-closed on an unresolved name. A name that does not resolve to a
declared, durably-identified tenant is reported and left untouched — it is never
guessed. The tenant must already carry
metadata.uuid; materialise the tenant first if it does not. - Comments and key order survive — only the reference nodes are rewritten.
- No authority transfer. Because the reference records the UUID, a later rename keeps the relationship and a later reuse of a deleted tenant's name can never take it over.
- Objects you change through the Management API or WebUI are pinned automatically when written; only pre-existing objects need this step.
See controller config migrate-references.
Remove and purge¶
sudo dpkg -r janus-controller # stop + disable; keep configuration and state
sudo dpkg -P janus-controller # also remove package-owned configuration
- Remove leaves
/etc/janus,/var/lib/janus/controllerand the database in place. The front door (the separatejanus-caddypackage), if present, is untouched. - Purge removes package-owned configuration but deliberately preserves
/var/lib/janus/controller, the PostgreSQL database and Caddy's data directory (including the local CA). Destroying administrator data or a certificate as a side effect of a package operation is unsafe; removing that data is an explicit, separate action.
Limitations¶
- The Controller never applies configuration to the data plane; that is the Gateway's job. A Gateway that has received state is not reported as having applied it until application succeeds.
- The front door's reference certificate is issued by Caddy's internal CA for a private/IP name. A publicly trusted FQDN requires pointing Caddy (or your own ingress) at that name; nothing else in the deployment changes.
Related¶
- Gateway installation — the data-plane component.
- Configuration — authoring the desired state.
- Operations — running the control plane day to day.
- Troubleshooting — when something diverges.
- Command-line interface — the
janusoperator CLI. - Management API — the API the WebUI and CLI use.