eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/how-to/authentik/authentik-web-ui-derivation.md
Erich Blume 7094ea7d3e Start C2 Mikado chain: build authentik from source 
Create goal card and 4 prerequisite cards for building authentik from a
custom Nix derivation instead of using pkgs.authentik from nixpkgs. This
removes the dependency on the nixpkgs packaging timeline and gives full
version control over authentik releases.

Chain: mikado/authentik-source-build
Leaf nodes: authentik-api-client-generation, authentik-python-backend-derivation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 08:20:17 -08:00

1.8 KiB
Raw Blame History

title modified status requires tags
Build Authentik Web UI 2026-02-28 active
authentik-api-client-generation
how-to
authentik
nix

Build Authentik Web UI

Build the Lit-based TypeScript web frontend for authentik.

Context

The web UI lives in web/ in the authentik repo. It's built with Rollup and uses Lit web components. The nixpkgs derivation builds this in two phases:

  1. webui-deps — Fixed-output derivation that runs npm ci to fetch Node dependencies. Uses platform-specific output hashes (aarch64-linux vs x86_64-linux).
  2. webui — Patches in the generated TypeScript API client (client-ts), then runs npm run build. Output includes dist/ and authentik/ static directories.

There's also a website derivation (Docusaurus-based API docs at website/) that produces the /help endpoint. This is optional but included in the nixpkgs build.

What to Do

  1. Create a fixed-output derivation for npm ci in web/ (platform-specific hashes)
  2. Patch the generated TypeScript client into web/node_modules/@goauthentik/api/
  3. Build with npm run build — produces dist/ and authentik/ directories
  4. Optionally build the Docusaurus website (website/) for the /help endpoint
  5. Verify: static assets exist and reference correct paths

Key Details

  • Build tool: Rollup (via npm scripts)
  • Node.js version: nodejs_24 in current nixpkgs (check upstream requirements)
  • The TypeScript API client must be patched in before the build
  • Fixed-output hashes break on any npm dependency change — will need updating per release
  • Output is consumed by both authentik-django (email templates) and the Go server (static serving)

Related