web : Use query parameter to bust cached URLs. Clarify instructions.

GirlBossRush · GirlBossRush · commit 0a390fa5f253 · 2025-08-12T20:19:28.000+02:00
diff --git a/authentik/api/templates/api/browser.html b/authentik/api/templates/api/browser.html
@@ -7,7 +7,7 @@
 {% endblock %}
 
 {% block head %}
-<script src="{% versioned_script 'dist/standalone/api-browser/index-%v.js' %}" type="module"></script>
+<script src="{% versioned_script 'dist/standalone/api-browser/index.js' %}" type="module"></script>
 {% endblock %}
 
 {% block body %}
diff --git a/authentik/core/templates/base/skeleton.html b/authentik/core/templates/base/skeleton.html
@@ -21,8 +21,8 @@
         <link rel="stylesheet" type="text/css" href="{% static 'dist/authentik.css' %}">
 
         <style>{{ brand_css }}</style>
-        <script src="{% versioned_script 'dist/poly-%v.js' %}" type="module"></script>
-        <script src="{% versioned_script 'dist/standalone/loading/index-%v.js' %}" type="module"></script>
+        <script src="{% versioned_script 'dist/poly.js' %}" type="module"></script>
+        <script src="{% versioned_script 'dist/standalone/loading/index.js' %}" type="module"></script>
         {% block head %}
         {% endblock %}
         {% for key, value in html_meta.items %}
diff --git a/authentik/core/templates/if/admin.html b/authentik/core/templates/if/admin.html
@@ -3,7 +3,7 @@
 {% load authentik_core %}
 
 {% block head %}
-<script src="{% versioned_script 'dist/admin/AdminInterface-%v.js' %}" type="module"></script>
+<script src="{% versioned_script 'dist/admin/AdminInterface.js' %}" type="module"></script>
 {% include "base/header_js.html" %}
 {% endblock %}
 
diff --git a/authentik/core/templates/if/user.html b/authentik/core/templates/if/user.html
@@ -3,7 +3,7 @@
 {% load authentik_core %}
 
 {% block head %}
-<script src="{% versioned_script 'dist/user/UserInterface-%v.js' %}" type="module"></script>
+<script src="{% versioned_script 'dist/user/UserInterface.js' %}" type="module"></script>
 {% include "base/header_js.html" %}
 {% endblock %}
 
diff --git a/authentik/core/templatetags/authentik_core.py b/authentik/core/templatetags/authentik_core.py
@@ -2,6 +2,7 @@
 
 from django import template
 from django.templatetags.static import static as static_loader
+from django.utils.safestring import mark_safe
 
 from authentik import authentik_full_version
 
@@ -10,5 +11,6 @@
 
 @register.simple_tag()
 def versioned_script(path: str) -> str:
-    """Wrapper around {% static %} tag that supports setting the version"""
-    return static_loader(path.replace("%v", authentik_full_version()))
+    """Wrapper around {% static %} tag that appends a version query parameter to the URL"""
+
+    return static_loader(path) + "?v=" + authentik_full_version()
diff --git a/authentik/flows/templates/if/flow.html b/authentik/flows/templates/if/flow.html
@@ -18,7 +18,7 @@
 {% endblock %}
 
 {% block head %}
-<script src="{% versioned_script 'dist/flow/FlowInterface-%v.js' %}" type="module"></script>
+<script src="{% versioned_script 'dist/flow/FlowInterface.js' %}" type="module"></script>
 <style>
 :root {
     --ak-flow-background: url("{{ flow_background_url }}");
diff --git a/authentik/providers/rac/templates/if/rac.html b/authentik/providers/rac/templates/if/rac.html
@@ -3,7 +3,7 @@
 {% load authentik_core %}
 
 {% block head %}
-<script src="{% versioned_script 'dist/rac/index-%v.js' %}" type="module"></script>
+<script src="{% versioned_script 'dist/rac/index.js' %}" type="module"></script>
 <link rel="icon" href="{{ tenant.branding_favicon_url }}">
 <link rel="shortcut icon" href="{{ tenant.branding_favicon_url }}">
 {% include "base/header_js.html" %}
diff --git a/web/bundler/utils/node.js b/web/bundler/utils/node.js
@@ -3,7 +3,7 @@
  */
 
 import { NodeEnvironment, serializeEnvironmentVars } from "@goauthentik/core/environment/node";
-import { AuthentikVersion } from "@goauthentik/core/version/node";
+import { readAuthentikVersion } from "@goauthentik/core/version/node";
 
 /**
  * Creates a mapping of environment variables to their respective runtime constants.
@@ -17,7 +17,7 @@ export function createBundleDefinitions() {
      * @satisfies {Record<ESBuildImportEnvKey, string>}
      */
     const envRecord = {
-        AK_VERSION: AuthentikVersion,
+        AK_VERSION: readAuthentikVersion(),
         AK_API_BASE_PATH: process.env.AK_API_BASE_PATH ?? "",
     };
 
diff --git a/web/package-lock.json b/web/package-lock.json
diff --git a/web/packages/core/environment/load/node.js b/web/packages/core/environment/load/node.js
@@ -0,0 +1,14 @@
+/**
+ * @file Load the contents of an environment file into `process.env`.
+ */
+import { MonoRepoRoot } from "#paths/node";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const envFilePath = join(MonoRepoRoot, ".env");
+
+if (existsSync(envFilePath)) {
+    console.debug(`Loading environment from ${envFilePath}`);
+
+    process.loadEnvFile(envFilePath);
+}
diff --git a/web/packages/core/package.json b/web/packages/core/package.json
@@ -48,7 +48,9 @@
         "@goauthentik/prettier-config": "^3.1.0",
         "@goauthentik/tsconfig": "^1.0.4",
         "@types/node": "^24.2.1",
+        "@types/semver": "^7.7.0",
         "prettier": "^3.6.2",
+        "semver": "^7.7.2",
         "typescript": "^5.8.3"
     },
     "engines": {
diff --git a/web/packages/core/version/node.js b/web/packages/core/version/node.js
@@ -5,16 +5,40 @@
  */
 import { MonoRepoRoot } from "#paths/node";
 import { execSync } from "node:child_process";
+import { parse as parseSemver } from "semver";
 
 // ts-import-sorter: disable
 import PackageJSON from "../../../../package.json" with { type: "json" };
 
 /**
- * The current version of authentik in SemVer format.
+ * @typedef {`${number}.${number}.${number}`} SimpleSemver */
+
+/**
+ * @type {SimpleSemver | undefined}
+ */
+let cachedSemver;
+
+/**
+ * Read current version of authentik in SemVer format.
  *
  * @runtime node
  */
-export const AuthentikVersion = /**@type {`${number}.${number}.${number}`} */ (PackageJSON.version);
+
+export function readAuthentikVersion() {
+    if (cachedSemver) return cachedSemver;
+
+    const parsed = parseSemver(PackageJSON.version);
+
+    if (!parsed) {
+        throw new TypeError(`Invalid semver version: ${PackageJSON.version}`);
+    }
+
+    cachedSemver = /** @type {SimpleSemver} */ (
+        [parsed.major, parsed.minor, parsed.patch].join(".")
+    );
+
+    return cachedSemver;
+}
 
 /**
  * Reads the last commit hash from the current git repository.
@@ -49,7 +73,12 @@ export function readGitBuildHash() {
 export function readBuildIdentifier() {
     const { GIT_BUILD_HASH } = process.env;
 
-    if (!GIT_BUILD_HASH) return AuthentikVersion;
+    const version = readAuthentikVersion();
+
+    if (!GIT_BUILD_HASH) {
+        console.warn("GIT_BUILD_HASH is not set, falling back to authentik version.");
+        return version;
+    }
 
-    return [AuthentikVersion, GIT_BUILD_HASH].join("+");
+    return [version, GIT_BUILD_HASH].join("+");
 }
diff --git a/web/scripts/build-web.mjs b/web/scripts/build-web.mjs
@@ -1,3 +1,9 @@
+/**
+ * @file ESBuild script for building the authentik web UI.
+ */
+
+import "@goauthentik/core/environment/load/node";
+
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 
@@ -12,7 +18,6 @@ import { DistDirectory, EntryPoint, PackageRoot } from "#paths/node";
 
 import { NodeEnvironment } from "@goauthentik/core/environment/node";
 import { MonoRepoRoot, resolvePackage } from "@goauthentik/core/paths/node";
-import { readBuildIdentifier } from "@goauthentik/core/version/node";
 
 import { deepmerge } from "deepmerge-ts";
 import esbuild from "esbuild";
@@ -29,7 +34,7 @@ const patternflyPath = resolvePackage("@patternfly/patternfly", import.meta);
  * @type {Readonly<BuildOptions>}
  */
 const BASE_ESBUILD_OPTIONS = {
-    entryNames: `[dir]/[name]-${readBuildIdentifier()}`,
+    entryNames: `[dir]/[name]`,
     chunkNames: "[dir]/chunks/[hash]",
     assetNames: "assets/[dir]/[name]-[hash]",
     outdir: DistDirectory,
diff --git a/website/docs/developer-docs/setup/frontend-dev-environment.md b/website/docs/developer-docs/setup/frontend-dev-environment.md
@@ -34,16 +34,18 @@ Depending on platform, some native dependencies might be required. On macOS, run
 
 2. From the cloned repository, follow the Docker Compose [installation instructions](../../install-config/install/docker-compose.mdx).
 
-    Additionally, run the following:
+
+3. Create a `.env` file in the root of the repository to configure the Docker Compose environment.
 
     ```shell
-    echo AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server >> .env
-    echo AUTHENTIK_TAG=gh-next >> .env
-    echo AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-next >> .env
-    echo AUTHENTIK_LOG_LEVEL=debug >> .env
+    AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
+    AUTHENTIK_TAG=gh-next
+    AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-next
+    AUTHENTIK_LOG_LEVEL=debug
+    GIT_BUILD_HASH="dev"
     ```
 
-3. Create a Docker Compose override to mount the local configuration file (`local.env.yml`) and ESBuild's output directory (`web`).
+4. Create a Docker Compose override to mount the local configuration file (`local.env.yml`) and ESBuild's output directory (`web`).
 
     ```yaml title="docker-compose.override.yml"
     services:
@@ -55,20 +57,20 @@ Depending on platform, some native dependencies might be required. On macOS, run
 
     By creating this file in the root of the repository, Docker will automatically mount the web files generated by the build process. The `local.env.yml` mount is optional, but allows you to override the default configuration.
 
-4. From the cloned repository root, install the front-end dependencies using NPM.
+5. From the cloned repository root, install the front-end dependencies using NPM.
 
     ```shell
     cd web
     npm ci
     ```
 
-5. From the cloned repository root, run the front-end build script.
+6. From the cloned repository root, run the front-end build script.
 
     ```shell
     make web-watch
     ```
 
-6. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.
+7. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.
 
     ```shell
     docker compose up
