Controller configuration
The Controller reads a YAML file (default config.yaml in the image). Set CONFIG_PATH to mount a custom file. Environment variables override YAML keys at runtime (containers, Helm, systemd).
Controller v3.8.0 ships a new schema. There is no v3.7 → v3.8 database migrator. Install with an empty SQLite file or a new MySQL/PostgreSQL database. See Migrating to v3.8.0.
Main YAML sections
app:
name: iofog
controlPlane: Remote # Remote | Kubernetes | Local
namespace: iofog
server:
port: 51121
publicUrl: "https://controller.example.com:51121" # CONTROLLER_PUBLIC_URL
trustProxy: false # TRUST_PROXY
# tls:
# path:
# key: ""
# cert: ""
# intermediateCert: ""
console:
port: 8008
url: "https://console.example.com:8008" # CONSOLE_URL
auth:
mode: embedded # embedded | external - AUTH_MODE
insecureAllowHttp: false
bootstrap:
username: "" # OIDC_BOOTSTRAP_ADMIN_USERNAME (embedded first boot)
password: "" # OIDC_BOOTSTRAP_ADMIN_PASSWORD
# issuerUrl: "" # OIDC_ISSUER_URL - required in external mode
# client:
# id: "" # OIDC_CLIENT_ID
# secret: "" # OIDC_CLIENT_SECRET
# consoleClient: "" # OIDC_CONSOLE_CLIENT_ID
database:
provider: sqlite # sqlite | mysql | postgres
sqlite:
databaseName: controller_db.sqlite
pragmas:
journalMode: WAL
busyTimeoutMs: 10000
nats:
enabled: true
systemImages:
router:
"1": "<router-image-amd64>"
"2": "<router-image-arm64>"
# keys 3–4: riscv64, arm - see defaults in Controller config.yaml
debug:
"1": "<debugger-image>"
nats:
"1": "<nats-image>"
Default image refs use your build flavor registry (ghcr.io/datasance). Override per arch with ROUTER_IMAGE_1 … ROUTER_IMAGE_4, NATS_IMAGE_*, and DEBUG_IMAGE_* env vars.
v3.8 renames in config
| Removed (v3.7) | v3.8 |
|---|---|
viewer.port, viewer.url | console.port, console.url |
server.ssl.* | server.tls.* |
auth.realm, auth.url, KC_* | auth.mode, OIDC_*, AUTH_* |
diagnostics section | Removed (diagnostics APIs removed) |
EdgeOps Console reads consoleUrl from runtime controller-config.js (not viewerUrl). Details: EdgeOps Console configuration.
Authentication and Console environment variables
These variables are the primary knobs for auth and Console wiring. Full auth setup: Embedded OIDC (default) and External OIDC (optional appendix).
| Environment variable | Config key | Description |
|---|---|---|
AUTH_MODE | auth.mode | embedded (default) or external |
OIDC_ISSUER_URL | auth.issuerUrl | Full issuer URL. Required in external mode. In embedded mode the issuer is {CONTROLLER_PUBLIC_URL}/oidc |
OIDC_CLIENT_ID | auth.client.id | OAuth client for Controller API / BFF |
OIDC_CLIENT_SECRET | auth.client.secret | Client secret |
OIDC_CONSOLE_CLIENT_ID | auth.consoleClient | EdgeOps Console SPA client ID |
AUTH_CONSOLE_CLIENT_ENABLED | auth.consoleClient.enabled | Enable Console OAuth client |
OIDC_BOOTSTRAP_ADMIN_USERNAME | auth.bootstrap.username | First admin user (embedded first boot) |
OIDC_BOOTSTRAP_ADMIN_PASSWORD | auth.bootstrap.password | Bootstrap admin password |
AUTH_INSECURE_ALLOW_HTTP | auth.insecureAllowHttp | Allow http:// in CONTROLLER_PUBLIC_URL (dev only) |
AUTH_SESSION_STORE_TYPE | auth.sessionStore.type | memory or database (HA BFF sessions) |
AUTH_SESSION_SECRET | auth.sessionStore.secret | BFF session encryption secret |
CONSOLE_PORT | console.port | EdgeOps Console listen port (default 8008) |
CONSOLE_URL | console.url | Public Console URL for OAuth redirects |
TLS environment variables
v3.8 renamed SSL_* to TLS_*. Listener certificates are also used for agent trust (caCert on provision) and embedded OAuth token exchange.
| Environment variable | Config key | Description |
|---|---|---|
TLS_PATH_KEY | server.tls.path.key | Path to TLS private key |
TLS_PATH_CERT | server.tls.path.cert | Path to TLS certificate |
TLS_PATH_INTERMEDIATE_CERT | server.tls.path.intermediateCert | Intermediate / chain certificate |
TLS_BASE64_KEY | server.tls.base64.key | Base64-encoded key (alternative to path) |
TLS_BASE64_CERT | server.tls.base64.cert | Base64-encoded certificate |
TLS_BASE64_INTERMEDIATE_CERT | server.tls.base64.intermediateCert | Base64-encoded intermediate cert |
CONTROLLER_PUBLIC_URL | server.publicUrl | Canonical external HTTPS URL (required for embedded OAuth) |
TRUST_PROXY | server.trustProxy | Honor X-Forwarded-* behind reverse proxy |
Other common environment variables
| Environment variable | Config key | Description |
|---|---|---|
CONFIG_PATH | - | Path to YAML config file |
SERVER_PORT | server.port | REST API port (default 51121) |
SERVER_DEV_MODE | server.devMode | Developer mode |
CONTROLLER_NAMESPACE | app.namespace | Kubernetes / RBAC namespace |
CONTROL_PLANE | app.controlPlane | Remote, Kubernetes, or Local |
DB_PROVIDER | database.provider | sqlite, mysql, or postgres |
DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_NAME | database.* | Provider-specific connection |
DB_USE_SSL, DB_SSL_CA | database.*.useSSL, sslCA | Database TLS |
NATS_ENABLED | nats.enabled | Platform NATS relay and hub features |
LOG_LEVEL | log.level | Log level |
WS_EXEC_MAX_CONCURRENT_PER_RESOURCE | server.webSocket.session.execMaxConcurrentPerResource | Exec sessions per microservice (default 5) |
Boolean env vars (TRUST_PROXY, SERVER_DEV_MODE, DB_USE_SSL, NATS_ENABLED, and others) accept true/false or 1/0 from Kubernetes string values.
The full mapping lives in the Controller repo: src/config/env-mapping.js.
Control plane deployment
When you deploy with potctl or the Operator, many values come from Control Plane YAML (auth, database, controller blocks) instead of hand-editing config.yaml. See Control Plane YAML and Platform Deployment.