From a8ecc9b530eb48e56f7a1ae409f95349316ee046 Mon Sep 17 00:00:00 2001 From: Connor Peshek Date: Tue, 26 Aug 2025 09:42:05 -0400 Subject: [PATCH] website/docs: Add steps for fixing xml python errors, clean up (#16223) --- Makefile | 19 ++++- .../setup/full-dev-environment.mdx | 31 +++++--- .../setup/website-dev-environment.md | 27 ------- .../setup/website-dev-environment.mdx | 79 +++++++++++++++++++ 4 files changed, 118 insertions(+), 38 deletions(-) delete mode 100644 website/docs/developer-docs/setup/website-dev-environment.md create mode 100644 website/docs/developer-docs/setup/website-dev-environment.mdx diff --git a/Makefile b/Makefile index 30d70fac68..528ad03a8d 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/website/docs/developer-docs/setup/full-dev-environment.mdx b/website/docs/developer-docs/setup/full-dev-environment.mdx index 9880c16233..d4fd21cbf5 100644 --- a/website/docs/developer-docs/setup/full-dev-environment.mdx +++ b/website/docs/developer-docs/setup/full-dev-environment.mdx @@ -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 - - + + 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 ``` @@ -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 diff --git a/website/docs/developer-docs/setup/website-dev-environment.md b/website/docs/developer-docs/setup/website-dev-environment.md deleted file mode 100644 index 9927447493..0000000000 --- a/website/docs/developer-docs/setup/website-dev-environment.md +++ /dev/null @@ -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. diff --git a/website/docs/developer-docs/setup/website-dev-environment.mdx b/website/docs/developer-docs/setup/website-dev-environment.mdx new file mode 100644 index 0000000000..5c07a6b649 --- /dev/null +++ b/website/docs/developer-docs/setup/website-dev-environment.mdx @@ -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 + + + + +Install the required dependencies on macOS using Homebrew: + +```shell +brew install node@24 +``` + + + + +[Download NodeJS version 24](https://nodejs.org/en/download/current) for your Linux distribution. + + + + +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. + + + + +## 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!