girlbossrush/authentik-agent-marketplace/dev-environment

authentik dev environment

Purpose

A working authentik checkout needs several moving parts before anything runs: language toolchains, dependency installs, a database and Redis, local configuration, a migrated schema, and a built web UI. This skill walks a contributor from a fresh clone to a running stack, and gets a broken environment back to a known-good state.

When to invoke

• "Set up my local authentik development environment."
• "I just cloned authentik — how do I get it running?"
• "My dependencies / database / Redis won't come up."
• "How do I create the first admin user locally?"
• "Reset my local environment to a clean state."

Not this skill: running an individual server once the environment exists (backend, frontend, docs) or running migrations as a routine task (backend).

Common workflows

Steps are tagged by what you're doing: [shell] run a command, [verify] confirm it worked, [docs] read the developer docs. Commands run from the repo root unless noted.

From a fresh clone to first login

Result: authentik running locally at http://localhost:9000 with an admin you can sign in as.

1. [shell] Install the prerequisites: Python 3.14, uv, Node 24+, Go 1.26+, Docker and

Docker Compose, plus the platform libraries (macOS: libxmlsec1, libpq, krb5 via Homebrew; Debian: the krb5 / xmlsec / postgresql-server-dev packages).

1. [shell] Bring up the supporting services and install dependencies:

`` docker compose -f scripts/compose.yml up -d # PostgreSQL and friends make install # backend + web dependencies make gen-dev-config # local dev config make migrate # initialize the database make web-build # build the web UI (needed before it renders) ``

1. [shell] Start the stack: make run (server + worker, via uv run ak allinone).
2. [verify] Open http://localhost:9000 and set the password for the akadmin user.
3. [docs] website/docs/developer-docs/setup/full-dev-environment.mdx for the full

prerequisite list and platform notes.

Gotchas: make web-build is required before the UI renders; if esbuild / chromedriver fail to install (npm install-scripts are disabled by default for security), run npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json; the first run takes a moment to drain the task queue. Verify: the login page loads and you can sign in as akadmin.

Reset a broken environment to a clean state

Result: a fresh database and a known-good stack.

1. [shell] Reset the database: make dev-reset (drops, recreates, and migrates the

dev database).

1. [shell] If dependencies have drifted, re-run make install and make web-build.
2. [shell] Start again with make run.

Gotchas: make dev-reset is destructive (it drops the dev database) and is dev-only; always run migrations after pulling new commits, or you hit ImproperlyConfigured. Verify: make run comes up and you can log in.