Rauthy on Cloudron

Cloudron package for Rauthy, a lightweight OpenID Connect / OAuth 2.0 Single Sign-On Identity & Access Management server written in Rust.

Upstream version: 0.37.2

How this package is built

Rauthy does not publish standalone binary releases, only multi-arch container images, so the build is multi-stage:

1. ghcr.io/sebadob/rauthy:<version> - the server binary is taken from the official image (/app/rauthy).
2. tcmbp132021/cloudron-minibase:ubuntu26.04 - the Cloudron runtime. The binary is a dynamically linked glibc build (distroless cc-debian12), which the Ubuntu base satisfies, so no build toolchain is needed in the image.

The static, non-secret part of Rauthy's configuration is shipped as config.toml in /app/code (read-only). Everything environment dependent is supplied as environment variables by start.sh - from the Cloudron environment, from the editable /app/data/env.sh, and from the generated /app/data/secrets.env. Rauthy gives environment variables precedence over the TOML values on every start.

Runtime layout

Path	Access	Content
/app/code/config.toml	read-only	static configuration defaults
/app/code/rauthy	read-only	Rauthy server binary
/app/code/defaults/env.sh	read-only	template for the editable configuration
/app/data/env.sh	read-write	editable runtime configuration (mode 600)
/app/data/hiqlite	read-write	embedded Hiqlite database (SQLite + Raft)
/app/data/bootstrap	read-write	bootstrap admin state and generated secrets
/app/data/secrets.env	read-write	generated Hiqlite + encryption keys (mode 600)

/app/data is the only persistent location and is included in Cloudron backups.

Addons used

• localstorage (mandatory) - provides /app/data.
• sendmail - outgoing mail only. The port is taken from the addon variable that matches the selected TLS mode (CLOUDRON_MAIL_STARTTLS_PORT for starttls, CLOUDRON_MAIL_SMTPS_PORT for tls, CLOUDRON_MAIL_SMTP_PORT for danger-insecure), so it is never hardcoded.

Cloudron's proxy authentication is deliberately not used. Rauthy is an identity provider: its discovery document, all OIDC endpoints and its own login page must remain reachable without a Cloudron login. Admin access is gated by Rauthy itself - the rauthy_admin role, enforced on the admin UI and the admin API, with MFA required on admin accounts (admin_force_mfa, default on). Because Rauthy's admin API endpoints (/auth/v1/users, /auth/v1/clients, ...) are siblings of the /auth/v1/admin pages rather than children of them, a Cloudron wall on the pages would add no protection where the data actually is.

Configuration

Cloudron has no per-app environment variable editor, so every setting lives in a single file:

/app/data/env.sh

start.sh creates it from /app/code/defaults/env.sh on the first start, then loads and exports it on every start and restart. Because /app/data is persistent, the file survives restarts, updates and backup/restore, and an existing file is never overwritten - edits are yours to keep.

The Cloudron derived values are applied before the file is read, so anything defined in env.sh takes precedence, while a setting removed from the file still falls back to a working default.

Variable	Default	Purpose
PUB_URL	CLOUDRON_APP_DOMAIN	public host name
LISTEN_ADDRESS, LISTEN_PORT_HTTP, LISTEN_SCHEME	0.0.0.0, 3000, http	listen address; the port must match httpPort in the manifest
PROXY_MODE, TRUSTED_PROXIES	true, Cloudron proxy network	trust the reverse proxy's X-Forwarded-* headers
RP_ID, RP_ORIGIN, RP_NAME	app domain, https://<domain>:443, Rauthy	WebAuthn relying party; changing RP_ID invalidates registered passkeys
WEBAUTHN_PASSKEY_REG_TYPE	resident_key	make the Account UI default to discoverable passkeys that work well with platform authenticators
BOOTSTRAP_ADMIN_EMAIL	admin@<app domain>	e-mail address of the bootstrap admin
HTTP_WORKERS	4	worker threads (Rauthy cannot see the container memory limit)
SMTP_TLS_MODE	starttls	selects starttls, tls or danger-insecure, and with it the addon port variable used
SMTP_URL, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD	Cloudron sendmail addon	override to use an external SMTP relay
SMTP_FROM, RAUTHY_ADMIN_EMAIL	Cloudron mail sender	sender address for outgoing mail
SMTP_ROOT_CA	unset	PEM root CA for mail servers with a self-signed certificate

Any other Rauthy option can be set the same way using its documented environment variable name, for example METRICS_ENABLE, SESSION_LIFETIME or EMAIL_SUB_PREFIX.

The static keys shipped in config.toml can only be extended with keys that exist in the pinned Rauthy version - Rauthy refuses to start on unknown configuration keys.

Secrets

start.sh generates the Raft/API cluster secrets and the encryption key on the first start and stores them in /app/data/secrets.env. They are required to decrypt the database content and must be preserved across restores. Losing that file makes the data unrecoverable.

License

The upstream application is licensed under the Apache License 2.0 - see LICENSE.

---

Packaged by @timconsidine https://communityapps.appx.uk (full portfolio: https://myca.appx.uk)