website/docs: Add steps for fixing xml python errors, clean up (#16223)

2026-06-17 19:09:11 +03:00 · 2025-08-26 09:42:05 -04:00
parent 197f4c5585
commit a8ecc9b530
4 changed files with 118 additions and 38 deletions
@@ -18,7 +18,17 @@ pg_host := $(shell uv run python -m authentik.lib.config postgresql.host 2>/dev/
 pg_name := $(shell uv run python -m authentik.lib.config postgresql.name 2>/dev/null)
 redis_db := $(shell uv run python -m authentik.lib.config redis.db 2>/dev/null)

-all: lint-fix lint test gen web  ## Lint, build, and test everything
+UNAME := $(shell uname)
+
+## For macOS users, add the libxml2 and libxmlsec1 installed from brew to the build path
+## to prevent SAML-related tests from failing and ensure correct compilation
+ifeq ($(UNAME), Darwin)
+BREW_LDFLAGS := -L$(shell brew --prefix libxml2)/lib $(LDFLAGS)
+BREW_CPPFLAGS := -I$(shell brew --prefix libxml2)/include $(CPPFLAGS)
+BREW_PKG_CONFIG_PATH := $(shell brew --prefix libxml2)/lib/pkgconfig:$(PKG_CONFIG_PATH)
+endif
+
+all: lint-fix lint gen web test  ## Lint, build, and test everything

 HELP_WIDTH := $(shell grep -h '^[a-z][^ ]*:.*\#\#' $(MAKEFILE_LIST) 2>/dev/null | \
 	cut -d':' -f1 | awk '{printf "%d\n", length}' | sort -rn | head -1)
@@ -50,7 +60,14 @@ lint: ## Lint the python and golang sources
 	golangci-lint run -v

 core-install:
+ifeq ($(UNAME), Darwin)
+	# Clear cache to ensure fresh compilation
+	uv cache clean
+	# Force compilation from source for lxml and xmlsec with correct environment
+	LDFLAGS="$(BREW_LDFLAGS)" CPPFLAGS="$(BREW_CPPFLAGS)" PKG_CONFIG_PATH="$(BREW_PKG_CONFIG_PATH)" uv sync --frozen --reinstall-package lxml --reinstall-package xmlsec --no-binary-package lxml --no-binary-package xmlsec
+else
 	uv sync --frozen
+endif

 migrate: ## Run the Authentik Django server's migrations
 	uv run python -m lifecycle.migrate
@@ -9,7 +9,6 @@ tags:
    - docker
 ---

-import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
 import TabItem from "@theme/TabItem";
 import Tabs from "@theme/Tabs";

@@ -24,6 +23,7 @@ Before you begin, ensure you have the following tools installed:
 - [PostgreSQL](https://www.postgresql.org/) (16 or later)
 - [Docker](https://www.docker.com/) (Latest Community Edition or Docker Desktop)
 - [Docker Compose](https://docs.docker.com/compose/) (Compose v2)
+- [Make](https://www.gnu.org/software/make/) (3 or later)

 ## 1. Setting Up Required Services

@@ -52,8 +52,8 @@ If using locally installed databases, ensure the PostgreSQL credentials provided

 ## 2. Installing Platform-Specific Dependencies

-<Tabs defaultValue="Mac">
-<TabItem value="Mac">
+<Tabs defaultValue="macOS">
+<TabItem value="macOS">

 Install the required native dependencies on macOS using Homebrew:

@@ -61,13 +61,13 @@ Install the required native dependencies on macOS using Homebrew:
 brew install \
 libxmlsec1 \
 libpq \
-krb5 \
 pkg-config \
 uv \
 postgresql \
 redis \
 node@24 \
-golangci-lint
+golangci-lint \
+krb5
 ```

 </TabItem>
@@ -76,7 +76,7 @@ golangci-lint
 For Debian/Ubuntu-based distributions:

 ```shell
-pip install uv && \
+pip install uv
 sudo apt-get install -y \
 libgss-dev \
 krb5-config \
@@ -182,13 +182,13 @@ Now that the backend and frontend have been set up and built, you can start auth
 Start the server by running the following command in the same directory as your local authentik git repository:

 ```shell
-make run-server   # Starts authentik server
+make run-server
 ```

 Start the worker by running the following command in the same directory as your local authentik git repository:

 ```shell
-make run-worker   # Starts authentik worker
+make run-worker
 ```

 Both processes need to run to get a fully functioning authentik development environment.
@@ -214,7 +214,11 @@ When `AUTHENTIK_DEBUG` is set to `true` (the default for the development environ

 ## End-to-End (E2E) Setup

-To run E2E tests, navigate to the `/tests/e2e` directory in your local copy of the authentik git repo, and start the services by running `docker compose up -d`.
+Start the E2E test services with the following command:
+
+```shell
+docker compose -f tests/e2e/docker-compose.yml up -d
+```

 You can then view the Selenium Chrome browser via http://localhost:7900/ using the password: `secret`.

@@ -233,6 +237,7 @@ Ensure your code meets our quality standards by running:
 1. **Code linting**:

    ```shell
+    make lint-fix
    make lint
    ```

@@ -248,10 +253,16 @@ Ensure your code meets our quality standards by running:
    make web
    ```

+4. **Run tests**:
+
+    ```shell
+    make test
+    ```
+
 You can run all these checks at once with:

 ```shell
-make lint gen web
+make all
 ```

 ### Submitting your changes
@@ -1,27 +0,0 @@
---
-title: Docs development environment
-sidebar_label: Docs development
-tags:
-    - development
-    - contributor
-    - docs
-    - docusaurus
---
-
-If you want to only make changes to the documentation, you only need Node.js.
-
-### Prerequisites
-
- Node.js (any recent version should work; we use 24.x to build)
- Make (again, any recent version should work)
-
-:::info
-Depending on platform, some native dependencies might be required. On macOS, run `brew install node@24`
-:::
-
-### Instructions
-
-1. Clone the git repo from https://github.com/goauthentik/authentik
-2. Run `make docs-install` to install the docs development dependencies
-3. Run `make docs-watch` to start a development server to see and preview your changes
-4. Finally when you're about to commit your changes, run `make docs` to run the linter and auto-formatter.
@@ -0,0 +1,79 @@
+---
+title: Docs development environment
+sidebar_label: Docs development
+tags:
+    - development
+    - contributor
+    - docs
+    - docusaurus
+---
+
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+
+If you want to only make changes to the documentation, you only need Node.js.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en) (24 or later)
+- [Make](https://www.gnu.org/software/make/) (3 or later)
+
+## 1. Install dependencies
+
+<Tabs defaultValue="macOS">
+<TabItem value="macOS">
+
+Install the required dependencies on macOS using Homebrew:
+
+```shell
+brew install node@24
+```
+
+</TabItem>
+<TabItem value="Linux">
+
+[Download NodeJS version 24](https://nodejs.org/en/download/current) for your Linux distribution.
+
+</TabItem>
+<TabItem value="Windows">
+
+We're currently seeking community input on running the docs in Windows. If you have experience with this setup, please consider contributing to this documentation.
+
+</TabItem>
+</Tabs>
+
+## 2. Instructions
+
+Clone the repo:
+
+```shell
+git clone https://github.com/goauthentik/authentik
+```
+
+Install the docs dev dependencies:
+
+```shell
+make docs-install
+```
+
+Start the development server:
+
+```shell
+make docs-watch
+```
+
+Run the linter and auto-formatter to prepare your changes to commit:
+
+```shell
+make docs
+```
+
+## 3. Submitting your changes
+
+Once your changes pass all checks, you can submit a pull request through [GitHub](https://github.com/goauthentik/authentik/pulls). Be sure to:
+
+- Provide a clear description of your changes
+- Reference any related issues
+- Follow our code style guidelines
+
+Thank you for contributing to authentik!