Simple or Full: choosing your authentication mode

Two settings, not three modes

auth.mode — set by the AUTHENTICATION_MODE environment variable — takes simple or full, and nothing else. It ships as simple, and the application carries predicates for exactly those two values.

Switching authentication off altogether is a separate setting that lives in a different file and a different section: site.authentication.enabled, set by AUTH_ENABLED. It is on unless you set it to false, and disabling it disables API authentication along with everything else. If your instance sits behind a VPN or a proxy that already authenticates people, that is the setting you want, and the mode stops mattering.

What the mode changes

Simple mode keeps accounts in the Valkey/Redis datastore your instance already runs for secrets. It adds no service and no file.

Full mode brings up the Rodauth-based authentication application, mounted at /auth, and stores accounts in a SQL database. The mode gate sits on the application itself: it skips loading entirely unless the mode is full, so in simple mode nothing it serves exists.

The full-mode database

AUTH_DATABASE_URL defaults to sqlite://data/auth.db, and the code falls back to that same value when the configuration is silent. PostgreSQL is a supported target, not a requirement — the shipped full stack runs SQLite.

That database is a single file, and the default path resolves inside the application directory — /app/data/auth.db in a container. It has to sit in a mounted volume directory. Written anywhere else it lives in the container’s own writable layer, so every account it holds is gone the moment the container is replaced. The full stack mounts the onetime_app_data named volume at /app/data on all three services that open the file: the app, the email worker and the scheduler. The simple stack has no /app/data mount at all, because simple mode stores nothing there — which is the one thing to fix if you run full mode on the simple stack.

If you point AUTH_DATABASE_URL at PostgreSQL on a bare-metal install, one step is yours rather than the installer’s: the Rodauth schema SQL has to be run against the database as a PostgreSQL superuser. The installer prints the exact command when it detects full mode, and says in the same breath that SQLite needs none of it.

RabbitMQ is a background-jobs decision, not an auth-mode one

Neither mode decides whether background jobs run. That is JOBS_ENABLED, which is off unless it is set to the literal string true, and turning it on is what makes a broker necessary — full mode on its own does not. Run as a service covers what the worker and the scheduler do, and when you need to start them at all.

Expect one misleading warning on the way: in full mode the installer tries to declare the job queues and warns, rather than fails, when RabbitMQ is not reachable. That warning is not evidence that full mode needs the broker.

What the project tests against

No minimum version of any backing service is declared anywhere in the project. The shipped full stack pins Valkey 8.1 and RabbitMQ 4.2 by digest and uses SQLite for the auth database; that is what the project builds and tests against, not a supported floor.

Deciding

The mode determines where accounts live, so decide it before the instance has accounts in it. Simple mode’s store is the datastore you are already operating. Full mode’s is a separate SQL database — a second store, not a second view of the first.

The two shipped Compose stacks are named after the mode each one defaults to, but the mode is a variable rather than a property of the stack: both files set AUTHENTICATION_MODE to their own name only as a default, and setting the variable overrides it either way. What a stack does fix is the set of services it brings up alongside the application.

Then install. Install with Docker covers the two Compose stacks, and Install on Linux covers a bare-metal install on Debian or Ubuntu. On both paths the mode comes from AUTHENTICATION_MODE in the environment the application boots with.