Accounts and Workspaces

Accounts and Workspaces

Available since Koffan 2.16.0. This page mirrors the README section, which is the reference.

Back up your database before upgrading to 2.16.0. The first start migrates the database whether or not you enable accounts, and there is no downgrade path. See Upgrading.

By default Koffan has one shared password and behaves exactly as before. Set MULTI_USER=true (exactly that value) to give every person their own login and to keep separate lists for several households on one server.

Turning accounts on

1. Back up your database file (see Upgrading).
2. Set MULTI_USER=true and your own APP_PASSWORD (at least 8 characters). Optionally set ADMIN_USER (default admin). If APP_PASSWORD is still the built-in default shopping123, the administrator gets that password and the log shows a warning: change it right after signing in (since 2.16.1; 2.16.0 refused to start).
3. Restart Koffan and look for Created administrator "admin" in the log. Everyone signed in with the shared password is signed out.
4. Sign in as the administrator and open Manage workspaces from the workspace menu in the header. Create an account for each person and keep Add to the current workspace ticked to put them in "Home", the default workspace that holds all your existing lists.

With Docker Compose, put the settings in a .env file next to the compose file:

MULTI_USER=true
APP_PASSWORD=choose-a-long-password
ADMIN_USER=admin

How it works

• A workspace is a group of lists, templates and autocomplete history shared by the people in it (a household, the in-laws, a parent), with a name and an icon. One person can belong to several workspaces and switch between them from the header.
• Everyone in a workspace sees its lists; people outside it cannot.
• Anyone signed in can create a workspace and becomes its owner. Owners rename it, change its icon, add and remove people, clear its data and delete it. Members use its lists and can leave it. "Home" cannot be deleted.
• Administrators create and delete accounts and set new passwords. They can also manage any workspace (rename it, delete it, add or remove people), even one they are not in, but they only see its lists after adding themselves to it, which shows them in its member list. The first administrator is created from ADMIN_USER and APP_PASSWORD; the last administrator cannot be deleted.
• There is no e-mail or self-service sign-up: an administrator creates the account and hands over the username and password. Usernames have up to 40 characters, no spaces or commas, and are not case-sensitive.
• Everyone can change their own password under Your account on the Workspaces page. The current password is required, wrong guesses count against the login rate limit, and the change signs you out on your other devices. A password set by an administrator (for someone who forgot theirs) signs that account out everywhere.
• Export, import and Clear database work on the current workspace only. Only its owners and administrators can clear it.
• Real-time updates only reach the people in the workspace that changed. Someone who is removed from a workspace, deleted, signed out or given a new password stops receiving them at once.
• APP_PASSWORD is only used to create the first administrator; changing it later changes no one's password. Keep it set anyway: if you turn accounts off again, it becomes the shared password again (without it, the built-in default shopping123 applies).
• Turning accounts off again brings back the shared password. Nothing is deleted, but only "Home" is reachable (the other workspaces return when you turn accounts on again), and account sessions stop working.
• DISABLE_AUTH=true (for example with forward-auth at a proxy) turns accounts off.

REST API and webhooks with accounts

• The REST API token works on one workspace, API_WORKSPACE_ID (default 1, "Home"). Anything in other workspaces behaves as if it did not exist. Find workspace ids with sqlite3 /path/to/shopping.db "SELECT id, name FROM workspaces;". While the API is enabled, that workspace cannot be deleted; if it is missing, the API answers 503.
• Outbound webhooks are not per workspace. WEBHOOK_URL receives the item events of every workspace, including list and section names, and the payload carries no workspace id. On an instance shared by several households, leave webhooks disabled unless everyone trusts the receiver.

Behind a reverse proxy

• Login rate limiting counts attempts per client IP, and Koffan does not read forwarded IP headers. Behind a reverse proxy all accounts therefore share one limit, and one person's wrong passwords can lock everyone out for LOGIN_LOCKOUT_MINUTES. Set LOGIN_MAX_ATTEMPTS=0 and limit login attempts at the proxy instead (see Login Rate Limiting).
• With accounts, Koffan refuses changes and live updates requested by pages from other origins. Over HTTPS the browser reports where a request comes from. Over plain HTTP, Koffan compares the request's Origin with its Host, so a proxy serving Koffan over plain HTTP must pass the original Host header or set X-Forwarded-Host. Caddy and Traefik do this by default; with nginx add proxy_set_header Host $host;.

Forgotten administrator password

With a second administrator, they can simply set a new password. If the only administrator forgot theirs:

1. Back up the database file and stop Koffan.
2. Delete all accounts: sqlite3 /path/to/shopping.db "PRAGMA foreign_keys=ON; DELETE FROM users;". For the Docker volume from the Quick Start: docker run --rm -v koffan-data:/data alpine sh -c 'apk add --no-cache sqlite >/dev/null && sqlite3 /data/shopping.db "PRAGMA foreign_keys=ON; DELETE FROM users;"'
3. Start Koffan again with MULTI_USER=true and a new APP_PASSWORD. The administrator is created again and owns "Home". All other accounts are removed as well, so create them again. Their workspaces and lists are kept: add yourself to each workspace as administrator and add the people back.

See also: REST API (workspace scoping), Webhooks, Multiple Instances.