fix(ci): use GitHub App client IDs

docs: publish Homarr 2.0 article

.env.example

@@ -1,22 +1,24 @@
 # Since .env is gitignored, you can use .env.example to build a new `.env` file when you clone the repo.
-# Keep this file up-to-date when you add new variables to \`.env\`.
+# Keep this file up-to-date when you add new variables to `.env`.
 
 # This file will be committed to version control, so make sure not to have any secrets in it.
 # If you are cloning this repo, create a copy of this file named `.env` and populate it with your secrets.
 
-# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
-AUTH_SECRET="supersecret"
+# Generate two different 64-character hex values with `openssl rand -hex 32` before starting Homarr.
+# Never reuse these values or commit the populated `.env` file.
+AUTH_SECRET=
 
 # The below secret is used to encrypt integration secrets in the database.
-# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix
-# or starting the project without any (which will show a randomly generated one).
-SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
+# Homarr will reject an empty or invalid value and print a randomly generated candidate.
+SECRET_ENCRYPTION_KEY=
 
 LOG_LEVEL='info'
 
 # This is how you can use the sqlite driver:
 DB_DRIVER='better-sqlite3'
-DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
+# Safe local source-development path. SQLite files are ignored by Git.
+# Container images use /appdata/db/db.sqlite by default instead.
+DB_URL='./db.sqlite'
 
 # Those are the two ways to use the mysql2 driver:
 # 1. Using the URL format:
@@ -63,6 +65,8 @@ UNSAFE_ENABLE_MOCK_INTEGRATION=true
 
 # Public URL contract. Values must be absolute HTTP(S) URLs without credentials,
 # query strings, or fragments. Trailing slashes are normalized at startup.
+# Public Homarr origin used by MCP OAuth metadata and redirects behind proxies.
+# BASE_URL=https://homarr.example.com
 HOMARR_WEBSITE_URL=https://homarr.dev
 # PocketBase API used by Homarr and by the standalone documentation site.
 # Defaults to HOMARR_WEBSITE_URL.

.github/pull_request_template.md

@@ -4,14 +4,14 @@
   <h3>Homarr</h3>
 </div>
 
-**Thank you for your contribution. Please ensure that your pull request meets the following pull request:**
+**Thank you for your contribution. Please ensure that your pull request meets the following requirements:**
 
-- [ ] Builds without warnings or errors (`pnpm build`, autofix with `pnpm format:fix`)
-- [ ] Pull request targets `dev` branch
+- [ ] Relevant checks pass without warnings or errors
+- [ ] Pull request targets the intended base branch (`dev` by default; `release/v2` for v2 release work)
 - [ ] Commits follow the [conventional commits guideline](https://www.conventionalcommits.org/en/v1.0.0/)
-- [ ] No shorthand variable names are used (eg. `x`, `y`, `i` or any abbrevation)
-- [ ] Documentation is up to date. Create a pull request [here](https://github.com/homarr-labs/documentation/).
-- [ ] When using AI; No temp files are checked in, the code style follows the rest of the project
+- [ ] No shorthand variable names are used (for example, `x`, `y`, `i`, or abbreviations)
+- [ ] User-facing changes include matching documentation updates under `apps/docs`
+- [ ] When using AI, no temporary files are checked in and the code style follows the rest of the project
 
 **When contributing a new integration or widget:**
 

.github/workflows/bot-auto-merge-reconcile.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write # required to enable auto-merge
 
       - name: Install GitHub CLI

.github/workflows/bot-pr-automerge.yml

@@ -28,7 +28,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write # required to approve a pull request and enable auto-merge
 
       - name: Install GitHub CLI

.github/workflows/crowdin-schedule-download.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.CROWDIN_APP_PRIVATE_KEY }}
-          client-id: ${{ secrets.CROWDIN_APP_ID }}
+          client-id: ${{ vars.CROWDIN_CLIENT_ID }}
           permission-contents: write # required to commit to crowdin branch
           permission-pull-requests: write # required to create pull request
 

.github/workflows/deployment-beta-release.yml

@@ -52,7 +52,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write
       - name: Approve PR
         env:
@@ -64,7 +64,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # write to beta branch (due to merge)
           permission-pull-requests: write # merge pull request
       - id: automerge

.github/workflows/deployment-docker-image.yml

@@ -40,6 +40,7 @@ jobs:
       version: ${{ steps.read-semver.outputs.version || steps.version-fallback.outputs.version }}
       git_ref: ${{ steps.read-git-ref.outputs.ref || steps.read-semver.outputs.version || github.ref }}
       skipped: ${{ env.SKIP_RELEASE }}
+      upstream_sync: ${{ steps.update-upstream.outcome }}
     steps:
       - run: echo "Manual dispatch redeploys the latest existing release without creating a new one"
         if: env.SKIP_RELEASE == 'true'
@@ -54,7 +55,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to commit package.json & changelog changes, merge them to dev / next and publish the release
 
       - uses: actions/checkout@v7
@@ -115,8 +116,10 @@ jobs:
         run: |
           echo "ref=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
       - name: Update dev / next branch
+        id: update-upstream
         if: env.SKIP_RELEASE == 'false'
-        continue-on-error: true # Prevent pipeline from failing when merge fails
+        # Finish publishing the already-created release, then fail in the publish job if synchronization did not work.
+        continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
           UPSTREAM_BRANCH: ${{ github.ref_name == 'main' && 'dev' || 'next' }}
@@ -274,7 +277,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to publish the release
 
       - name: Log in to the Container registry
@@ -311,6 +314,12 @@ jobs:
         run: |
           gh release edit --repo ${{ github.repository }} ${{ needs.release.outputs.version }} --draft=false
 
+      - name: Verify dev / next synchronization
+        if: needs.release.outputs.skipped == 'false' && needs.release.outputs.upstream_sync != 'success'
+        run: |
+          echo "::error::The released commit was not synchronized back to the upstream development branch."
+          exit 1
+
       - name: Discord notification
         if: github.event_name != 'workflow_dispatch' || inputs['send-notifications']
         env:
@@ -318,3 +327,17 @@ jobs:
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "Successfully deployed images for branch **${{ github.ref_name }}**. Tagged as **${{env.NEXT_VERSION}}**."
+
+  notify-failure:
+    name: Notify deployment failure
+    if: ${{ always() && (failure() || cancelled()) && (github.event_name != 'workflow_dispatch' || inputs['send-notifications']) }}
+    needs: [release, build-amd64, build-arm64, extract-asset-amd64, extract-asset-arm64, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Discord failure notification
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "The deployment for branch **${{ github.ref_name }}** failed or was cancelled: [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"

.github/workflows/deployment-weekly-release.yml

@@ -19,10 +19,10 @@ permissions:
 jobs:
   create-and-merge-pr:
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 10
     steps:
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ github.event_name == 'schedule' || inputs.send-notifications }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -38,13 +38,30 @@ jobs:
         with:
           token: ${{ github.token }}
           branch: dev
+          noNewCommitBehavior: silent
+          noVersionBumpBehavior: silent
+      - name: No release needed
+        if: ${{ steps.semver.outputs.bump == '' || steps.semver.outputs.bump == 'none' }}
+        run: echo "No release-worthy commits were found since ${{ steps.semver.outputs.current }}." >> "$GITHUB_STEP_SUMMARY"
       - name: Create pull request
         id: create-pull-request
-        run: 'gh pr create --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" --base main --head dev --label automerge'
+        if: ${{ steps.semver.outputs.bump != '' && steps.semver.outputs.bump != 'none' }}
+        run: |
+          pr_url="$(gh pr list --base main --head dev --state open --json url --jq '.[0].url // empty')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" \
+              --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" \
+              --base main \
+              --head dev \
+              --label automerge)"
+          fi
+          echo "url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_url##*/}" >> "$GITHUB_OUTPUT"
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
       - name: Discord notification
-        if: ${{ github.event.inputs.send-notifications }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
@@ -52,26 +69,29 @@ jobs:
           args: "Created a release PR ${{ steps.create-pull-request.outputs.url }} for version ${{ steps.semver.outputs.next }} (new behaviour: ${{ steps.semver.outputs.bump }})"
       - name: Obtain token
         id: obtainApprovalToken
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
           permission-pull-requests: write
       - name: Approve PR
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         env:
           GITHUB_TOKEN: ${{ steps.obtainApprovalToken.outputs.token }}
         run: |
-          gh pr review --approve --body "Automatically approved by GitHub Action"
+          gh pr review "${{ steps.create-pull-request.outputs.url }}" --approve --body "Automatically approved by GitHub Action"
       - name: Obtain token
         id: obtainMergeToken
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # write to main branch (due to merge)
           permission-pull-requests: write # merge pull request
       - id: automerge
-        if: ${{ steps.semver.outputs.bump != 'major' }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && steps.semver.outputs.bump != 'major' }}
         name: automerge
         uses: "pascalgn/automerge-action@v0.16.4"
         env:
@@ -85,21 +105,21 @@ jobs:
           MERGE_REQUIRED_APPROVALS: 0 # do not require approvals
 
       - name: Merged Discord notification
-        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && github.event.inputs.send-notifications }}
+        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "Merged PR ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
       - name: Major Bump Discord notification
-        if: ${{ steps.semver.outputs.bump == 'major' && github.event.inputs.send-notifications }}
+        if: ${{ steps.semver.outputs.bump == 'major' && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0
         with:
           args: "The release PR must be manually merged because the next version is a major version: ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
       - name: Discord Fail Notification
-        if: failure() && github.event.inputs.send-notifications
+        if: ${{ failure() && (github.event_name == 'schedule' || inputs.send-notifications) }}
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0

.github/workflows/on-release.yml

@@ -5,39 +5,6 @@ on:
     types: [released]
 
 jobs:
-  trigger-docs-release:
-    name: Trigger Documentation Release
-    runs-on: ubuntu-latest
-    timeout-minutes: 2
-    steps:
-      - name: Obtain token
-        id: obtainToken
-        uses: actions/create-github-app-token@v3
-        with:
-          private-key: ${{ secrets.HOMARR_DOCS_RELEASE_APP_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_DOCS_RELEASE_APP_ID }}
-          owner: homarr-labs
-          repositories: |
-            documentation
-          permission-contents: write # required to dispatch repository workflow
-      - name: Trigger documentation release
-        env:
-          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
-          SOURCE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          curl -X POST \
-            -H "Authorization: token $GITHUB_TOKEN" \
-            -H "Accept: application/vnd.github+json" \
-            https://api.github.com/repos/homarr-labs/documentation/dispatches \
-            -d @- <<EOF
-          {
-            "event_type": "trigger-release",
-            "client_payload": {
-              "tag": "${SOURCE_TAG}"
-            }
-          }
-          EOF
-
   update-bug-report-template:
     name: Update Bug Report Template
     runs-on: ubuntu-latest
@@ -48,7 +15,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          client-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
       - name: Checkout code

.github/workflows/update-contributors.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
 

.github/workflows/update-integration-list.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/create-github-app-token@v3
         with:
           private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
           permission-contents: write # required to commit to branch
           permission-pull-requests: write # required to create pr & enable automerge
       - name: Checkout code

.oxfmtrc.json

@@ -10,7 +10,11 @@
     "CHANGELOG.md",
     "apps/docs/.docusaurus/**",
     "apps/docs/build/**",
-    "apps/docs/blog/**",
+    "apps/docs/blog/2022/**",
+    "apps/docs/blog/2023/**",
+    "apps/docs/blog/2024/**",
+    "apps/docs/blog/2025/**",
+    "apps/docs/blog/authors.yml",
     "packages/custom-widgets/src/core/component-catalog.generated.json",
     "apps/docs/static/custom-widgets/component-catalog-v1.json"
   ]

apps/docs/blog/2026/09-03-homarr-2.0/index.mdx

@@ -0,0 +1,219 @@
+---
+title: "Homarr 2.0.0: our biggest upgrade yet"
+authors:
+  - ajnart
+  - manuel-rw
+  - tagashi
+  - meierschlumpf
+tags: [homarr, update, version, assistant, custom widgets, dashboards, docker]
+draft: false
+---
+
+Homarr 2.0 is our biggest upgrade so far. It keeps the same job: put your apps, services, and status on one dashboard.
+
+We rebuilt the parts that had become difficult to extend: boards, Custom Widgets, Docker discovery, Assistant, and MCP.
+
+![A populated Homarr 2.0 dashboard with compact widgets, an Assistant, and an application rail](./img/homarr-v2-dashboard.webp)
+
+<!-- truncate -->
+
+:::warning Back up before upgrading
+
+Create a [Homarr backup](/docs/management/backup) and copy your application data before starting 2.0. Do not test a prerelease image on the only copy of your production volume. Backups are boring. Restores are worse.
+
+:::
+
+## Boards
+
+### Brand new drag and drop
+
+We re-thought drag and drop from the ground up and switched to [`dnd-kit`](https://dndkit.com/). Moves and eight-direction resizes are transactional: Homarr calculates a preview, checks collisions, and commits only a valid layout.
+
+Invalid or cancelled moves roll back. The same engine handles the main grid, rails, and nested Containers with pointer, touch, or keyboard input.
+
+![A Calendar tile moving across the rebuilt Homarr 2.0 board grid](./img/drag-and-drop.gif)
+
+### Goodbye Groups and sections, welcome Containers
+
+Groups and dynamic sections overlapped. Containers replace both with one model for apps, widgets, and nested Containers. They can be moved, resized, collapsed, scrolled, labeled, or configured to open their apps together.
+
+### Move multiple items at once
+
+Hold <kbd>Ctrl</kbd> on Windows or Linux, or <kbd>Command</kbd> on macOS, to select several items. Copy, delete, or move the selection to the main grid, a rail, or a Container. The move is saved only when every item fits.
+
+![Three selected board items with the batch Move menu offering the main canvas and right rail](./img/batch-move.webp)
+
+### Responsive layouts for the same board
+
+Each board has protected Base and Mobile layouts, with optional breakpoints between them. Homarr selects the highest matching breakpoint and scales the complete layout instead of changing widget proportions.
+
+**Reset from Base** generates a Mobile starting point without duplicating the board. Desktop layouts can reserve one to three columns as rails; Mobile places those items back in the main flow.
+
+![The responsive layout editor beside the same Homarr board rendered at a mobile viewport](./img/responsive-layouts.webp)
+
+### A visual board switcher
+
+The board switcher is now a searchable gallery with keyboard navigation. Open it from the header or press <kbd>Shift</kbd> + <kbd>C</kbd>.
+
+![A visual board card inside the searchable Homarr board switcher](./img/board-switcher.webp)
+
+### Configure your header
+
+The Header studio arranges built-in controls across left, center, and right areas. Logo, search, board, Assistant, Docker, editing, settings, theme, and account controls are available. A recovery control remains when the normal header is hidden.
+
+![The Header studio showing left, center, and right zones plus available controls](./img/header-studio.webp)
+
+### Add content without leaving the board
+
+The board menu creates widgets, apps, integrations, and Containers without opening a management page. Compatible integrations stay in the same flow, apps have Quick Add, and Workshop sits beside Custom Widgets.
+
+![The board's Add content menu offering a widget, app, integration, or Container](./img/add-content-menu.webp)
+
+Small destructive actions can use a second click for confirmation; higher-risk actions keep a full dialog.
+
+Read the [board guide](/docs/management/boards) for layout rules, rails, Containers, and keyboard controls.
+
+## Search, Assistant, and MCP
+
+### One command menu
+
+Press <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> to search Homarr resources, pages, settings, users, groups, and commands. Assistant, media, and web providers can add results. Homarr results rank first, and create actions follow your permissions.
+
+![The Homarr 2.0 command menu opening and returning mixed results for an Assistant query](./img/command-menu.gif)
+
+### Assistant inside Homarr
+
+Open Assistant from a board or the user menu with <kbd>Shift</kbd> + <kbd>A</kbd>. <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>/</kbd> opens Assistant search. It reads live Homarr data and uses tools for boards, apps, integrations, widgets, Docker, and supported services.
+
+Tool calls use the signed-in user's permissions. Read-only calls can run automatically; changes require approval by default. Provider credentials stay encrypted on the server. Providers, models, attachments, mentions, sources, usage, and private history are supported. Workshop also provides a community-funded provider.
+
+![The Homarr Assistant expanded over a live dashboard with health, exploration, media, and board actions](./img/assistant-control-surface.webp)
+
+### Connect external clients with MCP
+
+Homarr now exposes a stateless MCP server at `/api/mcp`. It implements MCP `2026-07-28` and accepts 2025 Streamable HTTP clients. The older `/api/mcp/mcp` path remains as an alias; the removed HTTP+SSE routes return `410 Gone`.
+
+Authenticate with an API key or OAuth 2.1 with PKCE. Tools cover boards, apps, integrations, Docker, Kubernetes, media, downloads, DNS, and Custom Widget authoring. The catalog returned by `tools/list` follows the current release and the authenticated user's permissions; confirmations still apply to changes.
+
+![Homarr's AI and MCP management page with authentication and Streamable HTTP client configuration](./img/mcp-management.webp)
+
+See [Assistant setup](/docs/management/assistant) and the [MCP guide](/docs/management/mcp).
+
+## Custom Widgets v2
+
+### A proper workbench
+
+We rebuilt the editor around the `homarr-custom-widget-v2` schema. API sources, requests, options, JSX, validation, and preview now share one workspace. Explicit preview generation prevents stale requests from replacing newer work, with three sizes and Live, Loading, Empty, and Error states.
+
+![The Custom Widget v2 workbench after a live exchange-rate request successfully renders its preview](./img/custom-widget-workbench.webp)
+
+### Server-side requests and actions
+
+A widget can use several fixed-origin API sources with separately encrypted credentials. Load requests support caching and manual or automatic refreshes. `ActionButton` and `ToggleSwitch` can run GET, POST, PUT, PATCH, and DELETE actions with confirmation, feedback, rollback, and query invalidation.
+
+![A Custom Widget v2 request configured as a permission-checked POST action with body and refresh controls](./img/custom-widget-post-action.webp)
+
+Widgets can expose saved controls for text, numbers, toggles, selections, sliders, dates, colors, icons, URLs, time zones, and JSON. Values feed request paths, query parameters, and nested JSON bodies, while select choices can come from another request.
+
+Host validation, redirect checks, timeouts, response limits, request budgets, permissions, and rate limits constrain requests. Custom Widgets remain **Beta** in 2.0.
+
+### Share through Workshop
+
+Workshop lets you publish, install, update, vote on, report, and share Custom Widgets and CSS. Submission screenshots now open in a keyboard-accessible viewer with thumbnails and zoom.
+
+The workbench can also generate a credential-free prompt for AI-assisted authoring. Deployment URLs and credentials stay in your Homarr instance.
+
+![The Community Workshop catalog inside Custom Widget management](./img/community-workshop.webp)
+
+Read the [Custom Widgets guide](/docs/management/custom-widgets) and [request security reference](/docs/management/custom-widgets/requests-and-security).
+
+## Widgets
+
+### Advanced views without larger tiles
+
+Supported widgets expand by Shift-hover, keyboard, or context menu. Preview the advanced view or pin it while the board becomes inactive. Widgets opt in explicitly, so compact tiles remain the default elsewhere.
+
+![The Download Client advanced view with transfer totals, filters, status, and per-item detail](./img/advanced-downloads.webp)
+
+### Settings with a live preview
+
+Widget settings now combine live preview, grouped options, and in-place app or integration editing. Weather and Clock were redesigned; Air Quality, Countdown, and Timer were added.
+
+Notebook gained collapsible sections and table controls for rows, columns, headers, cell colors, merging, and splitting. Health Monitoring now renders CPU usage, CPU temperature, memory, and GPU utilization as threshold-colored gauges.
+
+## Setup, sign-in, and Docker
+
+### One onboarding flow
+
+The six-stage setup studio discovers Docker-compatible services, prepares app and integration drafts, and creates the first board in one transaction.
+
+![The Homarr 2.0 setup studio on its Essentials step, with all six setup stages shown](./img/onboarding-studio.webp)
+
+### Branded sign-in and better external authentication
+
+Login pages use the name, logo, background, greeting, colors, and corner style configured for the instance.
+
+![The upgraded Homarr login page with a branded backdrop and centered account card](./img/new-login.webp)
+
+LDAP can provision a Homarr user on first sign-in. OIDC uses its Auth.js adapter, can link a verified email to an existing credentials account when enabled, and can synchronize external membership into existing Homarr groups. Exact behavior depends on the provider.
+
+### Multiple Docker and Podman endpoints
+
+`DOCKER_ENDPOINTS` defines Docker or Podman hosts with separate transports and capabilities. Healthy endpoint inventory remains available when another endpoint fails. Assisted setup compares containers with existing resources, suggests apps and integrations, and derives likely URLs.
+
+![Assisted Docker setup listing discovered services that can become apps or integrations](./img/docker-assisted-setup.webp)
+
+### Create Homarr content from container labels
+
+`homarr.name` and `homarr.href` identify a service. Optional `homarr.*` labels add integrations, place content in Containers, select widgets, set icons and health checks, keep stable IDs, and target a board.
+
+When `homarr.name` is absent, Homarr can use Homepage's `name`, `href`, `group`, `icon`, and `description` labels. Both `homepage.name` and `homepage.href` are required, and Homarr does not combine partial metadata from the two formats.
+
+See the [Docker label reference](/docs/integrations/docker-labels) for the exact fields and required combinations.
+
+## Permissions and appearance
+
+### Permissions you can inspect
+
+Group permissions now use a matrix with Viewer, Editor, and Admin presets. Access levels and create permissions are separate, with inherited and effective permissions shown before saving.
+
+![The Editor permission preset showing explicit board, app, integration, search, media, and administration scopes](./img/permission-matrix.webp)
+
+App, integration, and home-stat data are filtered on the server. Management navigation, API procedures, Assistant, and MCP use the same permission model.
+
+### Instance branding and global CSS
+
+Server branding now covers the application name, logo, favicon, colors, board accent behavior, and corner styles.
+
+![Instance branding controls for application identity, palette, corner style, and global CSS](./img/instance-branding.webp)
+
+Authentication pages add background, overlay, greeting, and visibility controls. Global CSS applies across the instance; board CSS is more specific and wins later in the cascade.
+
+![The global CSS editor, authentication appearance controls, and current branding summary](./img/global-css-and-auth.webp)
+
+Global CSS is not a security sandbox. Only trusted administrators should control it. See [Styling](/docs/advanced/styling) and [Server settings](/docs/management/settings).
+
+## Less waiting and duplicate work
+
+Board startup now runs independent session, layout, and widget-prefetch work in parallel. Spotlight, editors, media, and other heavy surfaces load only when opened. Drag previews and Custom Widget analysis update without re-rendering the complete page.
+
+Identical integration requests share in-flight work. Bounded in-process and Redis-backed caches coordinate responses and refresh locks across processes, while stale data can remain visible during a temporary upstream failure. Eligible public widget data can also return from the session cache while it refreshes.
+
+For release hardening, we also applied the current Auth.js, `protobufjs`, and production dependency security patches.
+
+## Before upgrading
+
+- Keep a backup and use the final release image, not a prerelease tag.
+- Legacy Custom JSX definitions enter an explicit migration state. Homarr keeps encrypted credentials and an archived copy until the v2 definition validates.
+- Mobile layouts place rail content in the main flow instead of displaying rails.
+- Custom Widgets remain Beta.
+- Assistant and MCP never bypass user, API-key, integration, or Docker endpoint permissions.
+
+## Links
+
+- Try the [Homarr 2.0 preview](https://app-v2.preview.homarr.dev).
+- Follow the [v2 release pull request](https://github.com/homarr-labs/homarr/pull/6545) and [public beta thread](https://github.com/homarr-labs/homarr/issues/6600).
+- Compare [v1.76.2 with the release/v2 branch](https://github.com/homarr-labs/homarr/compare/v1.76.2...release/v2).
+- Read the guides for [Boards](/docs/management/boards), [Custom Widgets](/docs/management/custom-widgets), [Assistant](/docs/management/assistant), [MCP](/docs/management/mcp), and [Docker labels](/docs/integrations/docker-labels).
+
+{/* Editorial release gate: set draft to false, update the dated path if needed, replace the branch comparison with the v2.0.0 tag, and verify the production image and migration notes before publishing. */}

apps/docs/docs/advanced/command-line/index.mdx

@@ -14,7 +14,31 @@ docker exec -it <container-id> /bin/bash
 homarr <command>
 ```
 
-In QNAP Container Station, open the Homarr container's **Execute** action and select `/bin/bash`.
+### QNAP Container Station
+
+1. Open **Container Station**.
+
+![Container Station in the QNAP application menu](./img/334116069-e7ec4726-3df7-4dc6-a3e0-b745e7eef17f.png)
+
+2. Select **Containers**.
+
+![Containers menu in QNAP Container Station](./img/334116205-aa09ce40-0701-4f7d-b9f9-b431b9d207c5.png)
+
+3. Select the Homarr container.
+
+![Homarr container selected in QNAP Container Station](./img/334116303-714b5e07-b9de-4ec0-a2bc-def7ee38750f.png)
+
+4. Select **Execute**.
+
+![Execute action for the Homarr container in QNAP Container Station](./img/334116411-df1482f9-3aa9-4686-b77f-e0dca09e60b2.png)
+
+5. Select `/bin/bash`, then select **Execute**.
+
+![Bash selected in the QNAP execute console](./img/334116518-e1ddb515-99c7-4159-81bf-76e889d1e808.png)
+
+6. Run `homarr <command>` in the console.
+
+![Bash console open for Homarr in QNAP Container Station](./img/334116642-08c4f204-5cd0-4e4e-a785-0142e1b279ca.png)
 
 See the pages in this section for available commands.
 

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -30,7 +30,8 @@ Using the `PUID` and `PGID` will require you to set the correct permissions on t
 | `PUID`                   | User ID to run the container as                                                                                                                                                                                                        | Any valid user ID                   | `0`                           |
 | `PGID`                   | Group ID to run the container as                                                                                                                                                                                                       | Any valid group ID                  | `0`                           |
 | `LOG_LEVEL`              | Log level to use                                                                                                                                                                                                                       | `debug` / `info` / `warn` / `error` | `info`                        |
-| `NO_EXTERNAL_CONNECTION` | Disables Homarr's internet-backed requests, including update checks, weather, and RSS feeds                                                                                                                                            | `true` or `false`                   | `false`                       |
+| `BASE_URL`               | Public Homarr origin used by MCP OAuth metadata and redirects. Set this when a reverse proxy does not preserve the public host and protocol.                                                                                           | HTTP(S) origin without a path       | -                             |
+| `NO_EXTERNAL_CONNECTION` | Disables Homarr's internet-backed requests, including update checks, weather, location search, and RSS feeds                                                                                                                           | `true` or `false`                   | `false`                       |
 | `ENABLE_DNS_CACHING`     | Enables dns caching. Enabled by default, but if you experience issues with IPv6 or static IPs, see [#4006](https://github.com/homarr-labs/homarr/issues/4006) or disable this flag                                                     | `true` or `false`                   | `true`                        |
 | `HOMARR_DISABLE_IPV6`    | Disables the IPv6 listener of the internal nginx proxy, even when the host supports IPv6. IPv6 is normally disabled automatically when the host has no IPv6 configured. See [#4596](https://github.com/homarr-labs/homarr/issues/4596) | `true` or `false`                   | `false`                       |
 | `HOMARR_WEBSITE_URL`     | Main Homarr documentation/site base used by runtime links. Must be an absolute HTTP(S) URL.                                                                                                                                            | HTTP(S) URL                         | `https://homarr.dev`          |

apps/docs/docs/advanced/proxy/index.mdx

@@ -40,7 +40,7 @@ services:
     volumes:
       - ./homarr/appdata:/appdata
     environment:
-      - BASE_URL=your.internal.dns.address.here.com
+      - BASE_URL=https://your.internal.dns.address.here.com
       - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
     networks:
       - proxy

apps/docs/docs/advanced/single-sign-on/index.mdx

@@ -202,9 +202,9 @@ Homarr supports multiple authentication options, from internal userbase (credent
     | ``AUTH_OIDC_CLIENT_NAME``   | Display name of provider (in login screen)                 | OIDC          |
     | ``AUTH_OIDC_AUTO_LOGIN``    | Automatically redirect to OIDC login                       | false         |
     | ``AUTH_OIDC_SCOPE_OVERWRITE`` | Overwrite default scopes (openid, profile, email)        | openid email profile groups           |
-    | ``AUTH_OIDC_GROUPS_ATTRIBUTE`` | Attribute used for groups (roles) claim                  | groups        |
+    | ``AUTH_OIDC_GROUPS_ATTRIBUTE`` | Attribute used for groups (roles) claim. Dot-separated paths such as `resource_access.homarr.roles` are supported. | groups        |
     | ``AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT`` | Stop syncing group memberships of OIDC users from the groups claim and manage them locally via the group members page instead | false |
-    | ``AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE`` | Overwrite name attribute. By default it will use preferred_username if it does not contain a `@` and otherwise name. | ---          |
+    | ``AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE`` | Overwrite name attribute. Dot-separated paths are supported. By default it will use preferred_username if it does not contain a `@` and otherwise name. | ---          |
     | ``AUTH_OIDC_FORCE_USERINFO`` | Force userinfo endpoint to be used for user information.    | false         |
     | ``AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING`` | Enable account linking for OIDC provider. This will link the OIDC accounts by email. Be sure that you have verified emails to prevent stealing accounts. | false |
     | ``AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING`` | Link an OIDC identity to an existing credentials user with the same email. The credentials login and existing user data are preserved. Requires the OIDC profile to contain `email_verified: true`. | false |
@@ -244,18 +244,21 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Create a group (e.g., `homarr-admins`) and assign users who require admin access.
 
         **2. Example .env file:**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #OIDC client ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #OIDC client secret
+        OIDC_CLIENT_ID=<REPLACE_WITH_OIDC_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_OIDC_CLIENT_SECRET>
         OIDC_SLUG=homarr #Application slug in Authentik
         AUTH_DOMAIN=auth.example.com #Authentik FQDN
         ADMIN_GROUP=homarr-admins #Authentik group for Homarr admins
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration:**
-        ```yaml {14-26}
+        ```yaml {14-24}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -269,8 +272,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=America/Los_Angeles
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
@@ -322,15 +323,18 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Record the `Client-ID` and `Client Key` (secret).
 
         **2. Example .env file (Homarr):**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #Google Client-ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret)
+        OIDC_CLIENT_ID=<REPLACE_WITH_GOOGLE_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_GOOGLE_CLIENT_SECRET>
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration (Homarr):**
-        ```yaml {16-22}
+        ```yaml {14-20}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -344,8 +348,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=Europe/Berlin
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

apps/docs/docs/getting-started/installation/helm.md

@@ -2,9 +2,9 @@
 
 <img src="https://raw.githubusercontent.com/homarr-labs/charts/refs/heads/main/charts/homarr/icon.svg" align="right" width="92" alt="homarr logo">
 
-![Version: 8.28.1](https://img.shields.io/badge/Version-8.28.1-informational?style=flat)
+![Version: 8.28.2](https://img.shields.io/badge/Version-8.28.2-informational?style=flat)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat)
-![AppVersion: v1.76.1](https://img.shields.io/badge/AppVersion-v1.76.1-informational?style=flat)
+![AppVersion: v1.76.2](https://img.shields.io/badge/AppVersion-v1.76.2-informational?style=flat)
 
 A Helm chart to deploy homarr for Kubernetes
 
@@ -437,7 +437,7 @@ All available values are listed on the [artifacthub](https://artifacthub.io/pack
 | httproute.rules[0].matches[0].path.value           | string | `"/"`                                                                                                                                                                                                                                            | Path value to match                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | image.pullPolicy                                   | string | `"IfNotPresent"`                                                                                                                                                                                                                                 | Image pull policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | image.repository                                   | string | `"ghcr.io/homarr-labs/homarr"`                                                                                                                                                                                                                   | Image repository                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| image.tag                                          | string | `"v1.76.1"`                                                                                                                                                                                                                                      | Overrides the image tag whose default is the chart appVersion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| image.tag                                          | string | `"v1.76.2"`                                                                                                                                                                                                                                      | Overrides the image tag whose default is the chart appVersion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | imagePullSecrets                                   | list   | `[]`                                                                                                                                                                                                                                             | Secrets for Docker registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | ingress.annotations                                | object | `{}`                                                                                                                                                                                                                                             | Ingress annotations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | ingress.enabled                                    | bool   | `false`                                                                                                                                                                                                                                          | Enable ingress                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

apps/docs/docs/getting-started/installation/source.mdx

@@ -38,13 +38,14 @@ This method is only useful, when you want to develop on Homarr or extend it with
     Install all dependencies using <code>pnpm install</code>
   </li>
   <li>
-    Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite
-    database file. For example `DB_URL='/home/username/homarr/db.sqlite`
+    Copy the `.env.example` file to `.env`. Its `DB_URL='./db.sqlite'` value is ready for local use and stores the
+    database in the cloned repository. Replace it with an absolute writable path such as
+    `DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
   </li>
   <li>
-    Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
+    Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
+    values. Keep both values secret and preserve `SECRET_ENCRYPTION_KEY` with your backups.
   </li>
-  <li>Replace `CRON_JOB_API_KEY` with a secure random string by using `openssl rand -base64 32`</li>
   <li>Run `pnpm run db:migration:sqlite:run` and wait that it completes</li>
   <li>Build the source using `pnpm build`</li>
   <li>

apps/docs/docs/getting-started/upgrade-v2.mdx

@@ -0,0 +1,74 @@
+---
+title: Upgrade from v1 to v2
+sidebar_position: 2
+tags:
+  - Getting started
+  - Upgrade
+  - Migration
+  - Backup
+---
+
+Homarr v2 upgrades the existing v1 database in place. Keep the same data storage, database configuration, and
+`SECRET_ENCRYPTION_KEY`; only change the Homarr image or package version for the first start.
+
+:::danger Back up before starting v2
+
+In Homarr v1, go to **Management → Tools → Backup**, export a backup, and keep the downloaded file somewhere safe
+before starting v2. See [Backup and restore](/docs/management/backup) for details.
+
+:::
+
+## Upgrade
+
+1. Pin the Homarr image to `ghcr.io/homarr-labs/homarr:v2.0.0` for the first v2 start.
+2. Keep the existing `/appdata` mount, database variables, Redis configuration, and `SECRET_ENCRYPTION_KEY` unchanged.
+3. Start one Homarr replica and follow its logs. Startup must reach `Migration complete`; Homarr aborts startup when a
+   database migration fails.
+4. Open Homarr and sign in. Confirm **Management → About** reports v2 before starting additional replicas.
+5. After validation, keep the version pinned or return to your normal stable release policy.
+
+For Docker Compose, the change is limited to the image tag before the usual update:
+
+```yaml
+services:
+  homarr:
+    image: ghcr.io/homarr-labs/homarr:v2.0.0
+```
+
+```sh
+docker compose pull
+docker compose up -d
+docker compose logs --follow homarr
+```
+
+Do not add `-v` when stopping the Compose deployment; that can remove named volumes.
+
+## What v2 migrates
+
+The startup migration:
+
+- creates the Custom Widget v2, Assistant, header preference, and branding storage;
+- adds Base/Mobile layout roles and left/right board gutters;
+- converts legacy Categories and dynamic sections into Containers and rails;
+- preserves legacy Custom Widget definitions, encrypted secrets, and board references for explicit migration.
+
+Legacy Custom Widgets are not silently rewritten. In **Management → Custom Widgets**, entries marked
+**Migration required** provide a credential-free migration prompt. Review and test the resulting v2 definition before
+removing the archived v1 version. See [Custom Widgets: Import and Workshop](/docs/management/custom-widgets#import-and-workshop).
+
+## Verify the upgraded instance
+
+- Sign in with each enabled authentication method and verify administrator access.
+- Open every important board on desktop and mobile. Check Containers, former Categories, rails, item placement, and
+  home-board assignments.
+- Test at least one read and one permitted action for each critical integration. Recheck integration and board access
+  for representative Viewer, Editor, and Admin groups.
+- Check Docker or Podman endpoints, search engines, uploaded media, trusted certificates, scheduled tasks, WebSockets,
+  and external Redis when used.
+- Review every legacy Custom Widget and migrate it only after its v2 preview and requests work.
+- Restart Homarr once more and confirm the logs contain no migration, database, Redis, authentication, or task errors.
+
+## Roll back
+
+Use the backup exported before the upgrade if you need to restore your v1 installation. Do not reuse a database that
+v2 has already migrated with v1.

apps/docs/docs/integrations/unifi-controller/index.mdx

@@ -16,7 +16,7 @@ import { networkControllerStatusWidget } from "@site/docs/widgets/network-contro
 <IntegrationHeader integration={unifiControllerIntegration} categories={["Network controller"]} />
 
 This integration is using the [node-unifi](https://www.npmjs.com/package/node-unifi) library under the hood to connect to the Unifi Controller.
-Therfore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
+Therefore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
 
 ### Widgets & Capabilities
 
@@ -28,6 +28,14 @@ Therfore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro c
 
 <AddingIntegration />
 
+Use the local HTTPS address of your controller:
+
+- UniFi OS consoles such as Dream Router, Dream Machine, Cloud Gateway, and CloudKey use `https://<host>` (port 443).
+- Self-hosted UniFi Network Servers normally use `https://<host>:8443`.
+- If you omit the port, Homarr tries port 443 first and then port 8443 when the first port cannot be reached.
+
+Use a local administrator account. Cloud-only accounts and accounts with multi-factor authentication are not supported by the underlying client.
+
 ### Secrets
 
 <IntegrationSecrets

apps/docs/docs/management/backup.mdx

@@ -30,8 +30,9 @@ needed to restore encrypted integration credentials.
 Select a Homarr backup ZIP. The browser previews entity counts, board names, and required database migrations before
 the archive is uploaded.
 
-Restoring replaces the current SQLite database and cannot be undone. After a successful restore, the Next.js process
-restarts and the page reloads when Homarr is ready.
+Restoring replaces the current SQLite database and cannot be undone. It also invalidates the current database session.
+After a successful management restore, Homarr waits for the restarted server and sends the administrator to sign in
+again. The first-run onboarding restore keeps its existing board destination.
 
 A backup can be restored on another Homarr instance. When its `SECRET_ENCRYPTION_KEY` differs, Homarr re-encrypts stored
 integration secrets for the target instance. Version metadata is used to apply compatible migrations.

apps/docs/docs/management/mcp.mdx

@@ -54,6 +54,10 @@ The **AI / MCP** tab on Homarr's API page shows the current endpoint, configurat
 MCP supports API keys and OAuth 2.1 with PKCE. API keys are simpler for direct client configuration; OAuth is available
 for clients that support dynamic authorization.
 
+When Homarr is behind a reverse proxy that does not preserve the public host and protocol, set `BASE_URL` to the exact
+public origin, for example `https://homarr.example.com`. Do not include a path. OAuth clients discover the authorization
+server and protected resource through Homarr's `/.well-known/` routes.
+
 Tools use the permissions of the API key owner or authorized user. Creating a key does not grant additional access.
 Custom Widget and Workshop authoring tools, prompts, and resources are visible only to administrators.
 

apps/docs/docs/widgets/weather/index.mdx

@@ -31,5 +31,6 @@ adds hourly temperature and precipitation charts and the complete seven-day fore
 Weather and location data come from Open-Meteo. Active weather refreshes every ten minutes; identical location requests
 can reuse a server response for five minutes. Failed refreshes keep the last successful data with an error indicator.
 
-Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests. Allowlist
-`https://open-meteo.com` when outbound access is restricted.
+Set `NO_EXTERNAL_CONNECTION=true` to disable this and other internet-backed requests. Weather data and the city search
+inside the widget configuration are unavailable while it is enabled. Allowlist `https://open-meteo.com` when outbound
+access is restricted.

apps/nextjs/next.config.ts

@@ -65,6 +65,15 @@ const nextConfig: NextConfig = {
       },
     ],
   },
+  async rewrites() {
+    return [
+      { source: "/.well-known/:path*", destination: "/well-known/:path*" },
+      {
+        source: "/api/mcp/:transport/.well-known/:path*",
+        destination: "/well-known/:path*/api/mcp/:transport",
+      },
+    ];
+  },
   // skipcq: JS-0116
   // eslint-disable-next-line @typescript-eslint/require-await,no-restricted-syntax
   async headers() {

apps/nextjs/src/app/.well-known/oauth-authorization-server/route.ts

@@ -1,33 +0,0 @@
-import { headers } from "next/headers";
-
-import { extractBaseUrlFromHeaders } from "@homarr/common";
-
-const corsHeaders = {
-  "Access-Control-Allow-Origin": "*",
-  "Access-Control-Allow-Methods": "GET, OPTIONS",
-  "Access-Control-Allow-Headers": "*",
-};
-
-export async function GET() {
-  const baseUrl = extractBaseUrlFromHeaders(await headers());
-
-  return Response.json(
-    {
-      issuer: baseUrl,
-      authorization_endpoint: `${baseUrl}/api/mcp/oauth/authorize`,
-      token_endpoint: `${baseUrl}/api/mcp/oauth/token`,
-      registration_endpoint: `${baseUrl}/api/mcp/oauth/register`,
-      response_types_supported: ["code"],
-      grant_types_supported: ["authorization_code"],
-      code_challenge_methods_supported: ["S256"],
-      token_endpoint_auth_methods_supported: ["none"],
-      scopes_supported: ["mcp:tools"],
-      resource_indicators_supported: true,
-    },
-    { headers: corsHeaders },
-  );
-}
-
-export async function OPTIONS() {
-  return new Response(null, { status: 204, headers: corsHeaders });
-}

apps/nextjs/src/app/.well-known/oauth-protected-resource/route.ts

@@ -1,25 +0,0 @@
-import { headers } from "next/headers";
-
-import { extractBaseUrlFromHeaders } from "@homarr/common";
-
-const corsHeaders = {
-  "Access-Control-Allow-Origin": "*",
-  "Access-Control-Allow-Methods": "GET, OPTIONS",
-  "Access-Control-Allow-Headers": "*",
-};
-
-export async function GET() {
-  const baseUrl = extractBaseUrlFromHeaders(await headers());
-
-  return Response.json(
-    {
-      resource: `${baseUrl}/api/mcp`,
-      authorization_servers: [baseUrl],
-    },
-    { headers: corsHeaders },
-  );
-}
-
-export async function OPTIONS() {
-  return new Response(null, { status: 204, headers: corsHeaders });
-}

apps/nextjs/src/app/api/backup/export/route.ts

@@ -52,7 +52,7 @@ export async function GET() {
     const date = new Date().toISOString().split("T")[0];
     const filename = `homarr-backup-${date}.zip`;
 
-    return new NextResponse(zipBuffer, {
+    return new NextResponse(new Uint8Array(zipBuffer), {
       status: 200,
       headers: {
         "Content-Type": "application/zip",

apps/nextjs/src/app/api/mcp/[transport]/route.spec.ts

@@ -22,7 +22,10 @@ vi.mock("@homarr/auth/api-key", () => ({
   API_KEY_HEADER_NAME: "ApiKey",
   getSessionFromApiKeyAsync: mocks.authenticate,
 }));
-vi.mock("@homarr/common", () => ({ extractBaseUrlFromHeaders: () => "http://localhost" }));
+vi.mock("@homarr/common", () => ({
+  extractBaseUrlFromHeaders: () => "http://localhost",
+  removeTrailingSlash: (value: string) => value.replace(/\/+$/u, ""),
+}));
 vi.mock("@homarr/common/server", () => ({ ipAddressFromHeaders: mocks.ipAddress }));
 vi.mock("@homarr/core/infrastructure/logs", () => ({
   createLogger: () => ({ info: vi.fn(), warn: mocks.loggerWarn, error: vi.fn() }),
@@ -42,6 +45,7 @@ vi.mock("@homarr/custom-widgets/core", () => ({
   getCustomWidgetJsonSchema: () => ({ type: "object", title: "Custom Widget" }),
 }));
 vi.mock("@homarr/db", () => ({ db: {} }));
+vi.mock("~/env", () => ({ env: { BASE_URL: undefined } }));
 vi.mock("~/versions/package-reader", () => ({ getPackageVersion: () => "test-version" }));
 vi.mock("../_extract-tools", () => ({
   extractMcpTools: () => [

apps/nextjs/src/app/api/mcp/_base-url.ts

@@ -0,0 +1,8 @@
+import { extractBaseUrlFromHeaders, removeTrailingSlash } from "@homarr/common";
+
+import { env } from "~/env";
+
+type RequestHeaders = Parameters<typeof extractBaseUrlFromHeaders>[0];
+
+export const getMcpBaseUrl = (headers: RequestHeaders) =>
+  removeTrailingSlash(env.BASE_URL ?? extractBaseUrlFromHeaders(headers));

apps/nextjs/src/app/api/mcp/_handler.ts

@@ -7,7 +7,7 @@ import { z } from "zod/v4";
 import type { McpTool } from "@homarr/api/mcp";
 import { createTRPCContext, mcpRouter } from "@homarr/api/mcp";
 import { API_KEY_HEADER_NAME, getSessionFromApiKeyAsync } from "@homarr/auth/api-key";
-import { extractBaseUrlFromHeaders } from "@homarr/common";
+import { removeTrailingSlash } from "@homarr/common";
 import { ipAddressFromHeaders } from "@homarr/common/server";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { buildCustomWidgetMcpPrompt } from "@homarr/custom-widgets/authoring-prompt";
@@ -24,6 +24,7 @@ import { db } from "@homarr/db";
 
 import { getPackageVersion } from "~/versions/package-reader";
 import { getSafeAssistantToolError } from "../assistant/chat/assistant-tool-error";
+import { getMcpBaseUrl } from "./_base-url";
 import { extractMcpTools } from "./_extract-tools";
 import { createMcpProtocolHandler } from "./_protocol";
 
@@ -246,6 +247,12 @@ function jsonErrorResponse(status: number, body: Record<string, string>, extraHe
   });
 }
 
+const getOAuthChallenge = (req: NextRequest) => {
+  const baseUrl = getMcpBaseUrl(req.headers);
+  const resourcePath = removeTrailingSlash(new URL(req.url).pathname);
+  return `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource${resourcePath}"`;
+};
+
 export const handleMcpRequest = async (req: NextRequest) => {
   const pathname = new URL(req.url).pathname;
   if (pathname.endsWith("/sse") || pathname.endsWith("/message")) {
@@ -269,30 +276,37 @@ export const handleMcpRequest = async (req: NextRequest) => {
 
   if (!apiKeyValue) {
     recordAuthFailure(ipAddress);
-    const baseUrl = extractBaseUrlFromHeaders(req.headers);
     return jsonErrorResponse(
       401,
       {
         error: "unauthorized",
         hint: "Authenticate with an ApiKey header or via OAuth at /.well-known/oauth-authorization-server",
       },
-      { "WWW-Authenticate": `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"` },
+      { "WWW-Authenticate": getOAuthChallenge(req) },
     );
   }
 
   if (!apiKeyValue.includes(".")) {
     recordAuthFailure(ipAddress);
-    return jsonErrorResponse(401, { error: "invalid_token", hint: "The token must be in the format '<id>.<token>'." });
+    return jsonErrorResponse(
+      401,
+      { error: "invalid_token", hint: "The token must be in the format '<id>.<token>'." },
+      { "WWW-Authenticate": getOAuthChallenge(req) },
+    );
   }
 
   const session = await getSessionFromApiKeyAsync(db, apiKeyValue, ipAddress, ua);
 
   if (!session) {
     recordAuthFailure(ipAddress);
-    return jsonErrorResponse(401, {
-      error: "invalid_token",
-      hint: "The API key was not found or the token is incorrect.",
-    });
+    return jsonErrorResponse(
+      401,
+      {
+        error: "invalid_token",
+        hint: "The API key was not found or the token is incorrect.",
+      },
+      { "WWW-Authenticate": getOAuthChallenge(req) },
+    );
   }
 
   clearAuthFailures(ipAddress);

apps/nextjs/src/app/api/mcp/oauth/authorize/route.ts

@@ -1,8 +1,8 @@
 import type { NextRequest } from "next/server";
 
 import { auth } from "@homarr/auth/next";
-import { extractBaseUrlFromHeaders } from "@homarr/common";
 
+import { getMcpBaseUrl } from "../../_base-url";
 import { consumePendingAuth, createAuthCode, getClient, storePendingAuth } from "../_store";
 
 export async function GET(req: NextRequest) {
@@ -83,8 +83,9 @@ export async function GET(req: NextRequest) {
     );
   }
 
-  const expectedResource = `${extractBaseUrlFromHeaders(req.headers)}/api/mcp`;
-  if (resource && resource !== expectedResource) {
+  const baseUrl = getMcpBaseUrl(req.headers);
+  const allowedResources = new Set([`${baseUrl}/api/mcp`, `${baseUrl}/api/mcp/mcp`]);
+  if (resource && !allowedResources.has(resource)) {
     return Response.json(
       {
         error: "invalid_target",
@@ -152,7 +153,7 @@ export async function GET(req: NextRequest) {
     );
   }
 
-  const loginUrl = new URL("/auth/login", url.origin);
+  const loginUrl = new URL("/auth/login", baseUrl);
   loginUrl.searchParams.set("callbackUrl", `/api/mcp/oauth/authorize?pending=${id}`);
   return Response.redirect(loginUrl.toString());
 }

apps/nextjs/src/app/well-known/[...path]/route.ts

@@ -0,0 +1,51 @@
+import type { NextRequest } from "next/server";
+
+import { getMcpBaseUrl } from "~/app/api/mcp/_base-url";
+
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*",
+};
+
+export async function GET(req: NextRequest, props: { params: Promise<{ path: string[] }> }) {
+  const [kind, ...rest] = (await props.params).path;
+  const baseUrl = getMcpBaseUrl(req.headers);
+  const identifierPath = rest.join("/");
+
+  if (kind === "oauth-authorization-server") {
+    const issuer = identifierPath ? `${baseUrl}/${identifierPath}` : baseUrl;
+    return Response.json(
+      {
+        issuer,
+        authorization_endpoint: `${baseUrl}/api/mcp/oauth/authorize`,
+        token_endpoint: `${baseUrl}/api/mcp/oauth/token`,
+        registration_endpoint: `${baseUrl}/api/mcp/oauth/register`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        scopes_supported: ["mcp:tools"],
+        resource_indicators_supported: true,
+      },
+      { headers: corsHeaders },
+    );
+  }
+
+  if (kind === "oauth-protected-resource") {
+    const resource = identifierPath ? `${baseUrl}/${identifierPath}` : `${baseUrl}/api/mcp`;
+    return Response.json(
+      {
+        resource,
+        authorization_servers: [baseUrl],
+      },
+      { headers: corsHeaders },
+    );
+  }
+
+  return Response.json({ error: "not_found" }, { status: 404, headers: corsHeaders });
+}
+
+export async function OPTIONS() {
+  return new Response(null, { status: 204, headers: corsHeaders });
+}

apps/nextjs/src/components/backup/database-restore-flow.tsx

@@ -204,8 +204,12 @@ export const DatabaseRestoreFlow = ({ variant = "card", onRestoreComplete }: Dat
     }
 
     onRestoreComplete?.();
-    const destination =
-      variant === "standalone" && homeBoardName ? `/boards/${encodeURIComponent(homeBoardName)}` : null;
+    let destination: string | null = null;
+    if (variant === "standalone" && homeBoardName) {
+      destination = `/boards/${encodeURIComponent(homeBoardName)}`;
+    } else if (variant === "card") {
+      destination = "/auth/login";
+    }
     startReadinessCheck(restartAfterMs, destination);
   }, [file, onRestoreComplete, startReadinessCheck, t, variant]);
 
@@ -317,6 +321,7 @@ export const DatabaseRestoreFlow = ({ variant = "card", onRestoreComplete }: Dat
       <RestoreProgressPanel
         active
         status={restoreStatus}
+        reloginRequired={variant === "card"}
         onRetry={() => startReadinessCheck(0)}
         onReload={() => window.location.reload()}
       />

apps/nextjs/src/components/backup/restore-progress-panel.tsx

@@ -11,11 +11,18 @@ export type RestoreProgressStatus = "restoring" | "restarting" | "timedOut";
 interface RestoreProgressPanelProps {
   active: boolean;
   status: RestoreProgressStatus;
+  reloginRequired?: boolean;
   onRetry: () => void;
   onReload: () => void;
 }
 
-export const RestoreProgressPanel = ({ active, status, onRetry, onReload }: RestoreProgressPanelProps) => {
+export const RestoreProgressPanel = ({
+  active,
+  status,
+  reloginRequired = false,
+  onRetry,
+  onReload,
+}: RestoreProgressPanelProps) => {
   const t = useI18n("management.page.tool.backup.restore");
   const tCommon = useI18n("common");
   const reduceMotion = useReducedMotion();
@@ -63,6 +70,12 @@ export const RestoreProgressPanel = ({ active, status, onRetry, onReload }: Rest
           </div>
         </Group>
 
+        {reloginRequired && !isRestoring ? (
+          <Text size="sm" c="dimmed">
+            {t("progress.relogin")}
+          </Text>
+        ) : null}
+
         {isTimedOut ? (
           <Group>
             <Button variant="light" onClick={onRetry} leftSection={<IconRefresh size={16} />}>

apps/nextjs/src/env.ts

@@ -16,8 +16,15 @@ const publicHttpUrl = (variableName: string) =>
     }
   });
 
+const publicHttpOrigin = (variableName: string) =>
+  publicHttpUrl(variableName).refine(
+    (value) => value === new URL(value).origin,
+    `${variableName} must be an HTTP(S) origin without a path`,
+  );
+
 export const env = createEnv({
   server: {
+    BASE_URL: publicHttpOrigin("BASE_URL").optional(),
     UNSAFE_ENABLE_MOCK_INTEGRATION: createBooleanSchema(false),
     DEMO_MODE: createBooleanSchema(false),
     DEMO_READ_ONLY: createBooleanSchema(true),

docs/README.md

@@ -62,378 +62,378 @@
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/adguard-home" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/adguard-home.svg" alt="AdGuard Home" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">AdGuard<br/>Home</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/anchor" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/anchor.svg" alt="Anchor" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Anchor</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/archiveteam-warrior" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/selfhst/icons/png/archiveteam-warrior.png" alt="ArchiveTeam Warrior" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">ArchiveTeam<br/>Warrior</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/aria2" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/PapirusDevelopmentTeam/papirus_icons@latest/src/system_downloads_3.svg" alt="Aria2" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Aria2</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/audiobookshelf" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/audiobookshelf.svg" alt="Audiobookshelf" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Audiobookshelf</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/bazarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/bazarr.svg" alt="Bazarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Bazarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/beszel" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/beszel.svg" alt="Beszel" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Beszel</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/coolify" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/coolify.svg" alt="Coolify" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Coolify</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/dash-dot" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/dashdot.png" alt="Dash." width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Dash.</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/deluge" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/deluge.svg" alt="Deluge" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Deluge</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/emby" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/emby.svg" alt="Emby" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Emby</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/glances" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/glances.svg" alt="Glances" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Glances</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/gluetun" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/gluetun.svg" alt="Gluetun" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Gluetun</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/gotify" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/gotify.svg" alt="Gotify" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Gotify</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/home-assistant" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/home-assistant.svg" alt="Home Assistant" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Home<br/>Assistant</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/ical" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/ical.svg" alt="iCal" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">iCal</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/immich" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/immich.svg" alt="Immich" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Immich</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/jellyfin" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/jellyfin.svg" alt="Jellyfin" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Jellyfin</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/jellyseerr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/jellyseerr.svg" alt="Jellyseerr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Jellyseerr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/lidarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/lidarr.svg" alt="Lidarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Lidarr</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/navidrome" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/navidrome.svg" alt="Navidrome" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Navidrome</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/nextcloud" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/nextcloud.svg" alt="Nextcloud" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Nextcloud</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/ntfy" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/ntfy.svg" alt="ntfy" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">ntfy</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/nzbget" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/nzbget.svg" alt="NZBGet" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">NZBGet</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/open-media-vault" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/openmediavault.svg" alt="OpenMediaVault" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">OpenMediaVault</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/opnsense" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/opnsense.svg" alt="OPNsense" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">OPNsense</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/overseerr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/overseerr.svg" alt="Overseerr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Overseerr</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/paperless-ngx" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/paperless-ngx.svg" alt="Paperless-ngx" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Paperless-ngx</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/patchmon" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/patchmon.svg" alt="PatchMon" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">PatchMon</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/peanut" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/peanut.svg" alt="PeaNUT" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">PeaNUT</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/pi-hole" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/pi-hole.svg" alt="Pi-hole" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Pi-hole</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/plex" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/plex.svg" alt="Plex" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Plex</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/prowlarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/prowlarr.svg" alt="Prowlarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Prowlarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/proxmox" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/proxmox.svg" alt="Proxmox" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Proxmox</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/q-bittorent" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/qbittorrent.svg" alt="qBittorrent" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">qBittorrent</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/radarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/radarr.svg" alt="Radarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Radarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/readarr" target="_blank" rel="noreferrer noopener">
-  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/readarr.svg" alt="Readarr" width="90" height="90" />
-  <br/>  
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@main/png/readarr.png" alt="Readarr" width="90" height="90" />
+  <br/>
   <p align="center">Readarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/sabnzbd" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/sabnzbd.svg" alt="SABnzbd" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">SABnzbd</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/seerr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/seerr.svg" alt="Seerr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Seerr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/slskd" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/slskd.svg" alt="Slskd" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Slskd</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/sonarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/sonarr.svg" alt="Sonarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Sonarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/speedtest-tracker" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/speedtest-tracker.png" alt="Speedtest Tracker" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Speedtest<br/>Tracker</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/synology" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/synology.svg" alt="Synology DiskStation" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Synology<br/>DiskStation</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/tdarr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/tdarr.png" alt="Tdarr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Tdarr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/technitium-dns" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/selfhst/icons/svg/technitium.svg" alt="Technitium DNS" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Technitium<br/>DNS</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/tracearr" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/tracearr.svg" alt="Tracearr" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Tracearr</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/traefik" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/traefik.svg" alt="Traefik" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Traefik</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/transmission" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/transmission.svg" alt="Transmission" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Transmission</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/truenas" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/truenas.svg" alt="TrueNAS" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">TrueNAS</p>
 </a>
 </td></tr>
 <tr><td align="center">
 <a href="https://homarr.dev/docs/integrations/umami" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/umami.svg" alt="Umami" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Umami</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/unifi-controller" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/unifi.png" alt="Unifi Controller" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Unifi<br/>Controller</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/unraid" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/unraid.svg" alt="Unraid" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Unraid</p>
 </a>
 </td>
 <td align="center">
-<a href="null" target="_blank" rel="noreferrer noopener">
+<a href="https://homarr.dev/docs/integrations/uptime-kuma" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/uptime-kuma.svg" alt="Uptime Kuma" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">Uptime<br/>Kuma</p>
 </a>
 </td>
 <td align="center">
 <a href="https://homarr.dev/docs/integrations/whats-up-docker" target="_blank" rel="noreferrer noopener">
   <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/whats-up-docker.svg" alt="What's Up Docker" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">What's<br/>Up<br/>Docker</p>
 </a>
 </td></tr>

packages/api/src/router/location.ts

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 
+import { env } from "@homarr/common/env";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
 import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
@@ -37,6 +38,8 @@ export const locationRouter = createTRPCRouter({
     .input(locationSearchCityInput)
     .output(locationSearchCityOutput)
     .query(async ({ input }) => {
+      if (env.NO_EXTERNAL_CONNECTION) return { results: [] };
+
       const url = new URL("https://geocoding-api.open-meteo.com/v1/search");
       url.searchParams.set("name", input.query);
       const res = await withTimeoutAsync(async (signal) => {

packages/auth/events.ts

@@ -9,7 +9,7 @@ import { groupMembers, groups, users } from "@homarr/db/schema";
 import { colorSchemeCookieKey, everyoneGroup } from "@homarr/definitions";
 
 import { env } from "./env";
-import { extractProfileName } from "./providers/oidc/oidc-provider";
+import { extractProfileName, getProfileValueByPath } from "./providers/oidc/profile";
 
 const logger = createLogger({ module: "authEvents" });
 
@@ -31,16 +31,11 @@ export const createSignInEventHandler = (db: Database): Exclude<NextAuthConfig["
     if (!dbUser) throw new Error("User not found");
 
     const groupsKey = env.AUTH_OIDC_GROUPS_ATTRIBUTE;
+    const profileGroups = profile ? getProfileValueByPath(profile, groupsKey) : undefined;
     // Groups from oidc provider are provided from the profile, it's not typed.
-    if (
-      !env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT &&
-      dbUser.provider === "oidc" &&
-      profile &&
-      groupsKey in profile &&
-      Array.isArray(profile[groupsKey])
-    ) {
-      logger.debug(`Using profile groups (${groupsKey}): ${JSON.stringify(profile[groupsKey])}`);
-      await synchronizeGroupsWithExternalForUserAsync(db, user.id, profile[groupsKey] as string[]);
+    if (!env.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT && dbUser.provider === "oidc" && Array.isArray(profileGroups)) {
+      logger.debug(`Using profile groups (${groupsKey}): ${JSON.stringify(profileGroups)}`);
+      await synchronizeGroupsWithExternalForUserAsync(db, user.id, profileGroups as string[]);
     }
 
     // In ldap-authroization we return the groups from ldap, it's not typed.

packages/auth/providers/oidc/oidc-provider.ts

@@ -7,6 +7,7 @@ import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/h
 
 import { env } from "../../env";
 import { createRedirectUri } from "../../redirect";
+import { extractProfileName } from "./profile";
 import { assertVerifiedEmailForCredentialsLinking } from "./verified-email";
 
 export const OidcProvider = (headers: ReadonlyHeaders | null): OIDCConfig<Profile> => ({
@@ -76,12 +77,3 @@ export const OidcProvider = (headers: ReadonlyHeaders | null): OIDCConfig<Profil
   // @ts-expect-error `undici` has a `duplex` option
   [customFetch]: fetchWithTrustedCertificatesAsync,
 });
-
-export const extractProfileName = (profile: Profile) => {
-  if (!env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE) {
-    // Use the name as the username if the preferred_username is an email address
-    return profile.preferred_username?.includes("@") ? profile.name : profile.preferred_username;
-  }
-
-  return profile[env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE as keyof typeof profile] as string;
-};

packages/auth/providers/oidc/profile.ts

@@ -0,0 +1,23 @@
+import type { Profile } from "@auth/core/types";
+
+import { env } from "../../env";
+
+export const getProfileValueByPath = (profile: Profile, path: string): unknown => {
+  return path.split(".").reduce<unknown>((value, key) => {
+    if (typeof value !== "object" || value === null || !Object.hasOwn(value, key)) {
+      return undefined;
+    }
+
+    return (value as Record<string, unknown>)[key];
+  }, profile);
+};
+
+export const extractProfileName = (profile: Profile): string | undefined => {
+  if (!env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE) {
+    // Use the name as the username if the preferred_username is an email address
+    return (profile.preferred_username?.includes("@") ? profile.name : profile.preferred_username) ?? undefined;
+  }
+
+  const profileName = getProfileValueByPath(profile, env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE);
+  return typeof profileName === "string" ? profileName : undefined;
+};

packages/auth/providers/oidc/test/profile.spec.ts

@@ -0,0 +1,96 @@
+import type { Profile } from "@auth/core/types";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+const mockEnv = vi.hoisted(() => ({
+  AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE: undefined as string | undefined,
+}));
+
+vi.mock("../../../env", () => ({ env: mockEnv }));
+
+import { extractProfileName, getProfileValueByPath } from "../profile";
+
+afterEach(() => {
+  mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = undefined;
+});
+
+describe("getProfileValueByPath", () => {
+  const profile = {
+    sub: "user-id",
+    resource_access: {
+      homarr: {
+        roles: ["admins"],
+      },
+    },
+  } satisfies Profile;
+
+  test("returns a top-level claim", () => {
+    expect(getProfileValueByPath(profile, "sub")).toBe("user-id");
+  });
+
+  test("returns a nested claim", () => {
+    expect(getProfileValueByPath(profile, "resource_access.homarr.roles")).toEqual(["admins"]);
+  });
+
+  test("returns undefined when the path does not exist", () => {
+    expect(getProfileValueByPath(profile, "resource_access.missing.roles")).toBeUndefined();
+  });
+});
+
+describe("extractProfileName", () => {
+  test("uses preferred_username when overwrite is not set", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "johndoe",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("johndoe");
+  });
+
+  test("uses name when preferred_username is an email", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "john@example.com",
+      name: "John Doe",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("John Doe");
+  });
+
+  test("returns undefined when the fallback name is null", () => {
+    const profile = {
+      sub: "user-id",
+      preferred_username: "john@example.com",
+      name: null,
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+
+  test("returns undefined when preferred_username is missing", () => {
+    const profile = {
+      sub: "user-id",
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+
+  test("uses a nested name claim when configured", () => {
+    mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = "user.profile.display_name";
+    const profile = {
+      sub: "user-id",
+      user: { profile: { display_name: "Nested User" } },
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBe("Nested User");
+  });
+
+  test("returns undefined when the configured claim is not a string", () => {
+    mockEnv.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE = "user.profile";
+    const profile = {
+      sub: "user-id",
+      user: { profile: { display_name: "Nested User" } },
+    } satisfies Profile;
+
+    expect(extractProfileName(profile)).toBeUndefined();
+  });
+});

packages/auth/test/events.spec.ts

@@ -1,7 +1,7 @@
 import type { ResponseCookie } from "next/dist/compiled/@edge-runtime/cookies";
 import type { ReadonlyRequestCookies } from "next/dist/server/web/spec-extension/adapters/request-cookies";
 import { cookies } from "next/headers";
-import { describe, expect, test, vi } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { eq } from "@homarr/db";
 import type { Database } from "@homarr/db";
@@ -21,6 +21,12 @@ vi.mock("../env", () => {
     env: mockEnv,
   };
 });
+
+afterEach(() => {
+  mockEnv.AUTH_OIDC_GROUPS_ATTRIBUTE = "someRandomGroupsKey";
+  mockEnv.AUTH_OIDC_GROUPS_LOCAL_MANAGEMENT = false;
+});
+
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 type HeadersExport = typeof import("next/headers");
 vi.mock("next/headers", async (importOriginal) => {
@@ -152,6 +158,30 @@ describe("createSignInEventHandler should create signInEventHandler", () => {
       });
       expect(dbGroupMembers?.groupId).toBe("1");
     });
+    test("should add missing group membership from a nested claim", async () => {
+      // Arrange
+      mockEnv.AUTH_OIDC_GROUPS_ATTRIBUTE = "resource_access.homarr.roles";
+      const db = createDb();
+      await createUserAsync(db, "oidc");
+      await createGroupAsync(db);
+      const eventHandler = createSignInEventHandler(db);
+
+      // Act
+      await eventHandler?.({
+        user: { id: "1", name: "test" },
+        profile: {
+          preferred_username: "test",
+          resource_access: { homarr: { roles: ["test"] } },
+        },
+        account: null,
+      });
+
+      // Assert
+      const dbGroupMembers = await db.query.groupMembers.findFirst({
+        where: eq(groupMembers.userId, "1"),
+      });
+      expect(dbGroupMembers?.groupId).toBe("1");
+    });
     test("should remove group membership", async () => {
       // Arrange
       const db = createDb();

packages/integrations/src/nextcloud/nextcloud-url.ts

@@ -0,0 +1,13 @@
+export const createNextcloudCalendarServerUrl = (integrationUrl: string) => {
+  const calendarServerUrl = new URL(integrationUrl);
+  const integrationPath = calendarServerUrl.pathname.replace(/\/+$/, "");
+  const davPath = "/remote.php/dav";
+
+  calendarServerUrl.pathname = integrationPath.endsWith(davPath)
+    ? `${integrationPath}/`
+    : `${integrationPath}${davPath}/`;
+  calendarServerUrl.search = "";
+  calendarServerUrl.hash = "";
+
+  return calendarServerUrl.toString();
+};

packages/integrations/src/nextcloud/nextcloud.integration.ts

@@ -21,6 +21,7 @@ import type { ICalendarIntegration } from "../interfaces/calendar/calendar-integ
 import type { CalendarEvent } from "../interfaces/calendar/calendar-types";
 import type { Notification } from "../interfaces/notifications/notification-types";
 import type { INotificationsIntegration } from "../interfaces/notifications/notifications-integration";
+import { createNextcloudCalendarServerUrl } from "./nextcloud-url";
 
 // Register all existing timezones
 if (ICAL.TimezoneService.count === 0) {
@@ -189,7 +190,7 @@ export class NextcloudIntegration extends Integration implements ICalendarIntegr
 
   private async createCalendarClientAsync(agent?: Agent) {
     return new DAVClient({
-      serverUrl: this.integration.url,
+      serverUrl: createNextcloudCalendarServerUrl(this.integration.url),
       credentials: {
         username: this.getSecretValue("username"),
         password: this.getSecretValue("password"),

packages/integrations/src/nextcloud/test/nextcloud-integration.spec.ts

@@ -0,0 +1,38 @@
+import type { Agent } from "node:https";
+import { DAVClient } from "tsdav";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { NextcloudIntegration } from "../nextcloud.integration";
+
+vi.mock("tsdav", () => ({ DAVClient: vi.fn() }));
+
+interface NextcloudCalendarClientFactory {
+  createCalendarClientAsync(agent: Agent): Promise<unknown>;
+}
+
+describe("NextcloudIntegration", () => {
+  beforeEach(() => {
+    vi.mocked(DAVClient).mockClear();
+  });
+
+  test("uses a calendar server URL that preserves the integration subpath", async () => {
+    const integration = new NextcloudIntegration({
+      id: "integration-id",
+      name: "Nextcloud",
+      url: "https://example.com/nextcloud",
+      externalUrl: null,
+      decryptedSecrets: [
+        { kind: "username", value: "admin" },
+        { kind: "password", value: "password" },
+      ],
+    });
+
+    await (integration as unknown as NextcloudCalendarClientFactory).createCalendarClientAsync({} as Agent);
+
+    expect(DAVClient).toHaveBeenCalledWith(
+      expect.objectContaining({
+        serverUrl: "https://example.com/nextcloud/remote.php/dav/",
+      }),
+    );
+  });
+});

packages/integrations/src/nextcloud/test/nextcloud-url.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "vitest";
+
+import { createNextcloudCalendarServerUrl } from "../nextcloud-url";
+
+describe("createNextcloudCalendarServerUrl", () => {
+  test("uses the DAV endpoint for a root installation", () => {
+    expect(createNextcloudCalendarServerUrl("https://cloud.example.com")).toBe(
+      "https://cloud.example.com/remote.php/dav/",
+    );
+  });
+
+  test("preserves the base path for a subpath installation", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+
+  test("does not duplicate a trailing slash", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+
+  test("does not duplicate an existing DAV endpoint", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/remote.php/dav")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+});

packages/integrations/src/unifi-controller/test/unifi-controller-integration.spec.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test, vi } from "vitest";
+
+vi.hoisted(() => {
+  process.env.SKIP_ENV_VALIDATION = "true";
+  process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
+  process.env.ENABLE_DNS_CACHING = "false";
+});
+
+const controllerCtor = vi.fn();
+const controllerLogin = vi.fn().mockResolvedValue(true);
+
+vi.mock("@homarr/redis", () => ({
+  createGetSetChannel: () => ({
+    getAsync: vi.fn().mockResolvedValue(null),
+    setAsync: vi.fn().mockResolvedValue(undefined),
+    removeAsync: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+vi.mock("@homarr/core/infrastructure/logs", () => ({
+  createLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+  ErrorWithMetadata: class extends Error {},
+}));
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  createCustomCheckServerIdentity: () => (() => undefined) as never,
+  fetchWithTrustedCertificatesAsync: vi.fn(),
+  createAxiosCertificateInstanceAsync: vi.fn().mockResolvedValue({}),
+  createCertificateAgentAsync: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@homarr/core/infrastructure/certificates", () => ({
+  getTrustedCertificateHostnamesAsync: vi.fn().mockResolvedValue([]),
+  getAllTrustedCertificatesAsync: vi.fn().mockResolvedValue([]),
+}));
+
+vi.mock("axios", () => ({
+  AxiosError: Error,
+  default: {
+    create: vi.fn().mockReturnValue({}),
+  },
+}));
+
+vi.mock("http-cookie-agent/http", () => ({
+  HttpCookieAgent: class {},
+  HttpsCookieAgent: class {},
+}));
+
+vi.mock("@homarr/node-unifi", () => {
+  class FakeController {
+    public options: Record<string, unknown>;
+    constructor(options: Record<string, unknown>) {
+      this.options = options;
+      controllerCtor(options);
+    }
+    public async login(): Promise<true> {
+      return await controllerLogin(this.options.port);
+    }
+    public async getSitesStats(): Promise<unknown[]> {
+      return [];
+    }
+  }
+  return { default: { Controller: FakeController } };
+});
+
+import { UnifiControllerIntegration } from "../unifi-controller-integration";
+
+const createIntegration = (url: string) =>
+  new UnifiControllerIntegration({
+    id: "test-unifi",
+    name: "Test Unifi",
+    url,
+    externalUrl: null,
+    decryptedSecrets: [
+      { kind: "username", value: "admin" },
+      { kind: "password", value: "secret" },
+    ],
+  });
+
+describe("UnifiControllerIntegration port resolution", () => {
+  test("a URL without a port uses the UniFi OS port 443", async () => {
+    controllerCtor.mockClear();
+    controllerLogin.mockClear().mockResolvedValue(true);
+    await createIntegration("http://192.168.1.1").getNetworkSummaryAsync();
+
+    expect(controllerCtor).toHaveBeenCalledTimes(1);
+    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 443 }));
+  });
+
+  test("a connection failure on port 443 falls back to the self-hosted controller port 8443", async () => {
+    controllerCtor.mockClear();
+    controllerLogin
+      .mockClear()
+      .mockRejectedValueOnce(Object.assign(new Error("connect ECONNREFUSED"), { isAxiosError: true }))
+      .mockResolvedValueOnce(true);
+
+    await createIntegration("http://controller.lan").getNetworkSummaryAsync();
+
+    expect(controllerCtor).toHaveBeenNthCalledWith(1, expect.objectContaining({ port: 443 }));
+    expect(controllerCtor).toHaveBeenNthCalledWith(2, expect.objectContaining({ port: 8443 }));
+  });
+
+  test("https://controller.lan:8443 keeps the user-specified port", async () => {
+    controllerCtor.mockClear();
+    controllerLogin.mockClear().mockResolvedValue(true);
+    await createIntegration("https://controller.lan:8443").getNetworkSummaryAsync();
+
+    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "controller.lan", port: 8443 }));
+  });
+
+  test("https://192.168.1.1:8443 keeps the user-specified port", async () => {
+    controllerCtor.mockClear();
+    controllerLogin.mockClear().mockResolvedValue(true);
+    await createIntegration("https://192.168.1.1:8443").getNetworkSummaryAsync();
+
+    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 8443 }));
+  });
+
+  test("an unusual port like 10443 is honored verbatim", async () => {
+    controllerCtor.mockClear();
+    controllerLogin.mockClear().mockResolvedValue(true);
+    await createIntegration("https://192.168.1.1:10443").getNetworkSummaryAsync();
+
+    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 10443 }));
+  });
+
+  test("an authentication failure on port 443 does not try another port", async () => {
+    controllerCtor.mockClear();
+    controllerLogin.mockClear().mockRejectedValueOnce(
+      Object.assign(new Error("Request failed with status code 401"), {
+        isAxiosError: true,
+        response: { status: 401 },
+      }),
+    );
+
+    await expect(createIntegration("https://controller.lan").getNetworkSummaryAsync()).rejects.toThrow();
+
+    expect(controllerCtor).toHaveBeenCalledTimes(1);
+    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ port: 443 }));
+  });
+});

packages/integrations/src/unifi-controller/unifi-controller-integration.ts

@@ -2,7 +2,6 @@ import type tls from "node:tls";
 import axios from "axios";
 import { HttpCookieAgent, HttpsCookieAgent } from "http-cookie-agent/http";
 
-import { getPortFromUrl } from "@homarr/common";
 import {
   getAllTrustedCertificatesAsync,
   getTrustedCertificateHostnamesAsync,
@@ -67,26 +66,53 @@ export class UnifiControllerIntegration extends Integration implements NetworkCo
       checkServerIdentity: createCustomCheckServerIdentity(await getTrustedCertificateHostnamesAsync()),
     };
 
-    const client = new Unifi.Controller({
-      host: url.hostname,
-      port: getPortFromUrl(url),
-      username: this.getSecretValue("username"),
-      password: this.getSecretValue("password"),
-      createAxiosInstance({ cookies }) {
-        return axios.create({
-          adapter: "http",
-          httpAgent: new HttpCookieAgent({ cookies }),
-          httpsAgent: new HttpsCookieAgent({
-            cookies,
-            requestCert: true,
-            ...certificateOptions,
-          }),
-        });
-      },
-    });
+    // node-unifi always connects over HTTPS, regardless of the protocol in the
+    // integration URL. UniFi OS consoles use port 443 while self-hosted controllers normally
+    // use 8443. If no port was provided, try both without hiding authentication errors.
+    const ports = url.port ? [Number(url.port)] : [443, 8443];
+    const createClientForPortAsync = async (port: number) => {
+      const client = new Unifi.Controller({
+        host: url.hostname,
+        port,
+        username: this.getSecretValue("username"),
+        password: this.getSecretValue("password"),
+        createAxiosInstance({ cookies }) {
+          return axios.create({
+            adapter: "http",
+            httpAgent: new HttpCookieAgent({ cookies }),
+            httpsAgent: new HttpsCookieAgent({
+              cookies,
+              requestCert: true,
+              ...certificateOptions,
+            }),
+          });
+        },
+      });
 
-    await client.login(this.getSecretValue("username"), this.getSecretValue("password"), null);
-    return client;
+      await client.login(this.getSecretValue("username"), this.getSecretValue("password"), null);
+      return client;
+    };
+
+    for (const [index, port] of ports.entries()) {
+      try {
+        return await createClientForPortAsync(port);
+      } catch (error) {
+        const isLastPort = index === ports.length - 1;
+        if (isLastPort || !this.isPortFallbackError(error)) {
+          throw error;
+        }
+      }
+    }
+
+    throw new Error("Unable to connect to the UniFi controller");
+  }
+
+  private isPortFallbackError(error: unknown) {
+    if (typeof error === "object" && error !== null && "isAxiosError" in error && error.isAxiosError === true) {
+      return !("response" in error) || error.response === undefined;
+    }
+
+    return error instanceof Error && error.message === "failed to detect UniFiOS status";
   }
 
   private getStatusValueOverAllSites<S extends HealthSubsystem>(

packages/integrations/src/unraid/unraid-integration.ts

@@ -39,9 +39,8 @@ export class UnraidIntegration extends Integration implements ISystemHealthMonit
     const cpuUtilization = systemInfo.metrics.cpu.cpus.reduce((acc, val) => acc + val.percentTotal, 0);
     const cpuCount = systemInfo.info.cpu.cores;
 
-    // We use "info" object instead of the stats since this is the exact amount the kernel sees, which is what Unraid displays.
-    const totalMemory = systemInfo.info.memory.layout.reduce((acc, layout) => layout.size + acc, 0);
-    const usedMemory = totalMemory * (systemInfo.metrics.memory.percentTotal / 100);
+    const totalMemory = systemInfo.metrics.memory.total;
+    const usedMemory = Math.max(totalMemory - systemInfo.metrics.memory.available, 0);
     const uptime = dayjs(systemInfo.info.os.uptime);
 
     return {
@@ -136,11 +135,6 @@ export class UnraidIntegration extends Integration implements ISystemHealthMonit
             brand,
             cores,
             threads
-          },
-          memory {
-            layout {
-              size     
-            }
           }
         }
       }

packages/integrations/src/unraid/unraid-types.ts

@@ -60,13 +60,6 @@ export const unraidSystemInfoSchema = z.object({
       cores: z.number(),
       threads: z.number(),
     }),
-    memory: z.object({
-      layout: z.array(
-        z.object({
-          size: z.number(),
-        }),
-      ),
-    }),
   }),
 });
 

packages/request-handler/src/docker.ts

@@ -481,13 +481,14 @@ export function calculateCpuUsage(stats: ContainerStats): number {
     return 0;
   }
 
-  const numberOfCpus = stats.cpu_stats.online_cpus;
-  const usage = stats.cpu_stats.system_cpu_usage;
-  if (!usage || usage === 0) {
+  const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
+  const systemDelta = (stats.cpu_stats.system_cpu_usage ?? 0) - (stats.precpu_stats?.system_cpu_usage ?? 0);
+
+  if (systemDelta <= 0 || cpuDelta < 0) {
     return 0;
   }
 
-  return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
+  return (cpuDelta / systemDelta) * 100;
 }
 
 export function calculateMemoryUsage(stats: ContainerStats): number {

packages/request-handler/src/test/docker.spec.ts

@@ -72,16 +72,16 @@ describe("calculateCpuUsage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 2000 }, system_cpu_usage: 10000 },
     });
-    // (2000 / 10000) * 4 * 100 = 80
-    expect(calculateCpuUsage(stats)).toBe(80);
+    // (2000 / 10000) * 100 = 20
+    expect(calculateCpuUsage(stats)).toBe(20);
   });
 
   test("should handle fractional CPU usage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 2, cpu_usage: { total_usage: 500 }, system_cpu_usage: 100000 },
     });
-    // (500 / 100000) * 2 * 100 = 1
-    expect(calculateCpuUsage(stats)).toBe(1);
+    // (500 / 100000) * 100 = 0.5
+    expect(calculateCpuUsage(stats)).toBe(0.5);
   });
 });
 

packages/translation/src/lang/en.json

@@ -3125,6 +3125,7 @@
         }
       },
       "currentWindSpeed": "{currentWindSpeed} {unit}",
+      "disabled": "Weather data is unavailable because outbound connections are disabled",
       "dailyForecast": {
         "sunrise": "Sunrise",
         "sunset": "Sunset",
@@ -6456,7 +6457,8 @@
             },
             "progress": {
               "title": "Restoring database...",
-              "restarting": "Restarting server"
+              "restarting": "Restarting server",
+              "relogin": "Restoring the database invalidated your current session. Homarr will send you to sign in when the server is ready."
             },
             "timeout": {
               "title": "Server did not come back online",

packages/widgets/src/downloads/component.tsx

@@ -493,6 +493,7 @@ export default function DownloadClientsWidget({
         title: t("items.name.columnTitle"),
         sortable: true,
         ellipsis: true,
+        width: 240,
         render: (record) => (
           <Tooltip
             key={displayMode}

packages/widgets/src/weather/component.tsx

@@ -1,10 +1,10 @@
 "use client";
 
-import { Box } from "@mantine/core";
+import { Box, Center, Text } from "@mantine/core";
 
 import { clientApi } from "@homarr/api/client";
+import { useI18n } from "@homarr/translation/client";
 
-import { WidgetEmptyState } from "../common/empty-state";
 import { getUsableWidgetQueryData, isInitialWidgetQueryPending } from "../common/query-state";
 import { WidgetQueryLoadingState } from "../common/query-state-indicator";
 import type { WidgetComponentProps } from "../definition";
@@ -19,6 +19,7 @@ export default function WeatherWidget({
   height,
   displayMode,
 }: WidgetComponentProps<"weather">) {
+  const t = useI18n("widget.weather");
   const input = {
     latitude: options.location.latitude,
     longitude: options.location.longitude,
@@ -27,7 +28,15 @@ export default function WeatherWidget({
   const weather = getUsableWidgetQueryData(weatherQuery);
 
   if (isInitialWidgetQueryPending(weatherQuery)) return <WidgetQueryLoadingState />;
-  if (!weather) return <WidgetEmptyState />;
+  if (!weather) {
+    return (
+      <Center h="100%" w="100%" p="sm">
+        <Text c="dimmed" size="sm" ta="center">
+          {t("disabled")}
+        </Text>
+      </Center>
+    );
+  }
 
   return (
     <Box className={classes.weatherSurface} h="100%" w="100%" pos="relative">

pnpm-workspace.yaml

@@ -14,8 +14,8 @@ catalog:
   "@codemirror/state": ^6.6.0
   "@codemirror/theme-one-dark": ^6.1.3
   "@codemirror/view": ^6.43.0
-  "@auth/core": ^0.41.2
-  "@auth/drizzle-adapter": ^1.11.2
+  "@auth/core": ^0.41.3
+  "@auth/drizzle-adapter": ^1.11.3
   "@ctrl/deluge": ^8.0.0
   "@ctrl/qbittorrent": ^9.14.0
   "@ctrl/transmission": ^7.4.0
@@ -120,7 +120,7 @@ catalog:
   "@xterm/addon-canvas": ^0.7.0
   "@xterm/addon-fit": 0.11.0
   "@xterm/xterm": ^6.0.0
-  adm-zip: 0.5.18
+  adm-zip: 0.6.0
   acorn: ^8.16.0
   acorn-jsx: ^5.3.2
   jszip: ^3.10.1
@@ -151,7 +151,7 @@ catalog:
   drizzle-zod: ^0.8.3
   embla-carousel-react: ^8.6.0
   esbuild: ^0.28.0
-  fast-xml-parser: ^5.9.3
+  fast-xml-parser: ^5.10.1
   fastify: ^5.9.0
   flag-icons: ^7.5.0
   glob: ^13.0.6
@@ -174,7 +174,7 @@ catalog:
   maria2: ^0.4.1
   mysql2: 3.22.6
   next: 16.3.1
-  next-auth: 5.0.0-beta.31
+  next-auth: 5.0.0-beta.32
   next-intl: 4.13.1
   next-themes: ^0.4.6
   node-loader: ^2.1.0
@@ -208,7 +208,7 @@ catalog:
   turbo: ^2.10.4
   typescript: 7.0.2
   vite: ^8.1.4
-  undici: 7.28.0
+  undici: 7.29.1
   use-deep-compare-effect: ^1.8.1
   video.js: ^8.23.9
   vite-tsconfig-paths: ^6.1.1
@@ -248,25 +248,48 @@ overrides:
   "@assistant-ui/core": 0.3.7
   "@assistant-ui/store": 0.3.5
   "@assistant-ui/tap": 0.9.10
+  "@grpc/grpc-js@<1.12.7": "1.12.7"
+  "@rvf/set-get@<7.0.2": "7.0.2"
+  "@xmldom/xmldom@<0.8.15": "0.8.15"
   "assistant-cloud": 0.1.38
   "@babel/helpers@<7.26.10": ">=7.29.7"
   "@babel/runtime@<7.26.10": ">=7.29.7"
-  "axios@>=1.0.0 <1.8.2": ">=1.18.1"
-  "brace-expansion@>=2.0.0 <=2.0.1": ">=5.0.7"
-  "brace-expansion@>=1.0.0 <=1.1.11": ">=5.0.7"
+  "axios@>=1.0.0 <1.18.1": "1.18.1"
+  "brace-expansion@>=1.0.0 <1.1.18": "1.1.18"
+  "brace-expansion@>=2.0.0 <2.1.4": "2.1.4"
+  "brace-expansion@>=4.0.0 <5.0.9": "5.0.9"
+  "browserslist@<4.28.7": "4.28.7"
   "esbuild@<=0.24.2": ">=0.28.1"
+  "fast-uri@>=3.0.0 <3.1.6": "3.1.6"
+  "@ai-sdk/provider-utils>undici": "8.10.2"
+  "find-my-way@<9.6.1": "9.9.0"
   "form-data@>=4.0.0 <4.0.4": ">=4.0.6"
   "hono@<4.6.5": ">=4.12.28"
+  "immutable@>=5.0.0-beta.1 <5.1.8": "5.1.8"
+  "ip-address@<10.3.1": "10.3.1"
+  "js-yaml@>=3.0.0 <3.15.1": "3.15.1"
+  "js-yaml@>=4.0.0 <4.3.1": "4.3.1"
+  "jsdom>undici": "8.10.2"
   "linkifyjs@<4.3.2": ">=4.3.3"
+  "lodash-es@<4.17.24": "4.18.1"
+  "nanoid@>=3.0.0 <3.3.18": "3.3.18"
   "nanoid@>=4.0.0 <5.0.9": ">=5.1.16"
+  "picomatch@>=2.0.0 <2.3.2": "2.3.2"
+  "postcss@<8.5.18": "8.5.18"
   "prismjs@<1.30.0": ">=1.30.0"
-  "proxmox-api>undici": "7.28.0"
+  "protobufjs@<7.5.5": ">=7.5.5 <8"
+  "proxmox-api>undici": "7.29.1"
   "react-is": "^19.2.7"
   "rollup@>=4.0.0 <4.22.4": ">=4.62.2"
+  "serialize-javascript@<7.0.5": "7.0.5"
   "sha.js@<=2.4.11": ">=2.4.12"
+  "shell-quote@<1.8.5": "1.10.0"
+  "svgo@>=3.0.0 <3.3.4": "3.3.4"
   "tar-fs@>=3.0.0 <3.0.9": ">=3.1.3"
   "tar-fs@>=2.0.0 <2.1.3": ">=3.1.3"
   "tmp@<=0.2.3": ">=0.2.7"
+  "undici@>=7.0.0 <7.29.1": "7.29.1"
+  "undici@>=8.0.0 <8.9.0": "8.9.0"
   "vite@>=5.0.0 <=5.4.18": ">=8.1.4"
 patchedDependencies:
   "@types/node-unifi": "patches/@types__node-unifi.patch"

scripts/update-integration-list.mts

@@ -1,5 +1,9 @@
 import { readFile, writeFile } from "fs/promises";
-import { integrationDefs } from "../packages/definitions/src/integration";
+import {
+  getIntegrationDocumentationUrl,
+  integrationDefs,
+  integrationKinds,
+} from "../packages/definitions/src/integration";
 
 const FILE = "docs/README.md";
 const MAX_COLUMNS_PER_ROW = 7;
@@ -21,19 +25,29 @@ async function updateIntegrationList() {
   }
 
   // Generate the new integration list
-  const integrations = Object.values(integrationDefs)
-    .filter((def) => def.name !== "Mock")
-    .sort((a, b) => a.name.localeCompare(b.name));
+  const integrations = integrationKinds
+    .filter((kind) => kind !== "mock")
+    .map((kind) => ({
+      ...integrationDefs[kind],
+      documentationUrl: getIntegrationDocumentationUrl(kind),
+    }))
+    .toSorted((a, b) => a.name.localeCompare(b.name));
   const tableRows: string[] = [];
   let currentRow: string[] = [];
 
   integrations.forEach((integration) => {
-    currentRow.push(`<td align="center">
-<a href="${integration.documentationUrl}" target="_blank" rel="noreferrer noopener">
+    const cellBody = `
   <img src="${integration.iconUrl}" alt="${integration.name}" width="90" height="90" />
-  <br/>  
+  <br/>
   <p align="center">${integration.name.replaceAll(" ", "<br/>")}</p>
-</a>
+`;
+    let cellContent = `<div>${cellBody}</div>`;
+    if (integration.documentationUrl !== null) {
+      cellContent = `<a href="${integration.documentationUrl}" target="_blank" rel="noreferrer noopener">${cellBody}</a>`;
+    }
+
+    currentRow.push(`<td align="center">
+${cellContent}
 </td>`);
 
     if (currentRow.length === MAX_COLUMNS_PER_ROW) {
@@ -67,4 +81,7 @@ ${endMarker}`;
   await writeFile(FILE, newContent, "utf8");
 }
 
-updateIntegrationList().catch(console.error);
+updateIntegrationList().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});