teyfix/ferriskey repository overview

⁠FerrisKey

teyfix/ferriskey packages the API, matching SQLx migrations and realm/client/provider provisioning. The shared outer Process Compose prepares typed configuration and SQL; the inner lifecycle runs migrations, starts the API, waits for native readiness, provisions resources and reconciles configured client secrets. Docker health includes completion of this chain. The API uses Process Compose’s native restart-on-failure policy, which also handles its signal exit during ordered shutdown; bootstrap jobs fail the container. PostgreSQL and the upstream webapp are separate services.

Mount YAML⁠ at /config/ferriskey.yaml (override FERRISKEY_CONFIG). The Compose example⁠ expects an existing PostgreSQL database and network. Supply native DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD, and the matching SQLx DATABASE_URL. For a dedicated schema, pre-create it with the database owner, set database_schema in YAML, and include its search_path in the SQLx URL. The API listens on port 3333 under /api; set SERVER_PUBLIC_URL and WEBAPP_URL to the consumer's public API origin and separately deployed upstream webapp.

ADMIN_USERNAME, ADMIN_EMAIL and ADMIN_PASSWORD are the native administrator bootstrap inputs. An existing admin password is not rotated by changing startup environment. DATABASE_URL_FILE, DATABASE_PASSWORD_FILE and ADMIN_PASSWORD_FILE use the shared file-secret resolver. Client/provider YAML supports {from_env: NAME} and {from_file: /run/secrets/name} through the common CUE resolver.

⁠Provisioning contract

realms is keyed by realm name. Each realm has optional clients and providers maps keyed by client ID and provider alias. Missing resources are created through the native API; existing resources are retained.

Clients support name, enabled, require_pkce (default true), direct_access_grants (false), redirects, logout_redirects, and an optional secret. Creation also supports public and service_account (both false); those creation properties cannot be changed through the upstream update API. Configured redirects are added if not already enabled. Unlisted redirects/clients/realms are not deleted. Provider settings update at each start; provider_id is a creation property. Native provider configuration values may be strings, booleans or secret references. Application authorization, user accounts, external provider registration and callback approval remain consumer-owned.

FerrisKey 0.9.0 exposes no API to assign a configured client secret. A small generated SQL file updates only explicitly declared secrets after API provisioning, using the native schema and safe SQL literal quoting. Omitting secret preserves the native generated/existing secret. Resolved configuration, API diagnostics and generated SQL remain private under /run/teyfix-ferriskey.

The image copies the unmodified API binary, SQLx and matching migrations from the official FerrisKey image. It does not compile or patch FerrisKey. Upstream and runtime image versions are selected in docker-bake.hcl. Authentication behavior belongs to upstream; external provider login is a consumer integration test.

⁠Logs and checks

The native API emits JSON by default (LOG_JSON=true). Process Compose writes it to /var/log/ferriskey/server.jsonl, configurable through paths.log, with collector-readable permissions. Mount it read-only into an external Vector collector. Database state remains in the consuming PostgreSQL service; this image has no database volume of its own.

docker buildx bake ferriskey-smoke runs native SQLx/API startup against disposable PostgreSQL and verifies retained-state provisioning, stable client identity, redirect/provider idempotence, configured secret rotation, logs and shutdown. CI runs on both published architectures. This does not migrate an existing consumer or verify its external OAuth provider registrations.

Maintained from the source documentation⁠. See published tags⁠ and the service integration guide⁠.