Skip to content

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):

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:

JANUS_DB_PASSWORD=change-me

or override the whole connection string:

JANUS_DATABASE_URL=postgres://janus:secret@db.example.net:5432/janus?sslmode=require

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_hosts file 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-caddy installs /etc/janus/caddy/Caddyfile and a caddy.service drop-in (both conffiles), enables caddy.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/expectedIdentity may be omitted, and are only used to override the automatic identity with externally managed material.
  • autoApply requires the Gateway to have agent.applyHelperPath set (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.env and the Caddyfile are 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/controller and the database in place. The front door (the separate janus-caddy package), 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.