Thymis Documentation

On this page

OCI-Container / Docker

Run the Thymis Controller in a Docker/OCI container on x86_64 hosts.

Important: The container can build and serve x86_64 (x64) device configurations only. Raspberry Pi/ARM (aarch64) image builds are not supported due to cross compiling issues inside the container.

If you already use Nix, you can also run the Controller with nix run.

Image

Quick start

docker run -d 
  --name thymis-controller 
  -p 8000:8000 
  -e UVICORN_HOST=0.0.0.0 
  -e THYMIS_BASE_URL=http://localhost 
  -e THYMIS_AGENT_ACCESS_URL=http://localhost:8000 
  -v /var/lib/thymis:/var/lib/thymis 
  --restart unless-stopped 
  ghcr.io/thymis-io/thymis-controller:latest

Access the UI at: http://localhost:8000 (or behind your HTTPS proxy).

Login with the default user admin and the password at /var/lib/thymis/auth-basic-password (adjust if needed)

Persistent state

Mount host storage to keep the repo, DB, images, and keys:

  • -v /var/lib/thymis:/var/lib/thymis

Ensure the directory is writable by the container.

Configuration (env vars)

NixOS module defaults do not apply in Docker, pass what you need explicitly:

  • THYMIS_BASE_URL: public URL for users/UI (e.g. https://thymis.example.com).
  • THYMIS_AGENT_ACCESS_URL: URL devices use to connect (often same as BASE_URL).
  • THYMIS_PROJECT_PATH: data dir in container (use /var/lib/thymis).
  • THYMIS_AUTH_BASIC: true|false to enable/disable built‑in basic auth.
  • THYMIS_AUTH_BASIC_USERNAME: username for basic auth (if enabled).
  • THYMIS_AUTH_BASIC_PASSWORD_FILE: path in container to a password file; mount it.
  • UVICORN_HOST: bind address; use 0.0.0.0 in containers.
  • UVICORN_PORT: internal port (default 8000); map a host port accordingly.

Example with basic auth:

-e THYMIS_AUTH_BASIC=true 
-e THYMIS_AUTH_BASIC_USERNAME=admin 
-e THYMIS_AUTH_BASIC_PASSWORD_FILE=/var/lib/thymis/auth-basic-password

Reverse proxy (optional)

For public exposure and TLS, terminate HTTPS on your existing reverse proxy (Nginx/Traefik) and forward to the container on port 8000.

Limitations

  • x86_64 builds only; no Raspberry Pi/ARM builds from the container.
  • For ARM targets use the NixOS-based setup instead.

Troubleshooting

  • View logs: docker logs -f thymis-controller
  • Verify /var/lib/thymis is mounted and writable
  • If a build targets non‑x86, switch to the NixOS install

Containers on devices

If your goal is to run Docker/OCI containers on the devices managed by Thymis (not to containerize the Controller itself), use the built‑in OCI‑Containers module. This page only covers running the Controller in a container.

See also

ende