Environment Variables

Koios is configured through environment variables passed to the Docker container. Most deployments work with the defaults, but you can customize network ports, performance tuning, logging, authentication, and reverse proxy settings.

Setting Environment Variables

Add -e flags to the docker run command in your systemd service file:

ExecStart=/usr/bin/docker run --rm --name=%n --network host \
  -e ENABLE_TLS=true \
  -e HTTPS_PORT=8443 \
  -e LOG_STDOUT_ENABLED=true \
  --mount source=koios_data_postgres,target=/var/lib/postgresql/16/main \
  --mount source=koios_data_influxdb,target=/root/.influxdbv2 \
  --mount source=koios_media,target=/var/www/koios/media \
  --mount source=koios_logs,target=/var/www/koios/logs \
  --mount source=koios_certs,target=/var/www/koios/certs \
  --mount source=koios_license,target=/var/www/koios/license \
  --mount source=koios_secrets,target=/var/www/koios/secrets \
  aiopinc/koios:latest

After editing the service file, reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart docker.koios.service

Network & TLS

Control how Koios handles HTTPS, HTTP, and port assignments.

Variable	Default	Description
`ENABLE_TLS`	`true`	When `true`, Koios serves HTTPS and redirects HTTP to HTTPS. A built-in self-signed certificate is served until you install your own — see HTTPS Certificate below. Set to `false` when running behind a load balancer or reverse proxy that handles TLS termination.
`HTTPS_PORT`	`443`	The port for HTTPS traffic. Only used when `ENABLE_TLS=true`.
`KOIOS_TLS_SAN`	(empty)	Extra names the built-in certificate should cover, comma-separated — for example `koios.plant.local,10.0.4.20`. Koios already covers the addresses it can detect; set this when users reach Koios by a name it cannot see, such as a DNS alias. Only affects the built-in certificate, and changing it regenerates that certificate on the next restart.
`HTTP_PORT`	`80`	The port for HTTP traffic. In TLS mode, this port redirects to HTTPS. In no-TLS mode, this is the primary listening port.

Common Scenarios

Standard deployment (default): No variables needed. Koios listens on ports 443 (HTTPS) and 80 (HTTP redirect).

Custom ports:

-e HTTPS_PORT=8443 \
-e HTTP_PORT=8080 \

Behind a TLS-terminating proxy (e.g., NGINX, HAProxy, AWS ALB):

-e ENABLE_TLS=false \
-e HTTP_PORT=8080 \

Koios serves plain HTTP on port 8080. The proxy handles HTTPS and forwards traffic to this port.

Port mapping with host networking

When using --network host, the container binds directly to the host's ports. Make sure your chosen ports are not already in use. If using explicit port mapping instead (e.g., -p 8443:443), the port variables control the ports inside the container.

HTTPS Certificate

Koios chooses the certificate it serves on the HTTPS port in this order:

A certificate you place on the certificates volume at certs/https/custom/.
A certificate uploaded in the web interface at System > Certificates. See Certificates.
The built-in self-signed certificate, used when neither of the above is present or valid.

To install a CA-signed certificate at deploy time, place these files in custom/ before starting the container:

/var/www/koios/certs/https/custom/koios.crt    certificate
/var/www/koios/certs/https/custom/koios.key    private key (must not be passphrase-protected)
/var/www/koios/certs/https/custom/chain.crt    intermediate chain (optional)

Koios revalidates the pair on every boot. A certificate that is unreadable, does not match its key, or is protected by a passphrase is rejected and Koios falls back to the self-signed certificate, so a bad certificate never locks you out of the interface you would use to fix it.

A certificate on disk locks the in-app page

While a valid certificate is present in custom/, it outranks anything uploaded through System > Certificates, and the upload form there is disabled. Remove the files and restart to hand control back to the web interface.

Performance Tuning

Adjust worker threads and timeouts for your deployment size.

Variable	Default	Description
`UVICORN_WORKERS`	CPU count (max 4)	Number of web server worker processes. Increase for deployments with many concurrent API clients.
`DC_THREAD_POOL_SIZE`	`8`	Number of worker threads for device polling. Increase for deployments with many devices to improve polling concurrency.
`PE_THREAD_POOL_SIZE`	`8`	Number of worker threads for AI model inference. Increase for deployments running many models concurrently.
`PE_GROUP_THREAD_POOL_SIZE`	`32`	Maximum threads for parallel model inference within a scan group. When a scan group fires, all its models can run concurrently up to this limit.
`EE_THREAD_POOL_SIZE`	`8`	Number of worker threads for expression evaluation. Increase for deployments with many calculated tags (expressions).
`EE_IN_MEMORY_HEARTBEAT_INTERVAL`	`60`	Safety-net poll interval (in seconds) for in-memory tag sources feeding expression tags and AI models. The Expression Evaluator now reacts to live in-memory updates via push events; this heartbeat is purely a fallback to detect a stale producer. Lower it only if you suspect a producer is silently failing to publish. The legacy `EE_IN_MEMORY_SCAN_RATE` variable is still honored for backward compatibility.
`KOIOS_DB_POOL_SIZE`	`10`	Connections each background service keeps open to the configuration database.
`KOIOS_DB_MAX_OVERFLOW`	`20`	Extra connections a service may open beyond the pool size during bursts.

When to increase thread pools

The default thread pool sizes work well for most deployments (up to ~50 devices, ~50 models, or ~50 expressions). If you have significantly more, increase the corresponding pool size. Monitor CPU usage on the System > Health page. If the server has spare capacity but polling, inference, or expression evaluation feels slow, increasing the pool may help.

Stacks multiply database connections

Components running inside a stack execute in a worker process of their own — one process per stack in use, each opening its own pool. Total connections to the configuration database therefore scale with the number of stacks, not the number of component environments: several environments attached to one stack share a single worker and a single pool. Account for that before raising KOIOS_DB_POOL_SIZE on an install that uses several stacks.

Authentication

Control JWT token lifetimes for user sessions.

Variable	Default	Description
`KOIOS_ACCESS_TOKEN_LIFETIME_SECONDS`	`3600`	How long an access token remains valid (in seconds). Default is 1 hour. Shorter values improve security; longer values reduce re-authentication frequency.
`KOIOS_REFRESH_TOKEN_LIFETIME_DAYS`	`7`	How long a refresh token remains valid (in days). This determines the maximum session duration before a user must log in again.

Logging

Control log output destination, format, and verbosity.

Variable	Default	Description
`LOG_STDOUT_ENABLED`	`false`	When `true`, streams all service logs to container stdout, making them visible via `docker logs`. When `false`, logs are written to files inside the container's log volume and viewable from the in-app log viewer.
`KOIOS_DEFAULT_LOG_LEVEL`	`INFO`	Log verbosity for all Koios services. Options: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
`KOIOS_LOG_MAX_BYTES`	`10485760`	Size a per-device, per-model, or per-scan-group log file reaches before it rotates. Default is 10 MiB.
`KOIOS_LOG_BACKUP_COUNT`	`5`	How many rotated copies of each of those log files are kept.
`KOIOS_LIBRARY_LOG_LEVELS`	(none)	Comma-separated `library=LEVEL` overrides for third-party libraries, e.g. `asyncua=DEBUG,zeep=INFO`.

Koios holds third-party libraries at Warning, and the Modbus client at Error, so that raising a device or service to Debug returns Koios detail rather than a packet-by-packet protocol trace. KOIOS_LIBRARY_LOG_LEVELS is the only way to lift that ceiling — set it while you are diagnosing a problem, and expect the resulting logs to be large.

Capturing an overnight trace

A busy device left at Debug fills the default log ring in under two hours. Raise KOIOS_LOG_MAX_BYTES and KOIOS_LOG_BACKUP_COUNT before starting a long capture so the ring doesn't wrap past the event you're chasing, then return them to their defaults — the sizes apply to every device, model, and scan group.

In-app log viewer

Regardless of these settings, service logs are always available in the in-app log viewer at System > Service Logs. The LOG_STDOUT_ENABLED variable controls whether logs are also sent to container stdout.

Log Forwarding (OpenTelemetry)

Forward logs, metrics, and traces from Koios to an external observability platform using the built-in OpenTelemetry Collector.

Variable	Default	Description
`OTEL_COLLECTOR_ENABLED`	`false`	When `true`, starts the OpenTelemetry Collector inside the container.
`OTEL_REMOTE_ENDPOINT`	(none)	The remote OTLP HTTP endpoint URL (e.g., `https://your-collector:4318`). Required when the collector is enabled.
`OTEL_REMOTE_AUTH_TOKEN`	(none)	Bearer token for authenticating to the remote endpoint.

Example: Forwarding to Grafana Cloud

-e OTEL_COLLECTOR_ENABLED=true \
-e OTEL_REMOTE_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp \
-e OTEL_REMOTE_AUTH_TOKEN=your-grafana-cloud-token \

OPC-UA Configuration

Variable	Default	Description
`OPCUA_CERT_HOSTNAME`	System hostname	The hostname embedded in the OPC-UA client's application URI and used when generating client certificates. Override this if the system hostname doesn't match what your OPC-UA servers expect for certificate validation.

Device Access

For the rare case of attaching serial, GPIO, I2C, or SPI hardware directly to the host. Two steps are needed: expose the host device node with --device, and give the Koios services membership in the group that owns it, since device nodes are group-owned and the services run as an unprivileged user.

Variable	Default	Description
`KOIOS_EXTRA_GROUPS`	(none)	Comma-separated group names and/or numeric group IDs the Koios services should join, so they can reach host device nodes exposed with `--device`. Standard serial (`dialout`) is already included. Group ID `0` is refused; unresolvable entries are skipped.

Standard serial devices (the dialout group) work with no extra configuration. For GPIO, I2C, or SPI, whose group IDs vary between hosts, pass the numeric group ID. Find it with stat -c '%g' /dev/<node> on the host:

--device /dev/gpiochip0 \
-e KOIOS_EXTRA_GROUPS=998 \

Reverse Proxy Settings

Advanced configuration

These settings are only needed when Koios is deployed behind a reverse proxy (NGINX, Apache, HAProxy, AWS ALB, etc.) that handles TLS termination. For standalone deployments with ENABLE_TLS=true, the defaults work correctly.

When running behind a reverse proxy, you may need to configure CSRF protection and cookie settings so that the proxy's domain and protocol are trusted.

Sub-Path Hosting

Variable	Default	Description
`KOIOS_BASE_PATH`	`/`	Serve the Koios web interface under a reverse-proxy sub-path, for example `/wfwd/koios/`. The interface assets are rewritten to this base path when the container starts.

The proxy must strip the prefix

Koios serves at the root path inside the container. Configure the proxy to remove the sub-path prefix before forwarding, or every request arrives with a path Koios does not recognise.

CSRF Protection

Variable	Default	Description
`DJANGO_CSRF_TRUSTED_ORIGINS`	(empty)	Comma-separated list of trusted origins. Must be set when behind a proxy to match the browser's Origin header. Example: `https://koios.example.com,https://other.example.com`
`DJANGO_CSRF_COOKIE_SECURE`	`True`	Set to `False` if serving over plain HTTP (e.g., behind a proxy on a private network).
`DJANGO_CSRF_COOKIE_HTTPONLY`	`False`	Set to `True` to prevent JavaScript from reading the CSRF cookie.
`DJANGO_CSRF_COOKIE_DOMAIN`	(current domain)	Set to `.example.com` for cross-subdomain CSRF cookie sharing.
`DJANGO_CSRF_COOKIE_PATH`	`/`	URL path for the CSRF cookie.
`DJANGO_CSRF_COOKIE_SAMESITE`	(browser default)	SameSite attribute: `Lax`, `Strict`, or `None`.

Session Cookies

Variable	Default	Description
`DJANGO_SESSION_COOKIE_SECURE`	`True`	Set to `False` if serving over plain HTTP.
`DJANGO_SESSION_COOKIE_DOMAIN`	(current domain)	Domain for the session cookie.
`DJANGO_SESSION_COOKIE_PATH`	`/`	URL path for the session cookie.
`DJANGO_SESSION_COOKIE_SAMESITE`	`Lax`	SameSite attribute for the session cookie.

Proxy Headers

Variable	Default	Description
`DJANGO_USE_X_FORWARDED_HOST`	`True`	Use the `X-Forwarded-Host` header from the proxy to determine the request host.
`DJANGO_USE_X_FORWARDED_PORT`	`True`	Use the `X-Forwarded-Port` header from the proxy.
`DJANGO_SECURE_PROXY_SSL_HEADER`	`HTTP_X_FORWARDED_PROTO,https`	Header and expected value (comma-separated) used to detect HTTPS behind a proxy.
`DJANGO_SECURE_SSL_REDIRECT`	`False`	When `True`, the application redirects all HTTP requests to HTTPS. Usually `False` when the proxy handles redirection.

Example: Behind NGINX with Custom Domain

-e ENABLE_TLS=false \
-e HTTP_PORT=8080 \
-e DJANGO_CSRF_TRUSTED_ORIGINS=https://koios.example.com \
-e DJANGO_CSRF_COOKIE_SECURE=True \
-e DJANGO_SESSION_COOKIE_SECURE=True \

Debugging

These variables are intended for troubleshooting and should not be enabled in normal operation.

Variable	Default	Description
`DJANGO_DEBUG`	`False`	Enables verbose error pages with stack traces. Never enable in production. It exposes sensitive information.
`KOIOS_DB_QUERY_LOG`	(disabled)	Database query logging for the data collection and inference services. Set to `summary` for a periodic 60-second summary, or `verbose` for every individual query with timing. Useful for diagnosing slow queries.

What's Next

Running Koios as a Service: apply these variables in your systemd service file
Manually Starting Koios: pass variables to one-off docker run commands
Updating Koios: upgrade to a new version safely

If the Install Goes Wrong Manually Starting Koios