From 09e653c36f23f61c124d85eeba887a3fd5ae2333 Mon Sep 17 00:00:00 2001 From: Thomas Camlong Date: Tue, 21 Jul 2026 11:48:51 +0200 Subject: [PATCH] Restore Workshop and preserve Custom Widget docs --- apps/docs/.oxlintrc.json | 3 - apps/docs/.vscode/settings.json | 11 +- apps/docs/README.md | 18 +- .../advanced/command-line/_category_.json | 2 +- .../command-line/fix-usernames/index.mdx | 2 +- .../docs/docs/advanced/command-line/index.mdx | 10 +- .../command-line/integrations/index.mdx | 5 +- .../command-line/password-recovery/index.mdx | 4 +- .../advanced/command-line/users/index.mdx | 5 +- .../docs/advanced/development/_category_.json | 13 +- .../advanced/development/getting-started.mdx | 3 +- .../docs/advanced/development/kubernetes.mdx | 2 +- .../advanced/environment-variables/index.mdx | 91 +- apps/docs/docs/advanced/icons/index.mdx | 17 +- .../advanced/keyboard-shortcuts/index.mdx | 8 +- apps/docs/docs/advanced/proxy/index.mdx | 20 +- .../running-as-different-user/index.mdx | 20 +- .../docs/advanced/single-sign-on/index.mdx | 17 +- apps/docs/docs/advanced/styling/index.mdx | 30 +- apps/docs/docs/community/donate.mdx | 6 +- apps/docs/docs/community/faq.mdx | 48 +- apps/docs/docs/community/get-in-touch.mdx | 4 +- apps/docs/docs/community/license.mdx | 3 +- apps/docs/docs/community/translations.mdx | 26 +- .../after-the-installation.mdx | 41 +- apps/docs/docs/getting-started/glossary.mdx | 3 +- apps/docs/docs/getting-started/index.mdx | 13 +- .../getting-started/installation/docker.mdx | 42 +- .../docs/getting-started/installation/helm.md | 317 +-- .../installation/home-assistant.mdx | 2 +- .../installation/portainer.mdx | 13 +- .../getting-started/installation/proxmox.mdx | 6 +- .../getting-started/installation/qnap.mdx | 2 +- .../getting-started/installation/runtipi.mdx | 17 +- .../getting-started/installation/saltbox.mdx | 3 +- .../getting-started/installation/source.mdx | 26 +- .../getting-started/installation/unraid.mdx | 13 +- .../docs/integrations/adguard-home/index.mdx | 49 +- apps/docs/docs/integrations/anchor/index.mdx | 51 +- apps/docs/docs/integrations/aria2/index.mdx | 51 +- .../integrations/audiobookshelf/index.mdx | 51 +- apps/docs/docs/integrations/bazarr/index.mdx | 52 +- apps/docs/docs/integrations/beszel/index.mdx | 60 +- apps/docs/docs/integrations/coolify/index.mdx | 67 +- .../docs/docs/integrations/dash-dot/index.mdx | 39 +- apps/docs/docs/integrations/deluge/index.mdx | 45 +- apps/docs/docs/integrations/docker/index.mdx | 46 +- apps/docs/docs/integrations/emby/index.mdx | 44 +- apps/docs/docs/integrations/glances/index.mdx | 50 +- apps/docs/docs/integrations/gluetun/index.mdx | 56 +- apps/docs/docs/integrations/gotify/index.mdx | 42 +- .../integrations/home-assistant/index.mdx | 52 +- apps/docs/docs/integrations/ical/index.mdx | 44 +- apps/docs/docs/integrations/immich/index.mdx | 38 +- .../docs/docs/integrations/jellyfin/index.mdx | 51 +- .../docs/integrations/jellyseerr/index.mdx | 65 +- .../docs/integrations/kubernetes/index.mdx | 18 +- apps/docs/docs/integrations/lidarr/index.mdx | 43 +- .../docs/integrations/navidrome/index.mdx | 47 +- .../docs/integrations/nextcloud/index.mdx | 55 +- apps/docs/docs/integrations/ntfy/index.mdx | 49 +- apps/docs/docs/integrations/nzbget/index.mdx | 45 +- .../integrations/open-media-vault/index.mdx | 62 +- .../docs/docs/integrations/opnsense/index.mdx | 84 +- .../docs/integrations/overseerr/index.mdx | 65 +- .../docs/integrations/paperless-ngx/index.mdx | 51 +- .../docs/docs/integrations/patchmon/index.mdx | 51 +- apps/docs/docs/integrations/peanut/index.mdx | 57 +- apps/docs/docs/integrations/pi-hole/index.mdx | 65 +- apps/docs/docs/integrations/plex/index.mdx | 58 +- .../docs/docs/integrations/prowlarr/index.mdx | 38 +- apps/docs/docs/integrations/proxmox/index.mdx | 136 +- .../docs/integrations/q-bittorent/index.mdx | 48 +- apps/docs/docs/integrations/radarr/index.mdx | 39 +- apps/docs/docs/integrations/readarr/index.mdx | 39 +- apps/docs/docs/integrations/sabnzbd/index.mdx | 41 +- apps/docs/docs/integrations/seerr/index.mdx | 65 +- apps/docs/docs/integrations/slskd/index.mdx | 43 +- apps/docs/docs/integrations/sonarr/index.mdx | 39 +- .../integrations/speedtest-tracker/index.mdx | 45 +- .../docs/docs/integrations/synology/index.mdx | 6 +- apps/docs/docs/integrations/tdarr/index.mdx | 46 +- .../integrations/technitium-dns/index.mdx | 88 +- .../docs/docs/integrations/tracearr/index.mdx | 47 +- .../docs/integrations/transmission/index.mdx | 41 +- apps/docs/docs/integrations/truenas/index.mdx | 88 +- apps/docs/docs/integrations/umami/index.mdx | 73 +- .../integrations/unifi-controller/index.mdx | 42 +- apps/docs/docs/integrations/unraid/index.mdx | 94 +- .../docs/integrations/uptime-kuma/index.mdx | 47 +- apps/docs/docs/management/api/index.mdx | 13 + apps/docs/docs/management/apps/index.mdx | 10 +- apps/docs/docs/management/backup.mdx | 10 +- apps/docs/docs/management/boards/index.mdx | 93 +- .../docs/management/certificates/index.mdx | 24 +- .../management/custom-widgets/_category_.json | 9 + .../custom-widgets/agent-authoring.mdx | 86 + .../management/custom-widgets/authoring.mdx | 37 + .../management/custom-widgets/custom-jsx.mdx | 44 + .../docs/management/custom-widgets/index.mdx | 234 +- .../custom-widgets/requests-and-security.mdx | 42 + .../custom-widgets/troubleshooting.mdx | 59 + .../docs/management/integrations/index.mdx | 25 +- apps/docs/docs/management/mcp.mdx | 106 +- apps/docs/docs/management/media/index.mdx | 3 +- .../docs/management/search-engines/index.mdx | 24 +- apps/docs/docs/management/settings/index.mdx | 21 +- apps/docs/docs/management/tasks/index.mdx | 3 - apps/docs/docs/management/users/index.mdx | 41 +- apps/docs/docs/management/workshop/index.mdx | 24 +- apps/docs/docs/widgets/anchor-note/index.mdx | 34 +- apps/docs/docs/widgets/app/index.mdx | 27 +- apps/docs/docs/widgets/audio-stats/index.mdx | 44 +- apps/docs/docs/widgets/bazarr/index.mdx | 36 +- .../docs/docs/widgets/beszel-alerts/index.mdx | 36 +- .../docs/widgets/beszel-system-grid/index.mdx | 36 +- .../widgets/beszel-system-table/index.mdx | 35 +- apps/docs/docs/widgets/bookmarks/index.mdx | 29 +- apps/docs/docs/widgets/calendar/index.mdx | 97 +- apps/docs/docs/widgets/clock/index.mdx | 34 +- apps/docs/docs/widgets/coolify/index.mdx | 39 +- apps/docs/docs/widgets/custom-api/index.mdx | 56 +- apps/docs/docs/widgets/custom-api/index.ts | 3 +- .../docs/widgets/dns-hole-controls/index.mdx | 54 +- .../docs/widgets/dns-hole-summary/index.mdx | 59 +- .../docs/widgets/docker-containers/index.mdx | 39 +- apps/docs/docs/widgets/downloads/index.mdx | 88 +- apps/docs/docs/widgets/firewall/index.mdx | 34 +- apps/docs/docs/widgets/iframe/index.mdx | 33 +- .../widgets/immich-album-carousel/index.mdx | 38 +- .../widgets/immich-server-stats/index.mdx | 38 +- .../docs/widgets/indexer-manager/index.mdx | 41 +- .../docs/docs/widgets/media-missing/index.mdx | 50 +- .../docs/widgets/media-releases/index.mdx | 51 +- .../docs/widgets/media-request-list/index.mdx | 48 +- .../docs/widgets/media-request-list/index.ts | 12 + .../widgets/media-request-stats/index.mdx | 45 +- apps/docs/docs/widgets/media-server/index.mdx | 60 +- .../docs/widgets/media-transcoding/index.mdx | 47 +- .../widgets/minecraft-server-status/index.mdx | 33 +- .../network-controller-status/index.mdx | 41 +- .../network-controller-summary/index.mdx | 38 +- .../docs/docs/widgets/notifications/index.mdx | 37 +- .../docs/docs/widgets/paperless-ngx/index.mdx | 35 +- apps/docs/docs/widgets/patchmon/index.mdx | 61 +- apps/docs/docs/widgets/rss-feed/index.mdx | 25 +- .../widgets/smart-home-entity-state/index.mdx | 50 +- .../smart-home-execute-automation/index.mdx | 48 +- .../docs/widgets/speedtest-tracker/index.mdx | 34 +- apps/docs/docs/widgets/stock-price/index.mdx | 32 +- apps/docs/docs/widgets/system-disks/index.ts | 6 +- apps/docs/docs/widgets/timetable/index.mdx | 12 +- apps/docs/docs/widgets/tracearr/index.mdx | 49 +- apps/docs/docs/widgets/umami/index.mdx | 43 +- apps/docs/docs/widgets/ups/index.mdx | 48 +- apps/docs/docs/widgets/uptime-kuma/index.mdx | 35 +- apps/docs/docs/widgets/video/index.mdx | 20 +- apps/docs/docs/widgets/vpn/index.mdx | 31 +- apps/docs/docs/widgets/weather/index.mdx | 25 +- apps/docs/docusaurus.config.ts | 26 +- apps/docs/package.json | 18 +- apps/docs/scripts/dump-contributors.mjs | 39 +- apps/docs/scripts/verify-algolia-search.mjs | 101 +- .../custom-jsx-component-reference.module.css | 451 ++++ .../custom-jsx-component-reference.tsx | 497 ++++ .../components/custom-widget-code-client.tsx | 120 + .../src/components/custom-widget-code.tsx | 50 + .../available-integrations.module.css | 26 +- .../pages/home/review-list/styles.module.css | 4 - .../components/workshop/DetailComments.tsx | 53 +- .../src/components/workshop/DetailPage.tsx | 192 +- .../src/components/workshop/SubmitForm.tsx | 45 +- .../src/components/workshop/WorkshopAdmin.tsx | 188 ++ .../src/components/workshop/WorkshopApp.tsx | 151 +- .../workshop/WorkshopDetailRoutePage.tsx | 1 + .../src/components/workshop/useWorkshop.ts | 45 +- apps/docs/src/lib/pocketbase.ts | 43 +- apps/docs/src/lib/utils.ts | 10 + apps/docs/src/lib/workshop-schema.spec.ts | 33 +- apps/docs/src/lib/workshop-schema.ts | 88 +- apps/docs/src/pages/index.module.css | 1 - apps/docs/src/pages/workshop/admin/index.tsx | 15 + apps/docs/static/api/open-api-schema.json | 2266 ++++++++++++++++- .../custom-widgets/component-catalog-v1.json | 1 + apps/docs/static/data/contributions.json | 128 +- .../data/translation-contributions.json | 967 ++++++- apps/docs/tsconfig.json | 14 +- .../boards/[name]/settings/_customCss.tsx | 5 +- .../manage/custom-widgets/_beta-banner.tsx | 19 + .../manage/custom-widgets/edit/[id]/page.tsx | 2 + .../manage/custom-widgets/new/page.tsx | 2 + .../[locale]/manage/custom-widgets/page.tsx | 2 + .../components/workshop/workshop-browser.tsx | 131 +- .../workshop/workshop-css-import-button.tsx | 28 + .../workshop/workshop-publish-modal.tsx | 5 +- apps/workshop/Dockerfile | 3 +- apps/workshop/README.md | 32 +- apps/workshop/docker-compose.yml | 7 + apps/workshop/entrypoint.sh | 1 + apps/workshop/pb_hooks/workshop.pb.js | 55 + .../1784240000_workshop_widgets.js | 85 +- apps/workshop/tests/workshop.integration.mjs | 75 +- package.json | 1 + packages/translation/src/lang/en.json | 6 + packages/workshop/src/client.ts | 136 +- packages/workshop/src/schema.spec.ts | 12 + packages/workshop/src/schema.ts | 58 +- pnpm-lock.yaml | 74 + 208 files changed, 9503 insertions(+), 3337 deletions(-) create mode 100644 apps/docs/docs/management/custom-widgets/_category_.json create mode 100644 apps/docs/docs/management/custom-widgets/agent-authoring.mdx create mode 100644 apps/docs/docs/management/custom-widgets/authoring.mdx create mode 100644 apps/docs/docs/management/custom-widgets/custom-jsx.mdx create mode 100644 apps/docs/docs/management/custom-widgets/requests-and-security.mdx create mode 100644 apps/docs/docs/management/custom-widgets/troubleshooting.mdx create mode 100644 apps/docs/src/components/custom-jsx-component-reference.module.css create mode 100644 apps/docs/src/components/custom-jsx-component-reference.tsx create mode 100644 apps/docs/src/components/custom-widget-code-client.tsx create mode 100644 apps/docs/src/components/custom-widget-code.tsx create mode 100644 apps/docs/src/components/workshop/WorkshopAdmin.tsx create mode 100644 apps/docs/src/components/workshop/WorkshopDetailRoutePage.tsx create mode 100644 apps/docs/src/pages/workshop/admin/index.tsx create mode 100644 apps/docs/static/custom-widgets/component-catalog-v1.json create mode 100644 apps/nextjs/src/app/[locale]/manage/custom-widgets/_beta-banner.tsx create mode 100644 apps/nextjs/src/components/workshop/workshop-css-import-button.tsx create mode 100644 apps/workshop/pb_hooks/workshop.pb.js diff --git a/apps/docs/.oxlintrc.json b/apps/docs/.oxlintrc.json index 58480a9ab..3eba05d31 100644 --- a/apps/docs/.oxlintrc.json +++ b/apps/docs/.oxlintrc.json @@ -23,9 +23,6 @@ "react-hooks/exhaustive-deps": "warn", "eslint/no-unused-expressions": "warn" }, - "options": { - "reportUnusedDisableDirectives": "off" - }, "ignorePatterns": ["**/*.config.js", "**/*.config.mjs", "**/*.cjs", ".docusaurus/**", "build/**"], "settings": { "react": { "version": "19" } diff --git a/apps/docs/.vscode/settings.json b/apps/docs/.vscode/settings.json index c5a1b2892..2eef88bf3 100644 --- a/apps/docs/.vscode/settings.json +++ b/apps/docs/.vscode/settings.json @@ -1,10 +1,3 @@ { - "cSpell.words": [ - "Homarr", - "Lidarr", - "Nextcloud", - "Radarr", - "Readarr", - "Sonarr" - ] -} \ No newline at end of file + "cSpell.words": ["Homarr", "Lidarr", "Nextcloud", "Radarr", "Readarr", "Sonarr"] +} diff --git a/apps/docs/README.md b/apps/docs/README.md index b66530488..f704c92f0 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -71,7 +71,7 @@ Each integration/widget doc follows a consistent pattern: The docs app has `@homarr/definitions` as a workspace dependency. You can import integration kinds, widget kinds, and other definitions directly: ```typescript -import { IntegrationKind } from '@homarr/definitions'; +import { IntegrationKind } from "@homarr/definitions"; ``` This enables type-safe references to homarr domain concepts within documentation code. @@ -90,15 +90,15 @@ pnpm verify:search ## Tech Stack -| Layer | Technology | -|---|---| +| Layer | Technology | +| -------------- | ------------------------------------------- | | Site generator | Docusaurus 3 (`@docusaurus/preset-classic`) | -| Styling | Tailwind CSS 3 + Docusaurus Infima | -| Icons | `@tabler/icons-react` | -| Diagrams | Mermaid (`@docusaurus/theme-mermaid`) | -| Search | Algolia DocSearch | -| Analytics | PostHog | -| Charts | @nivo/line | +| Styling | Tailwind CSS 3 + Docusaurus Infima | +| Icons | `@tabler/icons-react` | +| Diagrams | Mermaid (`@docusaurus/theme-mermaid`) | +| Search | Algolia DocSearch | +| Analytics | PostHog | +| Charts | @nivo/line | ## Contributing diff --git a/apps/docs/docs/advanced/command-line/_category_.json b/apps/docs/docs/advanced/command-line/_category_.json index f3ee30aa5..4b4aec4c3 100644 --- a/apps/docs/docs/advanced/command-line/_category_.json +++ b/apps/docs/docs/advanced/command-line/_category_.json @@ -1,4 +1,4 @@ { "collapsed": true, "label": "Command line interface" -} \ No newline at end of file +} diff --git a/apps/docs/docs/advanced/command-line/fix-usernames/index.mdx b/apps/docs/docs/advanced/command-line/fix-usernames/index.mdx index d3b9f50cc..bf8808118 100644 --- a/apps/docs/docs/advanced/command-line/fix-usernames/index.mdx +++ b/apps/docs/docs/advanced/command-line/fix-usernames/index.mdx @@ -14,4 +14,4 @@ homarr fix-usernames This will convert all credential usernames to lowercase and update the database accordingly. -![](./img/screenshot-cli.png) \ No newline at end of file +![](./img/screenshot-cli.png) diff --git a/apps/docs/docs/advanced/command-line/index.mdx b/apps/docs/docs/advanced/command-line/index.mdx index 0e3e802f7..287985739 100644 --- a/apps/docs/docs/advanced/command-line/index.mdx +++ b/apps/docs/docs/advanced/command-line/index.mdx @@ -1,7 +1,7 @@ # Command line interface The Homarr image ships with a built-in recovery tool. This can be useful, if you do not have access to Homarr or if something is not working. -Please note that the CLI is an *emergency tool*, not an API tool. +Please note that the CLI is an _emergency tool_, not an API tool. :::caution @@ -12,10 +12,10 @@ You should also create a backup of the database, in case you break something. ## Execute CLI with Docker -1. Execute ``docker ps | grep homarr`` on the root system with Docker to find the container ID of your Homarr container. -2. Run ``docker exec -it /bin/bash homarr ``. \ -Replace ```` with your container ID from step 1. \ -Replace ```` with the command you want to execute (see sub-pages). +1. Execute `docker ps | grep homarr` on the root system with Docker to find the container ID of your Homarr container. +2. Run `docker exec -it /bin/bash homarr `. \ + Replace `` with your container ID from step 1. \ + Replace `` with the command you want to execute (see sub-pages). ## Execute CLI with QNAP diff --git a/apps/docs/docs/advanced/command-line/integrations/index.mdx b/apps/docs/docs/advanced/command-line/integrations/index.mdx index dfdb587b0..b958e9d2b 100644 --- a/apps/docs/docs/advanced/command-line/integrations/index.mdx +++ b/apps/docs/docs/advanced/command-line/integrations/index.mdx @@ -7,6 +7,7 @@ This guide requires that you understand [how to access the CLI](../). ::: Using these commands, you can manage the integrations from the CLI: + ```bash Group of commands to manage integrations @@ -43,7 +44,7 @@ Flags: ## Delete Integration - Requires a database connection -- Requires one parameter: ``id`` or ``name`` +- Requires one parameter: `id` or `name` - Deletes an integration permanently from the database ```bash @@ -57,4 +58,4 @@ Flags: -n, --name string Name of the integration -h, --help help for integrations delete -v, --version version for homarr-cli -``` \ No newline at end of file +``` diff --git a/apps/docs/docs/advanced/command-line/password-recovery/index.mdx b/apps/docs/docs/advanced/command-line/password-recovery/index.mdx index e5a80f669..844b44140 100644 --- a/apps/docs/docs/advanced/command-line/password-recovery/index.mdx +++ b/apps/docs/docs/advanced/command-line/password-recovery/index.mdx @@ -12,8 +12,8 @@ All sessions for that user will be terminated and the user must re-login. ![](./img/screenshot-cli.png) -Using the ``--username`` parameter, you can specify who you want to reset the password for. +Using the `--username` parameter, you can specify who you want to reset the password for. Executing the command will create a new random password, update the database and display the new password. All sessions for this user will be terminated and they must re-login. -![](./img/screenshot-cli-result.png) \ No newline at end of file +![](./img/screenshot-cli-result.png) diff --git a/apps/docs/docs/advanced/command-line/users/index.mdx b/apps/docs/docs/advanced/command-line/users/index.mdx index a867fa72d..93170259a 100644 --- a/apps/docs/docs/advanced/command-line/users/index.mdx +++ b/apps/docs/docs/advanced/command-line/users/index.mdx @@ -7,6 +7,7 @@ This guide requires that you understand [how to access the CLI](../). ::: Using these commands, you can manage the users from the CLI: + ```bash Group of commands to manage users @@ -42,7 +43,7 @@ yj52ek5cyb6du4bp4osbkjry admin xxxx@example.com ## Delete User - Requires a database connection -- Requires one parameter: ``id`` or ``username`` +- Requires one parameter: `id` or `username` ```bash Delete a user by id or username @@ -76,4 +77,4 @@ Flags: -p, --password New password -h, --help help for users update-password -v, --version version for homarr-cli -``` \ No newline at end of file +``` diff --git a/apps/docs/docs/advanced/development/_category_.json b/apps/docs/docs/advanced/development/_category_.json index 9f659a536..bf0464672 100644 --- a/apps/docs/docs/advanced/development/_category_.json +++ b/apps/docs/docs/advanced/development/_category_.json @@ -1,9 +1,8 @@ { - "label": "Developer guides", - "position": 6, - "collapsed": true, - "link": { - "type": "generated-index" - } + "label": "Developer guides", + "position": 6, + "collapsed": true, + "link": { + "type": "generated-index" } - \ No newline at end of file +} diff --git a/apps/docs/docs/advanced/development/getting-started.mdx b/apps/docs/docs/advanced/development/getting-started.mdx index 7c16813ba..fb2cb9560 100644 --- a/apps/docs/docs/advanced/development/getting-started.mdx +++ b/apps/docs/docs/advanced/development/getting-started.mdx @@ -63,6 +63,7 @@ This guide will help you set up your development environment to start contributi - `pnpm typecheck`: Run the typescript type checker. #### Building the project + - `pnpm build`: Build the project for production. - `docker build -t homarr .`: Build a docker image for the project. -- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:latest`: Run the created docker image. \ No newline at end of file +- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:latest`: Run the created docker image. diff --git a/apps/docs/docs/advanced/development/kubernetes.mdx b/apps/docs/docs/advanced/development/kubernetes.mdx index e27b3ccbc..ff58b6c0a 100644 --- a/apps/docs/docs/advanced/development/kubernetes.mdx +++ b/apps/docs/docs/advanced/development/kubernetes.mdx @@ -132,4 +132,4 @@ This command should return CPU and memory usage statistics for each node. ## Conclusion -You have successfully set up a multi-node Kubernetes cluster using kind and installed the Metrics Server for monitoring resource usage. This setup is useful for local development and testing Kubernetes workloads before deploying them to a production environment. \ No newline at end of file +You have successfully set up a multi-node Kubernetes cluster using kind and installed the Metrics Server for monitoring resource usage. This setup is useful for local development and testing Kubernetes workloads before deploying them to a production environment. diff --git a/apps/docs/docs/advanced/environment-variables/index.mdx b/apps/docs/docs/advanced/environment-variables/index.mdx index f1a70b371..d45a19472 100644 --- a/apps/docs/docs/advanced/environment-variables/index.mdx +++ b/apps/docs/docs/advanced/environment-variables/index.mdx @@ -25,15 +25,13 @@ This is especially useful for [docker secrets](https://docs.docker.com/engine/sw Using the `PUID` and `PGID` will require you to set the correct permissions on the mounted volumes and if used the docker socket. See more in the [Running as a different user](/docs/advanced/running-as-different-user) documentation. ::: -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| ``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 some requests that need internet connection | `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` | - - +| Environment Variable | Description | Possible values | Default | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------- | +| `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 some requests that need internet connection | `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` | ## Authentication @@ -43,9 +41,9 @@ See [Single Sign-On](/docs/advanced/single-sign-on) for more informations. The `SECRET_ENCRYPTION_KEY` is required. If none is specified before starting the container, a random key will be shown in the error message and the container will exit. -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| ``SECRET_ENCRYPTION_KEY`` | Secret used to encrypt secrets in database. | 64 character hex string | - | +| Environment Variable | Description | Possible values | Default | +| ----------------------- | ------------------------------------------- | ----------------------- | ------- | +| `SECRET_ENCRYPTION_KEY` | Secret used to encrypt secrets in database. | 64 character hex string | - | :::info A random secret can be generated by using the following command: `openssl rand -hex 32` @@ -53,27 +51,27 @@ A random secret can be generated by using the following command: `openssl rand - ## Docker -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| ``DOCKER_HOSTNAMES`` | Comma seperated list of hostnames to connect to | For example `localhost,docker.example.com` | - | -| ``DOCKER_PORTS`` | Comma seperated list of ports to connect to | For example `2375,2376` | - | -| ``DOCKER_SOCKET_PATHS`` | Comma seperated list of paths to sockets | For example `/var/run/docker.sock,/run/user/1000/podman/podman.sock` | - | +| Environment Variable | Description | Possible values | Default | +| --------------------- | ----------------------------------------------- | -------------------------------------------------------------------- | ------- | +| `DOCKER_HOSTNAMES` | Comma seperated list of hostnames to connect to | For example `localhost,docker.example.com` | - | +| `DOCKER_PORTS` | Comma seperated list of ports to connect to | For example `2375,2376` | - | +| `DOCKER_SOCKET_PATHS` | Comma seperated list of paths to sockets | For example `/var/run/docker.sock,/run/user/1000/podman/podman.sock` | - | ## Database -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| ``DB_DRIVER`` | Database driver to use. Currently `better-sqlite3` is used for sqlite, `mysql2` for mysql and `node-postgres` for postgresql | ``better-sqlite3`` / ``mysql2`` / ``node-postgres`` | ``better-sqlite3`` | -| ``DB_DIALECT`` | Database dialect to use. | ``sqlite`` / ``mysql`` / ``postgresql`` | ``sqlite`` | -| ``DB_URL`` | Database URL to connect to. | Any valid database URL | ``/appdata/db/db.sqlite`` | -| ``DB_HOST`` | Database host to connect to. | Any valid database host | - | -| ``DB_PORT`` | Database port to connect to. | Any valid database port | - | -| ``DB_NAME`` | Database name to connect to. | Any valid database name | - | -| ``DB_USER`` | Database user to connect with. | Any valid database user | - | -| ``DB_PASSWORD`` | Database password to connect with. | Any valid database password | - | + +| Environment Variable | Description | Possible values | Default | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------- | +| `DB_DRIVER` | Database driver to use. Currently `better-sqlite3` is used for sqlite, `mysql2` for mysql and `node-postgres` for postgresql | `better-sqlite3` / `mysql2` / `node-postgres` | `better-sqlite3` | +| `DB_DIALECT` | Database dialect to use. | `sqlite` / `mysql` / `postgresql` | `sqlite` | +| `DB_URL` | Database URL to connect to. | Any valid database URL | `/appdata/db/db.sqlite` | +| `DB_HOST` | Database host to connect to. | Any valid database host | - | +| `DB_PORT` | Database port to connect to. | Any valid database port | - | +| `DB_NAME` | Database name to connect to. | Any valid database name | - | +| `DB_USER` | Database user to connect with. | Any valid database user | - | +| `DB_PASSWORD` | Database password to connect with. | Any valid database password | - | You can either use the url or host, port, name and credentials combined. The URL will be prioritized over the other values. - ## Redis By default Redis is running within the installation. (for example in Docker). @@ -83,25 +81,23 @@ However for example for K8s it can be useful to use an external Redis instance. External redis is currently not supported with Proxmox Community Scripts ::: -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| `REDIS_IS_EXTERNAL` | Whether Redis is running externally. | `true` / `false` | `false` | -| `REDIS_HOST` | Hostname of the Redis instance. | Any valid hostname | - | -| `REDIS_PORT` | Port of the Redis instance. | Any valid port | `6379` | -| `REDIS_USERNAME` | Username to connect to the Redis instance. | Any valid username | - | -| `REDIS_PASSWORD` | Password to connect to the Redis instance. | Any valid password | - | -| `REDIS_DATABASE_INDEX` | Select which database of your redis instance should be used. | Any numeric index | - | -| `REDIS_TLS_CA` | CA certificate for Redis TLS connections. If a certificate is specified the connection will use TLS. | Any valid CA certificate | - | - +| Environment Variable | Description | Possible values | Default | +| ---------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------ | ------- | +| `REDIS_IS_EXTERNAL` | Whether Redis is running externally. | `true` / `false` | `false` | +| `REDIS_HOST` | Hostname of the Redis instance. | Any valid hostname | - | +| `REDIS_PORT` | Port of the Redis instance. | Any valid port | `6379` | +| `REDIS_USERNAME` | Username to connect to the Redis instance. | Any valid username | - | +| `REDIS_PASSWORD` | Password to connect to the Redis instance. | Any valid password | - | +| `REDIS_DATABASE_INDEX` | Select which database of your redis instance should be used. | Any numeric index | - | +| `REDIS_TLS_CA` | CA certificate for Redis TLS connections. If a certificate is specified the connection will use TLS. | Any valid CA certificate | - | ## Proxy -| Environment Variable | Description | Possible values | Default | -| ------------------------ | ----------- | --------------- | ------- | -| ``HTTP_PROXY`` | HTTP proxy to use | Any valid HTTP proxy URL | - | -| ``HTTPS_PROXY`` | HTTPS proxy to use | Any valid HTTPS proxy URL | - | -| ``NO_PROXY`` | Comma separated list of hosts that should be excluded from proxying | Any valid hostnames | - | - +| Environment Variable | Description | Possible values | Default | +| -------------------- | ------------------------------------------------------------------- | ------------------------- | ------- | +| `HTTP_PROXY` | HTTP proxy to use | Any valid HTTP proxy URL | - | +| `HTTPS_PROXY` | HTTPS proxy to use | Any valid HTTPS proxy URL | - | +| `NO_PROXY` | Comma separated list of hosts that should be excluded from proxying | Any valid hostnames | - | ## Advanced deployments @@ -109,6 +105,7 @@ External redis is currently not supported with Proxmox Community Scripts The advanced deployments environment variables should only be used if you know what you are doing. ::: -| Environment Variable | Description | -| ------------------------ | ----------- | -| ``DB_MIGRATIONS_DISABLED`` | Disable db migrations. For example for helm charts | +| Environment Variable | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------- | +| `DB_MIGRATIONS_DISABLED` | Disable db migrations. For example for helm charts | +| `WORKSHOP_API_URL` | Runtime public origin of the separate Workshop PocketBase service. Homarr uses `https://homarr.dev` by default. | diff --git a/apps/docs/docs/advanced/icons/index.mdx b/apps/docs/docs/advanced/icons/index.mdx index 2876559ac..04b5f3890 100644 --- a/apps/docs/docs/advanced/icons/index.mdx +++ b/apps/docs/docs/advanced/icons/index.mdx @@ -9,14 +9,16 @@ tags: --- ## Icon picker + Icons in Homarr are automatically requested from multiple sources: - - [Dashboard Icons](https://dashboardicons.com/) - Our recommended source with over 1888+ curated, high-quality icons - - [selfh.st icons](https://github.com/selfhst/icons) - - [Simple icons](https://github.com/simple-icons/simple-icons) - - [Tabler icons](https://tabler-icons.io/) - - [Papirus icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme) - - [Homelab Svg assets](https://github.com/loganmarchione/homelab-svg-assets) - - **Local icons**: automatically fetched from the [medias feature](/docs/management/media/) + +- [Dashboard Icons](https://dashboardicons.com/) - Our recommended source with over 1888+ curated, high-quality icons +- [selfh.st icons](https://github.com/selfhst/icons) +- [Simple icons](https://github.com/simple-icons/simple-icons) +- [Tabler icons](https://tabler-icons.io/) +- [Papirus icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme) +- [Homelab Svg assets](https://github.com/loganmarchione/homelab-svg-assets) +- **Local icons**: automatically fetched from the [medias feature](/docs/management/media/) Using these icon sources, Homarr provides a total collection of over 11,000 icons at your fingertips. The icon picker is a fast searcher that helps you to find your desired icon simply by entering a search term. @@ -30,5 +32,6 @@ If you can't find the icon you're looking for in Homarr's built-in picker, we st Icons that are high quality and printable ([SVG](https://wikipedia.org/wiki/Scalable_Vector_Graphics)) are marked with a red badge "SVG" at the top right. ### Using external icons + If you don't find the icon you're looking for on Dashboard Icons or wish to use a different source, you can simply enter a URL that points to an icon. It is important that the URL directly points to the file without any advertisements or elements around it. diff --git a/apps/docs/docs/advanced/keyboard-shortcuts/index.mdx b/apps/docs/docs/advanced/keyboard-shortcuts/index.mdx index 8dfe0f285..fa504f82b 100644 --- a/apps/docs/docs/advanced/keyboard-shortcuts/index.mdx +++ b/apps/docs/docs/advanced/keyboard-shortcuts/index.mdx @@ -6,11 +6,11 @@ tags: Homarr has the following keyboard shortcuts: -| Shortcut | Description | -| -------- | ----------- | +| Shortcut | Description | +| ----------- | -------------------- | | `MOD` + `K` | Opens the search bar | -| `MOD` + `J` | Toggles Dark Mode | -| `MOD` + `E` | Toggles Edit Mode | +| `MOD` + `J` | Toggles Dark Mode | +| `MOD` + `E` | Toggles Edit Mode | :::tip diff --git a/apps/docs/docs/advanced/proxy/index.mdx b/apps/docs/docs/advanced/proxy/index.mdx index ef4e41f1d..02af599ec 100644 --- a/apps/docs/docs/advanced/proxy/index.mdx +++ b/apps/docs/docs/advanced/proxy/index.mdx @@ -9,16 +9,17 @@ tags: - Security --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; ## Allowing self-signed certificates + Some users may come across a barrier, where they're unable to receive a 200 response from the Ping widget for some apps, while using self-signed certificates or a local certificate authory. :::note What's going on? Homarr is trying to communicate to your apps via the integrations. -It usually doesn't matter if Homarr is running on ``http`` or ``https``. +It usually doesn't matter if Homarr is running on `http` or `https`. Your apps have a self-signed certificate - Homarr will recognize that the certificate was signed by an unknown authority and requests will be blocked. ::: @@ -28,8 +29,9 @@ To allow self-signed certificates, you can configure them on the certificates ma ## Securing Homarr with Traefik Copying the configuration straight from the docker-compose file won't work if you are running Homarr behind Traefik, such as a Portainer setup, or docker-swarm. In that case, you should use the following slightly modified configuration: + ```yaml -version: '3' +version: "3" services: homarr: container_name: homarr @@ -54,11 +56,12 @@ networks: external: true ``` -
+
A sample Traefik docker-compose.yml using Cloudflare for certificate generation that works with the configuration above would be: + ```yaml -version: '3' +version: "3" apps: traefik: @@ -104,7 +107,6 @@ networks: external: true ``` - :::tip Of particular note here is that both configurations explicitly define which network they are using, in this case "proxy", but it can be named anything. It just has to be the same across all apps for which Traefik is serving as a proxy. These are marked as external because the proxy network was manually created by running: `docker network create proxy` but this might be unnecessary depending on HOW exactly you are running Traefik. For example, if running [Traefik with Portainer](https://docs.portainer.io/advanced/reverse-proxy/traefik#deploying-in-a-docker-standalone-scenario), you can follow their official docs on how to set up Traefik and Portainer together, and you can just focus on the Homarr docker labels instead. ::: @@ -115,7 +117,6 @@ If you are using Caddy as the reverse proxy for your setup, your `docker-compose ```yaml services: - # <-- [Homarr installation] caddy: @@ -141,14 +142,17 @@ networks: proxy: external: true ``` + :::important Homarr needs to be on the same network so you will need to add the following property to your homarr install: + ```yaml homarr: ... networks: - proxy ``` + ::: Next, create a file named `Caddyfile` at the same level as your `docker-compose.yml` file with the following content: diff --git a/apps/docs/docs/advanced/running-as-different-user/index.mdx b/apps/docs/docs/advanced/running-as-different-user/index.mdx index a4ebcf0f4..91c02fb9d 100644 --- a/apps/docs/docs/advanced/running-as-different-user/index.mdx +++ b/apps/docs/docs/advanced/running-as-different-user/index.mdx @@ -8,7 +8,7 @@ tags: - PUID --- -By default the container is running with user `root` and group `root`. +By default the container is running with user `root` and group `root`. You can change the user and group by using the `PUID` and `PGID` environment variables. Important to note is, that you'll also need to change the permissions for the mounted directories accordingly. @@ -32,11 +32,11 @@ services: volumes: - ./homarr/appdata:/appdata environment: - - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` - - PUID=1000 - - PGID=1000 + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` + - PUID=1000 + - PGID=1000 ports: - - '7575:7575' + - "7575:7575" ``` After that you'll need to create the appdata directory and set the correct permissions: @@ -76,11 +76,11 @@ services: - /var/run/docker.sock:/var/run/docker.sock - ./homarr/appdata:/appdata environment: - - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` - - PUID=1000 - - PGID=999 + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` + - PUID=1000 + - PGID=999 ports: - - '7575:7575' + - "7575:7575" ``` And set the permissions for the mounted directories: @@ -90,4 +90,4 @@ mkdir -p ./homarr/appdata chown -R 1000:999 ./homarr/appdata ``` -Important here is that the group ID is set to `999` as we created the `docker` group with this ID. \ No newline at end of file +Important here is that the group ID is set to `999` as we created the `docker` group with this ID. diff --git a/apps/docs/docs/advanced/single-sign-on/index.mdx b/apps/docs/docs/advanced/single-sign-on/index.mdx index b4865ec88..f8e4c1ca7 100644 --- a/apps/docs/docs/advanced/single-sign-on/index.mdx +++ b/apps/docs/docs/advanced/single-sign-on/index.mdx @@ -10,20 +10,21 @@ tags: - Active Directory --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; # Single Sign On Homarr supports multiple authentication options, from internal userbase (credentials), to LDAP (with Active directory support), and OIDC. ### Auth configuration common variables -| Environment Variable | Description | Default Value | -|---------------------------|-------------|---------------| -| AUTH_PROVIDERS | Select Which provider to use between *credentials*, *ldap* and *oidc*.
Multiple providers can be enabled with by separating them with `,`, (ex. `AUTH_PROVIDERS=credentials,oidc`, it is highly recommended to just enable one provider). | credentials | -| AUTH_LOGOUT_REDIRECT_URL | URL to redirect to after clicking logging out. | --- | -| AUTH_SESSION_EXPIRY_TIME | Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m") | "30d" | -| AUTH_COOKIE_PREFIX | Prefix used for all authentication cookies (session, csrf, callback, pkce, state, nonce). Change this if you run another Auth.js/NextAuth app on the same hostname as Homarr (browsers scope cookies by host, not by port) to avoid cookie name collisions. Only letters, numbers, hyphens and underscores are allowed. | `homarr` | + +| Environment Variable | Description | Default Value | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| AUTH_PROVIDERS | Select Which provider to use between _credentials_, _ldap_ and _oidc_.
Multiple providers can be enabled with by separating them with `,`, (ex. `AUTH_PROVIDERS=credentials,oidc`, it is highly recommended to just enable one provider). | credentials | +| AUTH_LOGOUT_REDIRECT_URL | URL to redirect to after clicking logging out. | --- | +| AUTH_SESSION_EXPIRY_TIME | Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m") | "30d" | +| AUTH_COOKIE_PREFIX | Prefix used for all authentication cookies (session, csrf, callback, pkce, state, nonce). Change this if you run another Auth.js/NextAuth app on the same hostname as Homarr (browsers scope cookies by host, not by port) to avoid cookie name collisions. Only letters, numbers, hyphens and underscores are allowed. | `homarr` | diff --git a/apps/docs/docs/advanced/styling/index.mdx b/apps/docs/docs/advanced/styling/index.mdx index 9be382ec3..56d4305e5 100644 --- a/apps/docs/docs/advanced/styling/index.mdx +++ b/apps/docs/docs/advanced/styling/index.mdx @@ -19,12 +19,14 @@ Homarr uses https://mantine.dev/ under the hood. You can change the look & feel using custom CSS, that extends or overwrites the styles from Mantine. ## Getting into CSS + If you don't have any experience with CSS, we strongly recommend you to go through the courses here: https://www.w3schools.com/css/. Due to the infinite scenarios and setups possible with custom CSS, our support team will not provide any support with your own written CSS. ## Limitations and dangers + When using custom CSS, you can break the page or certain functionalities. Although CSS can improve the design & feel of the page, it **cannot do any of the following**: @@ -33,21 +35,23 @@ Although CSS can improve the design & feel of the page, it **cannot do any - Completely revamp the design of the page, only smaller changes are possible Here are some dangers of using custom CSS: + - Updates may contain breaking changes in the structure, built-in styling or how styling is processed. Therefore, -custom CSS may break unexpectedly without any warning + custom CSS may break unexpectedly without any warning - Custom CSS may make certain elements invisible or not possible to click / interact with - Custom CSS could make readability and accessibility worse for impaired people ## How to inspect the page -When styling the page, you can use the ``Inspector`` to inspect elements on the page and try out styles. + +When styling the page, you can use the `Inspector` to inspect elements on the page and try out styles. This may vary depending on your browser and operating system, but the workflow usually goes like this: - Open the Homarr page -- Press ``Ctrl`` + ``Shift`` + ``I`` at the same time. -Alternatively, right-click on the page and choose ``Inspect`` or ``Inspect element``. -- Open the tab ``Elements`` if it isn't open yet. +- Press `Ctrl` + `Shift` + `I` at the same time. + Alternatively, right-click on the page and choose `Inspect` or `Inspect element`. +- Open the tab `Elements` if it isn't open yet. - Search the element you want to change in the DOM tree or use the element picker (usually at the top left) -to select it by clicking on the page. + to select it by clicking on the page. - Experiment by changing the CSS code on the right side When writing custom CSS, it is important to also remember or create a selector, which tells the browser @@ -55,17 +59,19 @@ which element to apply the styles to. If you accidentally broke something or wan simply reload the page. ## Using Homarr's classes + Homarr's elements will already have a lot of classes and styles pre-applied. You can reuse those classes to apply additional styles or overwrite them. -When overwriting, remember to add the ``!important`` flag to your CSS property to tell the browser to use our instruction instead. +When overwriting, remember to add the `!important` flag to your CSS property to tell the browser to use our instruction instead. -Classes with random number suffixes, such as ``mantine-Card-x2fske``, should be avoided, since those are dynamic +Classes with random number suffixes, such as `mantine-Card-x2fske`, should be avoided, since those are dynamic CSS classes that will change with every build. This means, every time you update Homarr, your styles will no longer apply to them ## Defining custom classes for widgets + If you want to apply the styles only for one widget, you can define custom class names only for that widget. -To do that, enter edit mode on your board, click the three dots of your widget, click ``Edit item`` and click ``Advanced options``. +To do that, enter edit mode on your board, click the three dots of your widget, click `Edit item` and click `Advanced options`. Then, you can enter as many custom classes as you'd like: ![](./img/widget-custom-classes.png) @@ -73,6 +79,7 @@ Then, you can enter as many custom classes as you'd like: To save them, click `Save changes` on both modals and exit edit mode. ## Where to enter custom CSS + After you wrote your custom CSS, it is time to permanently save it, so you don't need to use the inspector anymore. To do this, enter the board settings: @@ -84,11 +91,12 @@ Here you can enter your CSS code, which will be applied on the respective board ![](./img/custom-css-setting.png) ## Using variables + You can also change the values of the theme variables, which are located here: https://mantine.dev/styles/css-variables-list/. To do this, see the following example CSS: ```css :root { - --mantine-primary-color-filled: #ffbb00; + --mantine-primary-color-filled: #ffbb00; } -``` \ No newline at end of file +``` diff --git a/apps/docs/docs/community/donate.mdx b/apps/docs/docs/community/donate.mdx index aeb95dcac..3651a2a7b 100644 --- a/apps/docs/docs/community/donate.mdx +++ b/apps/docs/docs/community/donate.mdx @@ -7,12 +7,15 @@ tags: --- # Donate + ## Why to donate + Our team of 4 developers is working on Homarr in their free time. Homarr has become a big part of our daily things we work on - and therefore we invest a lot of time into maintaining Homarr, providing support and implementing new features. We also incur monetary costs while developing Homarr for the tools that we need. A few examples include: + - Renting for a Cloud VPS for our cloud services (status page, monitoring, email, analytics, [demo instance](https://demo.homarr.dev/), ...) - Paying for (IDE-) licenses @@ -20,6 +23,7 @@ Using a donation, you help us to cover these expenses and enable the development Homarr is completely free to use. We'd highly appreciate if you consider donating, especially if you use Homarr in a commercial environment. ## Where to donate + We accept donations on our official [OpenCollective](https://opencollective.com/homarr). You may also sponsor us directly by providing a useful service / product to us other means. -You can get into contact with us [here](/docs/community/get-in-touch). \ No newline at end of file +You can get into contact with us [here](/docs/community/get-in-touch). diff --git a/apps/docs/docs/community/faq.mdx b/apps/docs/docs/community/faq.mdx index 465c7bbaf..19f2cd0e0 100644 --- a/apps/docs/docs/community/faq.mdx +++ b/apps/docs/docs/community/faq.mdx @@ -5,43 +5,57 @@ tags: - Help --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; ### Can I install Homarr on a Raspberry Pi? + Yes, Homarr is compatible with the architecture of the Raspberry Pi. Have a look in our installation guide on how to do so. ### I have a suggestion / idea for improvement or want to report a bug + You can report issues, suggestions, or ideas for improvements here. ### Can I use my own custom icons for apps? + Yes, check out our guide on how to add your custom icons. ### Some of my online icons are not working (anymore) + It seems the `cdn.jsdelivr.net` database of icon sometimes appear in the lists for DNS-Holes (PiHole, AdGuard Home...).
So make sure to manually whitelist this address. ### Can I add my own widgets? Do I need programming skills? -We have decided, not to support custom widgets, until Homarr is in a stable and highly polished state. -Enabling users to write their own widgets is easy at the first glance, but there are some major issues with it: -- There are mainly two options for adding plugins or custom widgets to Homarr. The first option is, to allow and inject custom code in Homarr. Apps like Nextcloud can do this easily, because they use the Runtime to render all components of the application (In reality, the process is still a bit more complicated). In contrast, Homarr is using Next.js - a framework that needs to be compiled in production. That means, that each time you would modify a custom widget or plugin, the app would have to be restarted. There are options to avoid this, but they are quite flakey and bring disadvantages in our experience. The second option is, to write widgets declaratively instead of imperatively. This way, we would be able to render and modify widgets without any restarting at all. However, we'd have to write our own interpreter for said declarative schema. This is totally possible, but requires a lot of planning and architecture design to function properly. The required work to implement either option is therefore quite substantial. -- Custom widgets would need to be able to request data, so they work properly. We use tRPC for this. Many APIs use different formats and we'd have to convert and read those. -- Using custom widgets, one could easily create harmful widgets, leak your personal data (potentially including your tokens) and trick your users. A proper implementation (eg. official plugin store, where we can ban harmful widgets from) would resolve this problem to a certain extent, but again requires additional work and time to be put in. +Yes. A [Custom Widget](/docs/management/custom-widgets) can read a public or private HTTP API. -If you still want to add a widget, please consider to contribute it directly to Homarr. For that, basic programming skills are required. Our [Developer Guides](/docs/advanced/development/getting-started) explain this even more detailed. +It can show responsive Mantine JSX. It can also use widget options and actions with board permission checks. + +Custom JSX v2 is the only Custom Widget format. Write the JSON and JSX in the workbench. + +You can also use the AI copy prompt. An MCP agent can validate and preview a definition before it saves the definition. + +The workbench reads a pasted AI response. It shows request capabilities and redacted diagnostics. + +A template cannot import packages or run arbitrary JavaScript. It cannot call browser `fetch`. + +Named requests use the Homarr server. The server applies board permissions and the network policy. + +Before installation, examine the origins, methods, permissions, and actions. Use the same review before publication. ### Is it secure to expose Homarr to the web? -Yes, since v0.14.0, we are confident that Homarr is secure enough to be exposed to the web. +Yes, since v0.14.0, we are confident that Homarr is secure enough to be exposed to the web. Make sure to enable the "allow anonymous access" [option in the settings](/docs/management/boards#access-control), if you want to allow people without an account to be able to see your dashboard (not edit) ### How do I open the console / log? + There are two different sources of information: + - console: This is your client (browser). It can tell us, if there is an issue on the client (crash, bug, ...). - log: This is your server. It will tell us, if there are issues with connections for the integrations, crashes and errors. -Both variants *can* contain personal data. It's recommended, that you don't post them publicly or remove personal data from it. +Both variants _can_ contain personal data. It's recommended, that you don't post them publicly or remove personal data from it. @@ -49,39 +63,45 @@ Both variants *can* contain personal data. It's recommended, that you don't post > Note: This will not work on most mobile browsers. Open your browser and ensure, that Homarr is your current tab. -Press ``CTRL`` + ``SHIFT`` + ``I`` on your keyboard. If this shortcut doesn't work, please use one of the alternatives: https://developer.chrome.com/docs/devtools/open/. -Click on ``Console`` in the new window, that opened. There, you should see white, orange and sometimes red messages. You can use the Windows Snip & Sketch tool (or your respective tool on Linux / MacOS) to screenshot those messages. +Press `CTRL` + `SHIFT` + `I` on your keyboard. If this shortcut doesn't work, please use one of the alternatives: https://developer.chrome.com/docs/devtools/open/. +Click on `Console` in the new window, that opened. There, you should see white, orange and sometimes red messages. You can use the Windows Snip & Sketch tool (or your respective tool on Linux / MacOS) to screenshot those messages. > Please never execute any commands in the console. Scammers are using the console to let you execute harmful commands. If you want to resolve an issue in Homarr, **you'll never have to execute any commands here** -This depends on your installation method. If you use Unraid, you can simply click on the App and on ``Log``. If you have a bare Docker install, use ``docker container logs homarr``. If you used a different name than ``homarr`` for your container, you need to replace said argument. Here is some additional information about the command: https://geekflare.com/check-docker-logs/. +This depends on your installation method. If you use Unraid, you can simply click on the App and on `Log`. If you have a bare Docker install, use `docker container logs homarr`. If you used a different name than `homarr` for your container, you need to replace said argument. Here is some additional information about the command: https://geekflare.com/check-docker-logs/. ### How do I post logs? + Please check [the section above](#how-do-i-open-the-console--log), on how to obtain logs. Logs should always be posted to https://pastebin.com/ or https://rentry.co/. ### Can I use Homarr at my company? + Yes, you can! But please consider a donation, if our work has been useful to you. ### I think I found a bug. What can I do? + If you think, that you found a bug, please create an issue here. ### Why can't I use my custom icons? + You need to restart the Homarr Docker container after adding icons. ### Why can't homarr see/ping containers running locally behind GluetunVPN? + This is because GluetunVPN, and many other docker VPN services, secure their VPN connections with strict firewalls. These firewalls often block access to local containers, even on the same docker network. The workaround for GluetunVPN is to add "- FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24" into the environmental variables of the docker compose file. If you are using a firewall on your system, you will need to add a rule that allows requests from ip's in the range of 192.168.xxx.xxx . If you are using UFW the command would be "sudo ufw allow from 192.168.0.0/16". Tip: If you are running your torrent client behind a VPN, and running Sonarr (or something similar) normally, make sure to open your torrent client's port in your firewall. If you don't, Sonarr will not be able to see it. Furthermore, use your machines IP (192.168.x.x) rather then 127.0.0.1 or localhost. ### Can I get in touch with you? + Yes, go here to get with us in touch. -
+
:::tip diff --git a/apps/docs/docs/community/get-in-touch.mdx b/apps/docs/docs/community/get-in-touch.mdx index 7651f5ea2..eecd2e1f3 100644 --- a/apps/docs/docs/community/get-in-touch.mdx +++ b/apps/docs/docs/community/get-in-touch.mdx @@ -9,16 +9,16 @@ tags: We're happy to talk with you! Shoot us a message at the following places: ## E-Mail + We are open to discuss sponsorships, security vulnerabilities and other private requests through our email. Please do not report any bugs / feature requests here - they will be ignored and deleted. [homarr-labs@proton.me](mailto:homarr-labs@proton.me) ## Discord + We have a Discord Server, where we announce new releases, discuss features and bugs and show off our dashboards. There are over 4'000 members and we're happy to answer your questions or concerns. You're also open to discuss new / upcoming features and any offtopic selfhosting content. [_![](https://discordapp.com/api/guilds/972958686051962910/widget.png?style=banner2)_](https://discord.gg/aCsmEV5RgA) - - diff --git a/apps/docs/docs/community/license.mdx b/apps/docs/docs/community/license.mdx index e36a5d684..3d1f82890 100644 --- a/apps/docs/docs/community/license.mdx +++ b/apps/docs/docs/community/license.mdx @@ -7,6 +7,7 @@ tags: Homarr is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). ## TL;DR + | Action | Allowed | | -------------- | ------- | | Copy | ✅ | @@ -24,8 +25,6 @@ Please consider [making a donation](/docs/community/donate) to Homarr, if this p ::: - - ## Full License ```txt diff --git a/apps/docs/docs/community/translations.mdx b/apps/docs/docs/community/translations.mdx index 074db939d..68eea8a1e 100644 --- a/apps/docs/docs/community/translations.mdx +++ b/apps/docs/docs/community/translations.mdx @@ -5,30 +5,31 @@ tags: - Translations --- -We want to make Homarr accessible for everyone. -But to do that, we need your help. -We are running a community program that enables everyone to translate Homarr into their language – no programming required. -We are using [Crowdin](https://crowdin.com/) to manage our translations. +We want to make Homarr accessible for everyone. +But to do that, we need your help. +We are running a community program that enables everyone to translate Homarr into their language – no programming required. +We are using [Crowdin](https://crowdin.com/) to manage our translations. You can find the translations [here](https://translate.homarr.dev/). ## How to translate - ### Using crowdin's online platform -Go to the [Crowdin translations](https://translate.homarr.dev/) and select a language you want to translate. -You can then enter the translation mode and start translating. -After you've submitted your translations, a Proofreader will review your changes. -After a translation has been approved, it will be merged to the language development branch. -We merge this one periodically to the development branch. + +Go to the [Crowdin translations](https://translate.homarr.dev/) and select a language you want to translate. +You can then enter the translation mode and start translating. +After you've submitted your translations, a Proofreader will review your changes. +After a translation has been approved, it will be merged to the language development branch. +We merge this one periodically to the development branch. After the next update of Homarr, all changes from the development branch will be merged, including the changes in the translations. ### Using live translate + You can also help translate homarr directly from the app! For this you can simply change your language to "Crowdin (live translations)" ![](./img/crowdin-language-select.png) -Then you'll be prompted to connect to your Crowdin account and choose the language in which you want to transalte. +Then you'll be prompted to connect to your Crowdin account and choose the language in which you want to transalte. You can then start translating directly from the app by selecting some text on the app. If some text cannot be selected to be edited with the live translation tool, you can still translate it inside of the In-Context popup at the Home tab, it will be red if it's not translated yet. @@ -47,7 +48,8 @@ Do you want to become a proofreader? [Let us know on our Discord](/docs/communit ::: ## Guidelines + 1. Translate with context: Some translations can't be translated 1:1 - they need context. Ensure that your translations make sense in the context. 2. Keep things simple and original - no additional characters are needed. 3. Don't translate the same thing twice - if you see a translation that is already translated, don't translate it again unless you have a better translation. -5. Keep your translations as close to the original as possible. +4. Keep your translations as close to the original as possible. diff --git a/apps/docs/docs/getting-started/after-the-installation.mdx b/apps/docs/docs/getting-started/after-the-installation.mdx index 7ac904bf4..00ed4c6b2 100644 --- a/apps/docs/docs/getting-started/after-the-installation.mdx +++ b/apps/docs/docs/getting-started/after-the-installation.mdx @@ -54,11 +54,7 @@ You must choose a username and password (both can later be changed). We enforce strict password requirements when you enter your password to protect your instance if you accidentally expose it to the internet. -{"Screenshot +{"Screenshot If you selected external providers (such as LDAP or OIDC), you'll be prompted to create an admin group. This group will be used to synchronize users from your provider to Homarr. @@ -116,22 +112,14 @@ The onboarding can no longer be started again. From here you can click on one of the provided links to continue your journey. We recommend you to continue with the section [creating your first board on this page](#creating-your-first-board). -{"Screenshot +{"Screenshot ### Importing a ZIP from version before 1.0.0 This is recommended when you used Homarr before and want to re-import your data. It is important that you first migrate correctly using [the list of breaking changes for 1.0](/blog/2024/09/23/version-1.0). -Export from old Homarr +Export from old Homarr **How to export and import data** @@ -197,38 +185,23 @@ Here you have the following options in the header: When entering the edit mode, you'll get some additional buttons to work with: -{"Screenshot +{"Screenshot - **Add item**: Click this button to add new elements to your page. - **Exit edit mode**: Click this btuton to save your changes and exit edit mode. To continue, click the option "New Item": -{"Screenshot +{"Screenshot Next, you can choose what item you'd like to add. We will discuss the other options in the following sections - for now choose "App" to continue. -{"Screenshot +{"Screenshot As soon as you chose the app, the modal will close and you'll get the following item on your board: -Screenshot of the No app element on the board +Screenshot of the No app element on the board This is expected, because you haven't told Homarr what app it should show in this item. To configure this, click on the small 3 dots at the top of the item in the edit mode and choose "Edit item" in the menu. diff --git a/apps/docs/docs/getting-started/glossary.mdx b/apps/docs/docs/getting-started/glossary.mdx index 8d690245c..ee6301ee8 100644 --- a/apps/docs/docs/getting-started/glossary.mdx +++ b/apps/docs/docs/getting-started/glossary.mdx @@ -1,8 +1,9 @@ # Glossary + In the glossary, you'll learn the different components and their names of Homarr. | Term | Definition | -|-----------------|----------------------------------------------------------------------------------------------------------------| +| --------------- | -------------------------------------------------------------------------------------------------------------- | | Apps | An piece of software that you or a third party hosts (eg. Google) | | Integration | A connection to a service outside of Homarr | | Dynamic section | Resizeable area where items on your board can be placed and grouped | diff --git a/apps/docs/docs/getting-started/index.mdx b/apps/docs/docs/getting-started/index.mdx index 4dc986658..0d6a44a4e 100644 --- a/apps/docs/docs/getting-started/index.mdx +++ b/apps/docs/docs/getting-started/index.mdx @@ -8,13 +8,14 @@ tags: - Unraid --- -import Link from '@docusaurus/Link'; -import { IconArrowRight } from '@tabler/icons-react'; +import Link from "@docusaurus/Link"; +import { IconArrowRight } from "@tabler/icons-react"; Before you try to install Homarr, please review if your device meets the requirements. Installing on an unsupported device may lead to unstable behaviour and no support will be provided. ## Hardware + - At least 500MB RAM - At least 600MB of free disk space for the Docker image. SSD is preferred. - Single or dual core CPU @@ -24,8 +25,8 @@ Installing on an unsupported device may lead to unstable behaviour and no suppor We build Homarr for a bunch of different architectures, including ARM. Please ensure that your device architecture is supported by Homarr. We won't be able to provide support for unusual or outdated architectures. -| Architecture | Supported | -|--------------|-----------------| +| Architecture | Supported | +| ------------ | ---------------- | | linux/amd64 | ✅ Supported | | linux/arm64 | ✅ Supported | | linux/arm/v7 | ❌ Not supported | @@ -34,10 +35,10 @@ We build Homarr for a bunch of different architectures, including ARM. Please en -
+
Go to Installation
diff --git a/apps/docs/docs/getting-started/installation/docker.mdx b/apps/docs/docs/getting-started/installation/docker.mdx index 956a6c2d6..5a56a848a 100644 --- a/apps/docs/docs/getting-started/installation/docker.mdx +++ b/apps/docs/docs/getting-started/installation/docker.mdx @@ -1,21 +1,23 @@ -import { DockerInstallSnippet } from '@site/src/components/pages/installation/docker/dynamic-docker-install' +import { DockerInstallSnippet } from "@site/src/components/pages/installation/docker/dynamic-docker-install"; # Docker + Docker is our recommended installation method for beginners and professionals. It is easy to use, ships with all dependencies inside a single container and is easy to use and maintain. It requires at least some basic knowledge of [Docker](https://www.docker.com/). We recommend [NetworkChuck's Docker Containers 101](https://www.youtube.com/watch?v=eGz9DS-aIeY) as a good start for complete beginners. ## Docker compose + ### Prerequisites - A Linux or Windows based system that meets the [hardware prerequisites](/docs/getting-started/#hardware) and [architecture prerequisites](/docs/getting-started/#architecture). - [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) - *preinstalled on many systems nowadays* +- [Docker Compose](https://docs.docker.com/compose/install/) - _preinstalled on many systems nowadays_ ### Installation - + Finally, run ``docker compose up -d`` in the same directory. This will start the Homarr container in the background. :::caution @@ -26,27 +28,26 @@ Docker compose creates a network by default. Some integrations may not work (spe ### Updating -To update, navigate to the directory with the ``docker-compose.yaml`` located. +To update, navigate to the directory with the `docker-compose.yaml` located. -- Stop Homarr using ``docker compose down`` -- Pull the newest image of Homarr using ``docker compose pull`` -- Start Homarr again using ``docker compose up -d`` (``-d`` for detached mode - start in background) -- Delete the old image using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*) +- Stop Homarr using `docker compose down` +- Pull the newest image of Homarr using `docker compose pull` +- Start Homarr again using `docker compose up -d` (`-d` for detached mode - start in background) +- Delete the old image using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_) You can automate this process using [Watchtower](https://containrrr.dev/watchtower/). ### Uninstalling -To uninstall, navigate to the directory with the ``docker-compose.yaml`` located. +To uninstall, navigate to the directory with the `docker-compose.yaml` located. -- Stop Homarr using ``docker compose down`` -- Delete the created directories & files on your root file system (check ``docker-compose.yaml`` file for your specific locations) -- Delete compose file using ``rm docker-compose.yaml`` -- Prune unused Docker images using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*) +- Stop Homarr using `docker compose down` +- Delete the created directories & files on your root file system (check `docker-compose.yaml` file for your specific locations) +- Delete compose file using `rm docker-compose.yaml` +- Prune unused Docker images using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_) - (Optional): Prune any network or volumes if you use any. - (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any. - ## Docker standalone :::caution @@ -77,15 +78,16 @@ docker run \ :::note -Docker will mount the configuration files and icons to your host machine. Please make sure to replace ```` from the docker run command with your desired storage location. The path must be absolute. +Docker will mount the configuration files and icons to your host machine. Please make sure to replace `` from the docker run command with your desired storage location. The path must be absolute. ::: ### Updating + To update Homarr, you must remove your container first. Make sure that you've mounted your data and that you have access to it, so your configuration doesn't get lost. -1. Run ``docker rm homarr`` to remove the container. -2. Pull the latest Homarr image ``docker pull ghcr.io/homarr-labs/homarr:latest``. +1. Run `docker rm homarr` to remove the container. +2. Pull the latest Homarr image `docker pull ghcr.io/homarr-labs/homarr:latest`. 3. Re-run the command you used to install Homarr. This process can get tideous, if you update frequently. Thus, we recommend [using docker-compose](#docker-compose) @@ -98,8 +100,8 @@ Want to update all your containers automatically? Checkout [Watchtower](https:// ### Uninstalling -1. Obtain the container ID of your Homarr container using ``docker ps | grep homarr``. -2. Delete the container using ``docker rm `` -3. Prune unused Docker images using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*) +1. Obtain the container ID of your Homarr container using `docker ps | grep homarr`. +2. Delete the container using `docker rm ` +3. Prune unused Docker images using `docker image prune` (_Warning: this also removes you other unused images - not just Homarr_) 4. (Optional): Prune any network or volumes if you use any. 5. (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any. diff --git a/apps/docs/docs/getting-started/installation/helm.md b/apps/docs/docs/getting-started/installation/helm.md index 039f76ed4..75f132d14 100644 --- a/apps/docs/docs/getting-started/installation/helm.md +++ b/apps/docs/docs/getting-started/installation/helm.md @@ -12,7 +12,7 @@ A Helm chart to deploy homarr for Kubernetes ## Source Code -* +- ## Requirements @@ -76,38 +76,38 @@ To avoid including sensitive information in plain text within your version contr Below is an exhaustive list of all secrets: -| FEATURE | SECRET NAME | SECRET KEYS | Required | -|-----------|-------------------------|-----------------------------------------|----------| -| OIDC | auth-oidc-secret | oidc-client-id
oidc-client-secret | No | -| LDAP | auth-ldap-secret | bind-password | No | -| DATABASE | db-secret | db-url | No | -| DATABASE | db-encryption | db-encryption-key | yes | +| FEATURE | SECRET NAME | SECRET KEYS | Required | +| -------- | ---------------- | ------------------------------------ | -------- | +| OIDC | auth-oidc-secret | oidc-client-id
oidc-client-secret | No | +| LDAP | auth-ldap-secret | bind-password | No | +| DATABASE | db-secret | db-url | No | +| DATABASE | db-encryption | db-encryption-key | yes | ### Database You have multiple options for configuring the database: -| DRIVER TYPE | Persistence mode | -|----------------|---------------------------------| -| better-sqlite3 | Pod disk | -| better-sqlite3 | homarr-database PVC | -| mysql2 | External MySql database | -| node-postgres | External Postgresql database | +| DRIVER TYPE | Persistence mode | +| -------------- | ---------------------------- | +| better-sqlite3 | Pod disk | +| better-sqlite3 | homarr-database PVC | +| mysql2 | External MySql database | +| node-postgres | External Postgresql database | #### Pod disk -No additional configuration is required. However, keep in mind that if the pod restarts, all data will be lost. This setup is not *recommended* for production use. +No additional configuration is required. However, keep in mind that if the pod restarts, all data will be lost. This setup is not _recommended_ for production use. To create the necessary database secret, execute the following command:
Required Secrets -````yaml +```yaml kubectl create secret generic db-encryption \ --from-literal=db-encryption-key='' \ --namespace homarr -```` +```
@@ -120,11 +120,11 @@ Associated secret to create :
DB Required Secrets -````yaml +```yaml kubectl create secret generic db-encryption \ --from-literal=db-encryption-key='' \ --namespace homarr -```` +```
@@ -133,13 +133,13 @@ Bellow an example of the override value file :
values.yaml -````yaml +```yaml persistence: homarrDatabase: enabled: true storageClassName: "default" size: "1Gi" -```` +```
@@ -150,17 +150,18 @@ To create the necessary database secrets, execute the following command:
Required Secrets -````yaml +```yaml kubectl create secret generic db-encryption \ --from-literal=db-encryption-key='' \ --namespace homarr -```` +``` -````yaml +```yaml kubectl create secret generic db-secret \ --from-literal=db-url='mysql://user:password@host:port/homarrdb' \ --namespace homarr -```` +``` +
Below is an example of the override values file: @@ -168,10 +169,11 @@ Below is an example of the override values file:
values.yaml -````yaml +```yaml database: type: mysql -```` +``` +
#### External Postgresql database @@ -181,17 +183,17 @@ To create the necessary database secrets, execute the following command:
Required Secrets -````yaml +```yaml kubectl create secret generic db-encryption \ --from-literal=db-encryption-key='' \ --namespace homarr -```` +``` -````yaml +```yaml kubectl create secret generic db-secret \ --from-literal=db-url='postgresql://user:password@host:port/homarrdb' \ --namespace homarr -```` +```
@@ -200,10 +202,11 @@ Below is an example of the override values file:
values.yaml -````yaml +```yaml database: type: postgresql -```` +``` +
### Ingress @@ -213,7 +216,7 @@ The ingress section in the values.yaml file allows you to configure how external
values.yaml -````yaml +```yaml service: enabled: true # Ensure the service is enabled for Ingress to route traffic ingress: @@ -231,7 +234,8 @@ ingress: - "homarr.homelab.dev" - "www.homarr.homelab.dev" secretName: homelab-tls -```` +``` +
### HTTPRoute (Gateway API) @@ -242,9 +246,9 @@ This provides a more expressive and future-proof alternative to Ingress, with su
values.yaml -````yaml +```yaml service: - enabled: true # must be enabled for HTTPRoute to forward traffic + enabled: true # must be enabled for HTTPRoute to forward traffic httproute: enabled: true parentRefs: @@ -260,14 +264,15 @@ httproute: backendRefs: - name: homarr port: 8080 -```` +``` +
#### Notes: - parentRefs: the Gateway(s) this route attaches to. Gateways must already exist. - hostnames: domain names this route applies to. -- rules: each rule can define matches (paths, headers, queries), optional filters, and backendRefs to services +- rules: each rule can define matches (paths, headers, queries), optional filters, and backendRefs to services - TLS must be configured on the Gateway (not on HTTPRoute). For example, the Gateway can have a TLS listener for homarr.homelab.dev, and this route will automatically apply once matched. ### Certificates @@ -284,7 +289,7 @@ Use inline certificates to generate a ConfigMap, mounted as individual files.
values.yaml -````yaml +```yaml persistence: homarrTrustedCerts: enabled: true @@ -298,7 +303,8 @@ persistence: -----BEGIN CERTIFICATE----- MIID...EFGH== -----END CERTIFICATE----- -```` +``` +
Behavior: @@ -313,7 +319,7 @@ Use inline certificates to generate a Kubernetes Secret, mounted as files.
values.yaml -````yaml +```yaml persistence: homarrTrustedCerts: enabled: true @@ -327,7 +333,8 @@ persistence: -----BEGIN CERTIFICATE----- MIIC...XYZ== -----END CERTIFICATE----- -```` +``` +
Behavior: @@ -342,16 +349,17 @@ Use an existing Kubernetes Secret, assuming its keys are filenames.
values.yaml -````yaml +```yaml persistence: homarrTrustedCerts: enabled: true type: existingSecret existingSecretName: "existingSecretName" existingSecretKeys: - - cert3.crt - - cert4.crt -```` + - cert3.crt + - cert4.crt +``` +
Behavior: @@ -372,114 +380,115 @@ All available values are listed on the [artifacthub](https://artifacthub.io/pack ## Values -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| additionalObjects | list | `[]` | Additional resources to deploy. These objects are templated. | -| affinity | object | `{}` | Node affinity for pod scheduling | -| autoscaling.enabled | bool | `false` | Enable autoscaling | -| autoscaling.maxReplicas | int | `100` | Maximum replicas | -| autoscaling.minReplicas | int | `1` | Minimum replicas | -| autoscaling.targetCPUUtilizationPercentage | int | `80` | Target CPU utilization for autoscaling | -| containerPorts | object | `{"http":{"port":7575,"protocol":"TCP"}}` | containerPorts defines the ports to open on the container. It is a map where each entry specifies: - `port` (int) (required): The port number to expose inside the container. - `protocol` (string) (required): The network protocol (TCP or UDP) used for the port. - `disabled` (bool) : Optional flag to disable this port (defaults to false). Can be overridden via Helm values. By default, this configuration exposes TCP port 7575 with the name `http`. | -| database.migrationEnabled | bool | `true` | Database migration configuration. DB_MIGRATIONS_DISABLED Set to `true` to disable database migrations. Migrations are enabled by default (`false`). | -| database.type | string | `"sqlite"` | Database type: sqlite, mysql or postgresql | -| env.AUTH_COOKIE_PREFIX | string | `"homarr"` | Prefix used for all authentication cookies. Change if you run another Auth.js/NextAuth app on the same hostname to avoid cookie name collisions. Only letters, numbers, hyphens and underscores. | -| env.AUTH_LDAP_BASE | string | `nil` | Base dn of your LDAP server | -| env.AUTH_LDAP_BIND_DN | string | `nil` | User used for finding users and groups | -| env.AUTH_LDAP_GROUP_CLASS | string | `"groupOfUniqueNames"` | Class used for querying groups | -| env.AUTH_LDAP_GROUP_FILTER_EXTRA_ARG | string | `nil` | Extra arguments for user's groups search filter (& based) | -| env.AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE | string | `"member"` | Attribute used for querying group member | -| env.AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE | string | `"dn"` | User attribute used for comparing with group member | -| env.AUTH_LDAP_SEARCH_SCOPE | string | `"base"` | LDAP search scope between base, one or sub | -| env.AUTH_LDAP_URI | string | `nil` | URI of your LDAP server | -| env.AUTH_LDAP_USERNAME_ATTRIBUTE | string | `"uid"` | Attribute used for username | -| env.AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG | string | `nil` | Extra arguments for user search filter (& based) | -| env.AUTH_LDAP_USER_MAIL_ATTRIBUTE | string | `"mail"` | Attribute used for mail field | -| env.AUTH_LOGOUT_REDIRECT_URL | string | `nil` | URL to redirect to after clicking logging out. | -| env.AUTH_OIDC_AUTO_LOGIN | string | `"false"` | Automatically redirect to OIDC login | -| env.AUTH_OIDC_CLIENT_NAME | string | `"OIDC"` | Display name of provider (in login screen) | -| env.AUTH_OIDC_GROUPS_ATTRIBUTE | string | `"groups"` | Attribute used for groups (roles) claim | -| env.AUTH_OIDC_ISSUER | string | `nil` | Issuer URI of OIDC provider without trailing slash (/) | -| env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE | string | `nil` | Overwrite name attribute. By default, it will use preferred_username if it does not contain a @ and otherwise name. | -| env.AUTH_OIDC_SCOPE_OVERWRITE | string | `"openid email profile groups"` | Override the OIDC scopes | -| env.AUTH_PROVIDERS | string | `"credentials"` | Enabled authentication methods. Multiple providers can be enabled with by separating them with , (ex. AUTH_PROVIDERS=credentials,oidc, it is highly recommended to just enable one provider). | -| env.AUTH_SESSION_EXPIRY_TIME | string | `"30d"` | Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m") | -| env.ENABLE_DNS_CACHING | string | `"false"` | Enables dns caching. This is not yet working for all users. See #4006 | -| env.LOG_LEVEL | string | `"info"` | Log level to use. Possible values: debug/info/warn/error | -| env.NO_EXTERNAL_CONNECTION | string | `"false"` | Disables some requests that need internet connection | -| env.TZ | string | `"Europe/Paris"` | Your local time zone | -| envSecrets.authLdapCredentials.existingSecret | string | `"auth-ldap-secret"` | Name of existing secret containing LDAP credentials | -| envSecrets.authLdapCredentials.ldapBindingPassword | string | `"bind-password"` | Password for bind user secret key | -| envSecrets.authOidcCredentials.existingSecret | string | `"auth-oidc-secret"` | Name of existing secret containing OIDC credentials | -| envSecrets.authOidcCredentials.oidcClientId | string | `"oidc-client-id"` | ID of OIDC client (application) secret key | -| envSecrets.authOidcCredentials.oidcClientSecret | string | `"oidc-client-secret"` | Secret of OIDC client (application) secret key | -| envSecrets.dbCredentials.dbUrlKey | string | `"db-url"` | Secret key for DB_URL Example for external database: `mysql://username:password@host:port/homarrdb` or `postgresql://username:password@host:port/homarrdb` | -| envSecrets.dbCredentials.existingSecret | string | `"db-secret"` | Name of existing secret containing DB credentials | -| envSecrets.dbEncryption.existingSecret | string | `"db-encryption"` | Name of existing secret containing DB encryption | -| envSecrets.dbEncryption.key | string | `"db-encryption-key"` | Secret key for SECRET_ENCRYPTION_KEY can be generated with `openssl rand -hex 32` | -| fullnameOverride | string | `""` | Overrides chart's fullname | -| hostAliases | list | `[]` | Add static entries to /etc/hosts in the Pod. This is useful in the following cases: - You are running in a dual-stack cluster (IPv4 + IPv6) and want to force usage of IPv4 for specific hostnames - Your application is having DNS resolution issues or IPv6 preference issues - You need to override or simulate DNS entries without changing global DNS - You are running in an air-gapped or isolated environment without external DNS Example: hostAliases: - ip: "192.168.1.10" hostnames: - "example.com" - "example.internal" | -| httproute | object | `{"enabled":false,"hostnames":["chart-example.local"],"parentRefs":[{"name":"my-gateway","namespace":"default"}],"rules":[{"backendRefs":[{"name":"homarr","port":8080}],"filters":[],"matches":[{"path":{"type":"PathPrefix","value":"/"}}]}]}` | Gateway API HTTPRoute configuration | -| httproute.enabled | bool | `false` | Enable HTTPRoute | -| httproute.hostnames | list | `["chart-example.local"]` | Hostnames this route matches (similar to ingress.hosts.host) | -| httproute.parentRefs | list | `[{"name":"my-gateway","namespace":"default"}]` | References to the parent Gateway(s) this route attaches to. Each item must include at least a `name`, and optionally a `namespace`. | -| httproute.rules | list | `[{"backendRefs":[{"name":"homarr","port":8080}],"filters":[],"matches":[{"path":{"type":"PathPrefix","value":"/"}}]}]` | List of routing rules. Each rule can include: - matches: path/header/query matching - filters: optional transformations (redirects, header modifications, etc.) - backendRefs: one or more Kubernetes Services to forward traffic to | -| httproute.rules[0].filters | list | `[]` | Optional filters for this rule (default: empty) | -| httproute.rules[0].matches[0].path.type | string | `"PathPrefix"` | Path match type. One of: Exact, PathPrefix, RegularExpression | -| 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.70.0"` | 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 | -| ingress.hosts | list | `[{"host":"chart-example.local","paths":[{"path":"/"}]}]` | Ingress hosts configuration | -| ingress.ingressClassName | string | `""` | Ingress class name | -| ingress.tls | list | `[]` | Ingress TLS configuration | -| livenessProbe.failureThreshold | int | `3` | Failure threshold for liveness probe - number of consecutive failures before pod is restarted | -| livenessProbe.httpGet.path | string | `"/api/health/live"` | This is the liveness check endpoint used by Kubernetes to determine if the application is still running. | -| livenessProbe.httpGet.port | int | `7575` | The port on which the liveness check will be performed. This must be the same as the container port exposed by the application. | -| livenessProbe.initialDelaySeconds | int | `10` | Initial delay in seconds before the liveness probe starts | -| livenessProbe.periodSeconds | int | `10` | Period in seconds between liveness probe checks | -| livenessProbe.timeoutSeconds | int | `1` | Timeout in seconds for each liveness probe check | -| nameOverride | string | `""` | Overrides chart's name | -| nodeSelector | object | `{}` | Node selectors for pod scheduling | -| persistence.homarrDatabase.accessMode | string | `"ReadWriteOnce"` | homarr-database access mode | -| persistence.homarrDatabase.enabled | bool | `false` | Enable homarr-database persistent storage | -| persistence.homarrDatabase.mountPath | string | `"/appdata"` | homarr-database mount path inside the pod | -| persistence.homarrDatabase.name | string | `"homarr-database"` | homarr-database persistent storage name | -| persistence.homarrDatabase.size | string | `"50Mi"` | homarr-database storage size | -| persistence.homarrDatabase.storageClassName | string | `"local-path"` | homarr-database storage class name | -| persistence.homarrDatabase.volumeClaimName | string | `""` | homarr-database optional volumeClaimName to target specific PV | -| persistence.homarrTrustedCerts.certificates | string | `nil` | homarr-trusted-certificates certificates, each entry will become a new trusted certificate as a dedicated file (works only for "configmap" and "secret" mode) | -| persistence.homarrTrustedCerts.enabled | bool | `false` | Enable trusted certificates persistence | -| persistence.homarrTrustedCerts.existingSecretKeys | string | `nil` | List of keys (filenames) to mount from the existing secret (used only when type is "existingSecret") | -| persistence.homarrTrustedCerts.existingSecretName | string | `""` | Name of the existing Kubernetes Secret to mount (required if type is "existingSecret") | -| persistence.homarrTrustedCerts.mountPath | string | `"/appdata/trusted-certificates"` | homarr-trusted-certificates mount path inside the pod | -| persistence.homarrTrustedCerts.type | string | `"configmap"` | Persistence mode can be : configmap (declarative), secret (declarative) or existingSecret (mount an existing Kubernetes Secret by name and specify which keys to mount as files) | -| podAnnotations | object | `{}` | Pod annotations | -| podLabels | object | `{}` | Pod labels | -| podSecurityContext | object | `{}` | Pod security context | -| rbac | object | `{"enabled":false}` | Enable RBAC resources for Kubernetes integration Creates Role, ClusterRole, and associated bindings for Homarr's Kubernetes features | -| rbac.enabled | bool | `false` | Enable to create RBAC resources and activate Kubernetes integration | -| readinessProbe.failureThreshold | int | `3` | Failure threshold for readiness probe - number of consecutive failures before pod is considered unready | -| readinessProbe.httpGet.path | string | `"/api/health/ready"` | This is the readiness check endpoint used by Kubernetes to determine if the application is ready to handle traffic. | -| readinessProbe.httpGet.port | int | `7575` | The port on which the readiness check will be performed. This must match the container's exposed port. | -| readinessProbe.initialDelaySeconds | int | `10` | Initial delay in seconds before the readiness probe starts. increase this value if the pod is slow to fully start. | -| readinessProbe.periodSeconds | int | `10` | Period in seconds between readiness probe checks | -| readinessProbe.timeoutSeconds | int | `1` | Timeout in seconds for each readiness probe check | -| replicaCount | int | `1` | Number of replicas | -| resources | object | `{}` | Resource configuration | -| securityContext | object | `{}` | Security context | -| service.enabled | bool | `true` | Enable service | -| service.ipFamilies | list | `[]` | List of IP families to use for the service. Examples: - ["IPv4"] - ["IPv6"] - ["IPv4", "IPv6"] for dual-stack Leave empty to use cluster default behavior | -| service.ipFamilyPolicy | string | `"SingleStack"` | Defines how the service assigns IP families (IPv4/IPv6) Possible values: - SingleStack (default): Only one IP family, usually IPv4 - PreferDualStack: Use dual-stack if the cluster supports it, fallback to single - RequireDualStack: Fail if dual-stack cannot be assigned | -| service.ports.app.port | int | `7575` | Service port | -| service.ports.app.protocol | string | `"TCP"` | Service protocol | -| service.ports.app.targetPort | string | `"http"` | Service target port | -| service.type | string | `"ClusterIP"` | Service type | -| strategyType | string | `"RollingUpdate"` | `strategyType` specifies the strategy used to replace old Pods by new ones. `strategyType` can be `"Recreate"` or `"RollingUpdate"`. `"RollingUpdate"` is the default value and updates Pods in a rolling update fashion. `"Recreate"` will kill all existing Pods before new ones are created. The `"Recreate"` strategy is necessary when persistent volume's `accessMode` is set to `"ReadWriteOnce"` when using `helm upgrade`, as pod volume attachments to an existing PersistentVolumeClaim need to be cleared before a new pod can attach to it. | -| tolerations | list | `[]` | Node tolerations for pod scheduling | +| Key | Type | Default | Description | +| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| additionalObjects | list | `[]` | Additional resources to deploy. These objects are templated. | +| affinity | object | `{}` | Node affinity for pod scheduling | +| autoscaling.enabled | bool | `false` | Enable autoscaling | +| autoscaling.maxReplicas | int | `100` | Maximum replicas | +| autoscaling.minReplicas | int | `1` | Minimum replicas | +| autoscaling.targetCPUUtilizationPercentage | int | `80` | Target CPU utilization for autoscaling | +| containerPorts | object | `{"http":{"port":7575,"protocol":"TCP"}}` | containerPorts defines the ports to open on the container. It is a map where each entry specifies: - `port` (int) (required): The port number to expose inside the container. - `protocol` (string) (required): The network protocol (TCP or UDP) used for the port. - `disabled` (bool) : Optional flag to disable this port (defaults to false). Can be overridden via Helm values. By default, this configuration exposes TCP port 7575 with the name `http`. | +| database.migrationEnabled | bool | `true` | Database migration configuration. DB_MIGRATIONS_DISABLED Set to `true` to disable database migrations. Migrations are enabled by default (`false`). | +| database.type | string | `"sqlite"` | Database type: sqlite, mysql or postgresql | +| env.AUTH_COOKIE_PREFIX | string | `"homarr"` | Prefix used for all authentication cookies. Change if you run another Auth.js/NextAuth app on the same hostname to avoid cookie name collisions. Only letters, numbers, hyphens and underscores. | +| env.AUTH_LDAP_BASE | string | `nil` | Base dn of your LDAP server | +| env.AUTH_LDAP_BIND_DN | string | `nil` | User used for finding users and groups | +| env.AUTH_LDAP_GROUP_CLASS | string | `"groupOfUniqueNames"` | Class used for querying groups | +| env.AUTH_LDAP_GROUP_FILTER_EXTRA_ARG | string | `nil` | Extra arguments for user's groups search filter (& based) | +| env.AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE | string | `"member"` | Attribute used for querying group member | +| env.AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE | string | `"dn"` | User attribute used for comparing with group member | +| env.AUTH_LDAP_SEARCH_SCOPE | string | `"base"` | LDAP search scope between base, one or sub | +| env.AUTH_LDAP_URI | string | `nil` | URI of your LDAP server | +| env.AUTH_LDAP_USERNAME_ATTRIBUTE | string | `"uid"` | Attribute used for username | +| env.AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG | string | `nil` | Extra arguments for user search filter (& based) | +| env.AUTH_LDAP_USER_MAIL_ATTRIBUTE | string | `"mail"` | Attribute used for mail field | +| env.AUTH_LOGOUT_REDIRECT_URL | string | `nil` | URL to redirect to after clicking logging out. | +| env.AUTH_OIDC_AUTO_LOGIN | string | `"false"` | Automatically redirect to OIDC login | +| env.AUTH_OIDC_CLIENT_NAME | string | `"OIDC"` | Display name of provider (in login screen) | +| env.AUTH_OIDC_GROUPS_ATTRIBUTE | string | `"groups"` | Attribute used for groups (roles) claim | +| env.AUTH_OIDC_ISSUER | string | `nil` | Issuer URI of OIDC provider without trailing slash (/) | +| env.AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE | string | `nil` | Overwrite name attribute. By default, it will use preferred_username if it does not contain a @ and otherwise name. | +| env.AUTH_OIDC_SCOPE_OVERWRITE | string | `"openid email profile groups"` | Override the OIDC scopes | +| env.AUTH_PROVIDERS | string | `"credentials"` | Enabled authentication methods. Multiple providers can be enabled with by separating them with , (ex. AUTH_PROVIDERS=credentials,oidc, it is highly recommended to just enable one provider). | +| env.AUTH_SESSION_EXPIRY_TIME | string | `"30d"` | Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m") | +| env.ENABLE_DNS_CACHING | string | `"false"` | Enables dns caching. This is not yet working for all users. See #4006 | +| env.LOG_LEVEL | string | `"info"` | Log level to use. Possible values: debug/info/warn/error | +| env.NO_EXTERNAL_CONNECTION | string | `"false"` | Disables some requests that need internet connection | +| env.TZ | string | `"Europe/Paris"` | Your local time zone | +| envSecrets.authLdapCredentials.existingSecret | string | `"auth-ldap-secret"` | Name of existing secret containing LDAP credentials | +| envSecrets.authLdapCredentials.ldapBindingPassword | string | `"bind-password"` | Password for bind user secret key | +| envSecrets.authOidcCredentials.existingSecret | string | `"auth-oidc-secret"` | Name of existing secret containing OIDC credentials | +| envSecrets.authOidcCredentials.oidcClientId | string | `"oidc-client-id"` | ID of OIDC client (application) secret key | +| envSecrets.authOidcCredentials.oidcClientSecret | string | `"oidc-client-secret"` | Secret of OIDC client (application) secret key | +| envSecrets.dbCredentials.dbUrlKey | string | `"db-url"` | Secret key for DB_URL Example for external database: `mysql://username:password@host:port/homarrdb` or `postgresql://username:password@host:port/homarrdb` | +| envSecrets.dbCredentials.existingSecret | string | `"db-secret"` | Name of existing secret containing DB credentials | +| envSecrets.dbEncryption.existingSecret | string | `"db-encryption"` | Name of existing secret containing DB encryption | +| envSecrets.dbEncryption.key | string | `"db-encryption-key"` | Secret key for SECRET_ENCRYPTION_KEY can be generated with `openssl rand -hex 32` | +| fullnameOverride | string | `""` | Overrides chart's fullname | +| hostAliases | list | `[]` | Add static entries to /etc/hosts in the Pod. This is useful in the following cases: - You are running in a dual-stack cluster (IPv4 + IPv6) and want to force usage of IPv4 for specific hostnames - Your application is having DNS resolution issues or IPv6 preference issues - You need to override or simulate DNS entries without changing global DNS - You are running in an air-gapped or isolated environment without external DNS Example: hostAliases: - ip: "192.168.1.10" hostnames: - "example.com" - "example.internal" | +| httproute | object | `{"enabled":false,"hostnames":["chart-example.local"],"parentRefs":[{"name":"my-gateway","namespace":"default"}],"rules":[{"backendRefs":[{"name":"homarr","port":8080}],"filters":[],"matches":[{"path":{"type":"PathPrefix","value":"/"}}]}]}` | Gateway API HTTPRoute configuration | +| httproute.enabled | bool | `false` | Enable HTTPRoute | +| httproute.hostnames | list | `["chart-example.local"]` | Hostnames this route matches (similar to ingress.hosts.host) | +| httproute.parentRefs | list | `[{"name":"my-gateway","namespace":"default"}]` | References to the parent Gateway(s) this route attaches to. Each item must include at least a `name`, and optionally a `namespace`. | +| httproute.rules | list | `[{"backendRefs":[{"name":"homarr","port":8080}],"filters":[],"matches":[{"path":{"type":"PathPrefix","value":"/"}}]}]` | List of routing rules. Each rule can include: - matches: path/header/query matching - filters: optional transformations (redirects, header modifications, etc.) - backendRefs: one or more Kubernetes Services to forward traffic to | +| httproute.rules[0].filters | list | `[]` | Optional filters for this rule (default: empty) | +| httproute.rules[0].matches[0].path.type | string | `"PathPrefix"` | Path match type. One of: Exact, PathPrefix, RegularExpression | +| 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.70.0"` | 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 | +| ingress.hosts | list | `[{"host":"chart-example.local","paths":[{"path":"/"}]}]` | Ingress hosts configuration | +| ingress.ingressClassName | string | `""` | Ingress class name | +| ingress.tls | list | `[]` | Ingress TLS configuration | +| livenessProbe.failureThreshold | int | `3` | Failure threshold for liveness probe - number of consecutive failures before pod is restarted | +| livenessProbe.httpGet.path | string | `"/api/health/live"` | This is the liveness check endpoint used by Kubernetes to determine if the application is still running. | +| livenessProbe.httpGet.port | int | `7575` | The port on which the liveness check will be performed. This must be the same as the container port exposed by the application. | +| livenessProbe.initialDelaySeconds | int | `10` | Initial delay in seconds before the liveness probe starts | +| livenessProbe.periodSeconds | int | `10` | Period in seconds between liveness probe checks | +| livenessProbe.timeoutSeconds | int | `1` | Timeout in seconds for each liveness probe check | +| nameOverride | string | `""` | Overrides chart's name | +| nodeSelector | object | `{}` | Node selectors for pod scheduling | +| persistence.homarrDatabase.accessMode | string | `"ReadWriteOnce"` | homarr-database access mode | +| persistence.homarrDatabase.enabled | bool | `false` | Enable homarr-database persistent storage | +| persistence.homarrDatabase.mountPath | string | `"/appdata"` | homarr-database mount path inside the pod | +| persistence.homarrDatabase.name | string | `"homarr-database"` | homarr-database persistent storage name | +| persistence.homarrDatabase.size | string | `"50Mi"` | homarr-database storage size | +| persistence.homarrDatabase.storageClassName | string | `"local-path"` | homarr-database storage class name | +| persistence.homarrDatabase.volumeClaimName | string | `""` | homarr-database optional volumeClaimName to target specific PV | +| persistence.homarrTrustedCerts.certificates | string | `nil` | homarr-trusted-certificates certificates, each entry will become a new trusted certificate as a dedicated file (works only for "configmap" and "secret" mode) | +| persistence.homarrTrustedCerts.enabled | bool | `false` | Enable trusted certificates persistence | +| persistence.homarrTrustedCerts.existingSecretKeys | string | `nil` | List of keys (filenames) to mount from the existing secret (used only when type is "existingSecret") | +| persistence.homarrTrustedCerts.existingSecretName | string | `""` | Name of the existing Kubernetes Secret to mount (required if type is "existingSecret") | +| persistence.homarrTrustedCerts.mountPath | string | `"/appdata/trusted-certificates"` | homarr-trusted-certificates mount path inside the pod | +| persistence.homarrTrustedCerts.type | string | `"configmap"` | Persistence mode can be : configmap (declarative), secret (declarative) or existingSecret (mount an existing Kubernetes Secret by name and specify which keys to mount as files) | +| podAnnotations | object | `{}` | Pod annotations | +| podLabels | object | `{}` | Pod labels | +| podSecurityContext | object | `{}` | Pod security context | +| rbac | object | `{"enabled":false}` | Enable RBAC resources for Kubernetes integration Creates Role, ClusterRole, and associated bindings for Homarr's Kubernetes features | +| rbac.enabled | bool | `false` | Enable to create RBAC resources and activate Kubernetes integration | +| readinessProbe.failureThreshold | int | `3` | Failure threshold for readiness probe - number of consecutive failures before pod is considered unready | +| readinessProbe.httpGet.path | string | `"/api/health/ready"` | This is the readiness check endpoint used by Kubernetes to determine if the application is ready to handle traffic. | +| readinessProbe.httpGet.port | int | `7575` | The port on which the readiness check will be performed. This must match the container's exposed port. | +| readinessProbe.initialDelaySeconds | int | `10` | Initial delay in seconds before the readiness probe starts. increase this value if the pod is slow to fully start. | +| readinessProbe.periodSeconds | int | `10` | Period in seconds between readiness probe checks | +| readinessProbe.timeoutSeconds | int | `1` | Timeout in seconds for each readiness probe check | +| replicaCount | int | `1` | Number of replicas | +| resources | object | `{}` | Resource configuration | +| securityContext | object | `{}` | Security context | +| service.enabled | bool | `true` | Enable service | +| service.ipFamilies | list | `[]` | List of IP families to use for the service. Examples: - ["IPv4"] - ["IPv6"] - ["IPv4", "IPv6"] for dual-stack Leave empty to use cluster default behavior | +| service.ipFamilyPolicy | string | `"SingleStack"` | Defines how the service assigns IP families (IPv4/IPv6) Possible values: - SingleStack (default): Only one IP family, usually IPv4 - PreferDualStack: Use dual-stack if the cluster supports it, fallback to single - RequireDualStack: Fail if dual-stack cannot be assigned | +| service.ports.app.port | int | `7575` | Service port | +| service.ports.app.protocol | string | `"TCP"` | Service protocol | +| service.ports.app.targetPort | string | `"http"` | Service target port | +| service.type | string | `"ClusterIP"` | Service type | +| strategyType | string | `"RollingUpdate"` | `strategyType` specifies the strategy used to replace old Pods by new ones. `strategyType` can be `"Recreate"` or `"RollingUpdate"`. `"RollingUpdate"` is the default value and updates Pods in a rolling update fashion. `"Recreate"` will kill all existing Pods before new ones are created. The `"Recreate"` strategy is necessary when persistent volume's `accessMode` is set to `"ReadWriteOnce"` when using `helm upgrade`, as pod volume attachments to an existing PersistentVolumeClaim need to be cleared before a new pod can attach to it. | +| tolerations | list | `[]` | Node tolerations for pod scheduling | --- + Autogenerated from chart metadata using [helm-docs](https://github.com/norwoodj/helm-docs) diff --git a/apps/docs/docs/getting-started/installation/home-assistant.mdx b/apps/docs/docs/getting-started/installation/home-assistant.mdx index 9f5a50f52..9ba9c5d01 100644 --- a/apps/docs/docs/getting-started/installation/home-assistant.mdx +++ b/apps/docs/docs/getting-started/installation/home-assistant.mdx @@ -14,7 +14,7 @@ Homarr can be seamlessly integrated into your Home Assistant setup with this add ## Installation 1. **Add Repository**: Navigate to your Home Assistant Supervisor panel, and go to the Add-on Store. Add the following repository URL: `https://github.com/Wiggen94/ha-homarr-v1-server` or click this button -[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FWiggen94%2Fha-homarr-v1-server) + [![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FWiggen94%2Fha-homarr-v1-server) 2. **Install the Add-on**: Search for "Homarr Server" in the Add-on Store and select it. Click on "Install" to start the installation process. diff --git a/apps/docs/docs/getting-started/installation/portainer.mdx b/apps/docs/docs/getting-started/installation/portainer.mdx index f816d77fe..0442b215e 100644 --- a/apps/docs/docs/getting-started/installation/portainer.mdx +++ b/apps/docs/docs/getting-started/installation/portainer.mdx @@ -1,5 +1,7 @@ # Portainer + ## Portainer Stacks + ### Prerequisites - [Portainer Stacks](https://www.portainer.io/blog/stacks-docker-compose-the-portainer-way) @@ -23,15 +25,14 @@ services: environment: - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - - '7575:7575' + - "7575:7575" ``` - :::note -Portainer will mount the files to your host machine. Please make sure to replace ```` from the docker run command with your desired storage location. The path must be absolute. +Portainer will mount the files to your host machine. Please make sure to replace `` from the docker run command with your desired storage location. The path must be absolute. ::: -Then, click on ``Deploy the stack`` and wait until the container has started. +Then, click on `Deploy the stack` and wait until the container has started. :::tip @@ -43,5 +44,5 @@ If you're unsure how to create a stack, checkout the [Portainer Documentation](h To update Homarr using Docker Compose or Portainer Stacks, simply pull the latest image and restart the container. -1. Run ``docker pull ghcr.io/homarr-labs/homarr:latest`` to pull the latest image. -2. Re-run ``docker-compose up -d`` or re-deploy the stack in Portainer. +1. Run `docker pull ghcr.io/homarr-labs/homarr:latest` to pull the latest image. +2. Re-run `docker-compose up -d` or re-deploy the stack in Portainer. diff --git a/apps/docs/docs/getting-started/installation/proxmox.mdx b/apps/docs/docs/getting-started/installation/proxmox.mdx index f6f5fb120..bd33b4040 100644 --- a/apps/docs/docs/getting-started/installation/proxmox.mdx +++ b/apps/docs/docs/getting-started/installation/proxmox.mdx @@ -31,7 +31,7 @@ After you've installed Homarr, you can find a new LXC "homarr". # Updating -Updating is as simple as executing +Updating is as simple as executing ```bash update @@ -49,17 +49,19 @@ Some Homarr features require setting environment variables. When installing Homa # Troubleshooting -If something does not work after an update, please first try rebooting the LXC or the homarr Service with +If something does not work after an update, please first try rebooting the LXC or the homarr Service with ```bash systemctl restart homarr ``` # Getting help + - If you are looking for help with the script, updating the LXC or troubleshooting the installer, please get in contact with the support of the community scripts. They provide support on their [Discord](https://discord.gg/2wvnMDgdnU). If you found vulnerabilities, bugs or have a request for the script, [create a new issue here](https://github.com/community-scripts/ProxmoxVE/issues/new/choose). - If you are looking to report a bug, vulnerability or request a new feature, use https://github.com/homarr-labs/homarr . You can ask for help on our Discord. # How to find logs + Homarr runs under a system service called `homarr`, so getting the logs is a simple as using the following command inside the LXC (Container) Shell ```bash diff --git a/apps/docs/docs/getting-started/installation/qnap.mdx b/apps/docs/docs/getting-started/installation/qnap.mdx index a655db5b3..b8c1f977b 100644 --- a/apps/docs/docs/getting-started/installation/qnap.mdx +++ b/apps/docs/docs/getting-started/installation/qnap.mdx @@ -4,6 +4,6 @@ QNAP installation guide has not updated to 1.0 yet. There guide is still for 0.15.10. ::: -When installing on QNAP, we recommend you to install Homarr using [Container Station]( https://www.qnap.com/en/software/container-station) or [this third-party image](https://www.myqnap.org/product/homarr/). +When installing on QNAP, we recommend you to install Homarr using [Container Station](https://www.qnap.com/en/software/container-station) or [this third-party image](https://www.myqnap.org/product/homarr/). There is also a guide available, but note that it is written in Chinese: https://post.smzdm.com/p/awzm7op2/ diff --git a/apps/docs/docs/getting-started/installation/runtipi.mdx b/apps/docs/docs/getting-started/installation/runtipi.mdx index 53a669c90..c2b2823b7 100644 --- a/apps/docs/docs/getting-started/installation/runtipi.mdx +++ b/apps/docs/docs/getting-started/installation/runtipi.mdx @@ -1,4 +1,4 @@ -# Runtipi +# Runtipi Runtipi is a self-hosted orchestrator that makes it easy to manage and run multiple services on a single server. It is based on Docker and comes with a simple web interface to manage your services. Runtipi is designed to be easy to use, so you don't have to worry about manual configuration or networking. @@ -11,6 +11,7 @@ https://runtipi.io # Installation Installing Homarr is pretty untuitive, the app is available in the default appstore : + 1. Search for **"Homarr"** in the App-Store page and select it 2. Click on **"Install"**. 3. Choose the method you want to access Homarr, through any port or domain name then select **"Install"** @@ -18,13 +19,15 @@ Installing Homarr is pretty untuitive, the app is available in the default appst # Maintenance After installation, all you need is available from the WebUI in **"My apps"** > **"Homarr"** : - - Start/Stop - - Update - - Backup - - Logs - + +- Start/Stop +- Update +- Backup +- Logs + If you like to tinker with your apps, you can also edit your app's docker-compose with a [user-config](https://runtipi.io/docs/guides/customize-app-config). # Getting help + - If you are looking for help with anything in Runtipi. They provide support on their [Discord](https://discord.gg/Bu9qEPnHsc) and [forums](https://forums.runtipi.io/). If you found vulnerabilities or bugs, [create a new issue here](https://github.com/runtipi/runtipi-appstore/issues). -- If you are looking to report a bug, vulnerability or request a new feature for Homarr, use https://github.com/homarr-labs/homarr . You can ask for help on our Discord. \ No newline at end of file +- If you are looking to report a bug, vulnerability or request a new feature for Homarr, use https://github.com/homarr-labs/homarr . You can ask for help on our Discord. diff --git a/apps/docs/docs/getting-started/installation/saltbox.mdx b/apps/docs/docs/getting-started/installation/saltbox.mdx index 2f284d72b..88805eafb 100644 --- a/apps/docs/docs/getting-started/installation/saltbox.mdx +++ b/apps/docs/docs/getting-started/installation/saltbox.mdx @@ -5,6 +5,7 @@ Saltbox installation command has not updated to 1.0 yet. There command still run ::: You can also use this to install on Saltbox: + ```bash sb install sandbox-homarr -``` \ No newline at end of file +``` diff --git a/apps/docs/docs/getting-started/installation/source.mdx b/apps/docs/docs/getting-started/installation/source.mdx index 933b264dd..838f0d0a2 100644 --- a/apps/docs/docs/getting-started/installation/source.mdx +++ b/apps/docs/docs/getting-started/installation/source.mdx @@ -28,15 +28,29 @@ This method is only useful, when you want to develop on Homarr or extend it with ## Steps
    -
  1. Clone the Repository using git clone https://github.com/homarr-labs/homarr.git
    2. -
  2. Enter the created directory using cd homarr
    3. -
  3. Install all dependencies using pnpm install
    4. -
  4. 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`
    5. -
  5. Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
    6. +
  6. + Clone the Repository using git clone https://github.com/homarr-labs/homarr.git +
    7. +
  7. + Enter the created directory using cd homarr +
    8. +
  8. + Install all dependencies using pnpm install +
    9. +
  9. + 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` +
    10. +
  10. + Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32` +
  11. Replace `CRON_JOB_API_KEY` with a secure random string by using `openssl rand -base64 32`
  12. Run `pnpm run db:migration:sqlite:run` and wait that it completes
  13. Build the source using `pnpm build`
    14. -
  14. Copy better-sqlite3.node files with `mkdir build` and `cp ./node_modules/better-sqlite3/build/Release/better_sqlite3.node ./build/better_sqlite3.node`
    15. +
  15. + Copy better-sqlite3.node files with `mkdir build` and `cp + ./node_modules/better-sqlite3/build/Release/better_sqlite3.node ./build/better_sqlite3.node` +
  16. Start a redis server using `redis-server`
  17. Run the server using `pnpm start`
  18. Open `http://localhost:3000` in your browser
    19. diff --git a/apps/docs/docs/getting-started/installation/unraid.mdx b/apps/docs/docs/getting-started/installation/unraid.mdx index 5fa7cc9b0..18588c5d4 100644 --- a/apps/docs/docs/getting-started/installation/unraid.mdx +++ b/apps/docs/docs/getting-started/installation/unraid.mdx @@ -1,5 +1,5 @@ -import Link from '@docusaurus/Link'; -import { IconDownload } from '@tabler/icons-react'; +import Link from "@docusaurus/Link"; +import { IconDownload } from "@tabler/icons-react"; # Unraid @@ -14,17 +14,17 @@ You can install Homarr directly from your Unraid Dashboard, no terminal required -
    +
    Install community applications plugin
    -
    -
    +
    +
    :::tip @@ -46,4 +46,3 @@ After you've installed the Community Apps Plugin, you can install Homarr from th After you've installed Homarr, you can find it under the tab "Docker". The official support thread is located [here](https://forums.unraid.net/topic/123478-support-smartphonelover-homarr/), but we prefer to communicate over GitHub and Discord instead. - diff --git a/apps/docs/docs/integrations/adguard-home/index.mdx b/apps/docs/docs/integrations/adguard-home/index.mdx index b4cb6cdb6..52b26f66f 100644 --- a/apps/docs/docs/integrations/adguard-home/index.mdx +++ b/apps/docs/docs/integrations/adguard-home/index.mdx @@ -1,37 +1,44 @@ --- -title: 'AdGuard Home' +title: "AdGuard Home" description: "AdGuard Home is a network-wide software for blocking ads and trackers, providing a safer and faster internet experience." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconAd, IconDeviceGamepad } from "@tabler/icons-react"; -import { adguardHomeIntegration } from '.'; -import { dnsHoleSummaryWidget } from '@site/docs/widgets/dns-hole-summary'; -import { dnsHoleControlsWidget } from '@site/docs/widgets/dns-hole-controls'; +import { adguardHomeIntegration } from "."; +import { dnsHoleSummaryWidget } from "@site/docs/widgets/dns-hole-summary"; +import { dnsHoleControlsWidget } from "@site/docs/widgets/dns-hole-controls"; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/anchor/index.mdx b/apps/docs/docs/integrations/anchor/index.mdx index e4d897767..2e43195cc 100644 --- a/apps/docs/docs/integrations/anchor/index.mdx +++ b/apps/docs/docs/integrations/anchor/index.mdx @@ -1,40 +1,45 @@ --- -title: 'Anchor' +title: "Anchor" description: "Anchor is a self-hosted note-taking application." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { anchorIntegration } from '.'; -import { anchorNoteWidget } from '@site/docs/widgets/anchor-note'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { anchorIntegration } from "."; +import { anchorNoteWidget } from "@site/docs/widgets/anchor-note"; - - + The Anchor integration lets Homarr connect to your Anchor instance so you can display and edit selected notes directly from your dashboard. ### Widgets & Capabilities + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/aria2/index.mdx b/apps/docs/docs/integrations/aria2/index.mdx index 9950fec2f..8ec92a5d0 100644 --- a/apps/docs/docs/integrations/aria2/index.mdx +++ b/apps/docs/docs/integrations/aria2/index.mdx @@ -1,38 +1,43 @@ --- -title: 'Aria2' +title: "Aria2" description: "Lightweight multiprotocol & multi-source command-line download utility. It supports HTTP/HTTPS, FTP, SFTP, BitTorrent and Metalink" hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { aria2Integration } from '.'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { aria2Integration } from "."; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/audiobookshelf/index.mdx b/apps/docs/docs/integrations/audiobookshelf/index.mdx index 156525ba5..a052d2fff 100644 --- a/apps/docs/docs/integrations/audiobookshelf/index.mdx +++ b/apps/docs/docs/integrations/audiobookshelf/index.mdx @@ -1,41 +1,40 @@ --- -title: 'Audiobookshelf' +title: "Audiobookshelf" description: "Audiobookshelf is a self-hosted audiobook and podcast server that lets you manage and stream your audio library." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { audiobookshelfIntegration } from '.'; -import { audioStatsWidget } from '@site/docs/widgets/audio-stats'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { audiobookshelfIntegration } from "."; +import { audioStatsWidget } from "@site/docs/widgets/audio-stats"; - - + Audiobookshelf provides library statistics including audiobook and podcast counts, listening time, and active sessions. ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/bazarr/index.mdx b/apps/docs/docs/integrations/bazarr/index.mdx index f9400a45e..7e1ad2d64 100644 --- a/apps/docs/docs/integrations/bazarr/index.mdx +++ b/apps/docs/docs/integrations/bazarr/index.mdx @@ -1,31 +1,30 @@ --- -title: 'Bazarr' +title: "Bazarr" description: "Bazarr is a companion application to Sonarr and Radarr that manages and downloads subtitles." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { bazarrIntegration } from '.'; -import { bazarrWidget } from '@site/docs/widgets/bazarr'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { bazarrIntegration } from "."; +import { bazarrWidget } from "@site/docs/widgets/bazarr"; - + Bazarr complements Sonarr and Radarr by managing subtitle downloads. The Homarr integration uses your Bazarr API key to fetch missing subtitle counts and health badges. ### Screenshots -import apiKeySettings from './img/api-key-settings.png'; -import widgetOverview from '@site/docs/widgets/bazarr/img/widget-overview.png'; +import apiKeySettings from "./img/api-key-settings.png"; +import widgetOverview from "@site/docs/widgets/bazarr/img/widget-overview.png";
    -

    API key location in Bazarr (Settings → General → Security):

    +

    + API key location in Bazarr (Settings → General → Security): +

    bazarr-api-key-settings
    @@ -35,20 +34,25 @@ import widgetOverview from '@site/docs/widgets/bazarr/img/widget-overview.png';
    ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets + You can find your Bazarr API key under **Settings → General → Security**. - + diff --git a/apps/docs/docs/integrations/beszel/index.mdx b/apps/docs/docs/integrations/beszel/index.mdx index 0c93cdc9f..8ddda77c6 100644 --- a/apps/docs/docs/integrations/beszel/index.mdx +++ b/apps/docs/docs/integrations/beszel/index.mdx @@ -1,25 +1,22 @@ --- -title: 'Beszel' +title: "Beszel" description: "Beszel is a lightweight server monitoring platform with Docker stats, historical data, and alert functions." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { beszelIntegration } from '.'; -import { beszelSystemStatsWidget } from '@site/docs/widgets/beszel-system-stats'; -import { beszelSystemGridWidget } from '@site/docs/widgets/beszel-system-grid'; -import { beszelSystemTableWidget } from '@site/docs/widgets/beszel-system-table'; -import { beszelAlertsWidget } from '@site/docs/widgets/beszel-alerts'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { beszelIntegration } from "."; +import { beszelSystemStatsWidget } from "@site/docs/widgets/beszel-system-stats"; +import { beszelSystemGridWidget } from "@site/docs/widgets/beszel-system-grid"; +import { beszelSystemTableWidget } from "@site/docs/widgets/beszel-system-table"; +import { beszelAlertsWidget } from "@site/docs/widgets/beszel-alerts"; -import beszelDashboard from './img/beszel-dashboard.png'; +import beszelDashboard from "./img/beszel-dashboard.png"; - + Beszel monitors your servers in real time via lightweight agents, collecting CPU, memory, disk, network, GPU, temperature, and Docker container metrics. It stores historical data and supports configurable alerts. @@ -28,26 +25,33 @@ Beszel monitors your servers in real time via lightweight agents, collecting CPU Beszel dashboard overview showing all four widgets ### Widgets & Capabilities + ### Adding the integration + ### Secrets - + + :::tip Beszel uses PocketBase under the hood. The default admin credentials are set during the initial Beszel setup. diff --git a/apps/docs/docs/integrations/coolify/index.mdx b/apps/docs/docs/integrations/coolify/index.mdx index 56e5e6c29..7b828cc18 100644 --- a/apps/docs/docs/integrations/coolify/index.mdx +++ b/apps/docs/docs/integrations/coolify/index.mdx @@ -1,29 +1,24 @@ --- -title: 'Coolify' -description: 'Self-hosted PaaS and deployment platform' +title: "Coolify" +description: "Self-hosted PaaS and deployment platform" hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { coolifyIntegration } from '.'; -import { coolifyWidget } from '../../widgets/coolify'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { coolifyIntegration } from "."; +import { coolifyWidget } from "../../widgets/coolify"; - + ### Widgets & Capabilities - + + ### Adding the integration + :::info URL configuration @@ -31,16 +26,28 @@ Use the root URL of your Coolify instance, for example `https://coolify.example. ::: ### Secrets -Enable API access under Settings > Advanced if it is disabled.), - (Go to Security > API Tokens.), - 'Enter a name, e.g. "Homarr".', - (Select the read permission. The Coolify widget only reads version, server, project, application, and service data.), - 'Click "Create".', - 'Copy the generated token immediately. Coolify only shows it once.', - 'Paste the token into the API Key field in Homarr.' - ] -}]} /> + + + Enable API access under Settings > Advanced if it is disabled. + , + + Go to Security > API Tokens. + , + 'Enter a name, e.g. "Homarr".', + + Select the read permission. The Coolify widget only reads version, server, project, application, + and service data. + , + 'Click "Create".', + "Copy the generated token immediately. Coolify only shows it once.", + "Paste the token into the API Key field in Homarr.", + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/dash-dot/index.mdx b/apps/docs/docs/integrations/dash-dot/index.mdx index 512bc6c8d..9c400321c 100644 --- a/apps/docs/docs/integrations/dash-dot/index.mdx +++ b/apps/docs/docs/integrations/dash-dot/index.mdx @@ -1,32 +1,33 @@ --- -title: 'Dash.' +title: "Dash." description: "Dash. is a system performance and resource monitoring tool" hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconHeartRateMonitor } from "@tabler/icons-react"; -import { dashDotIntegration } from '.'; -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; +import { dashDotIntegration } from "."; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; - - + ### Widgets & Capabilities + ### Adding the integration - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/deluge/index.mdx b/apps/docs/docs/integrations/deluge/index.mdx index 24aadb910..89f906c0c 100644 --- a/apps/docs/docs/integrations/deluge/index.mdx +++ b/apps/docs/docs/integrations/deluge/index.mdx @@ -1,36 +1,41 @@ --- -title: 'Deluge' +title: "Deluge" description: "Deluge is a lightweight, Free Software, cross-platform BitTorrent client." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconDownload } from "@tabler/icons-react"; -import Alert from '@theme/Admonition'; -import { delugeIntegration } from '.'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import Alert from "@theme/Admonition"; +import { delugeIntegration } from "."; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/docker/index.mdx b/apps/docs/docs/integrations/docker/index.mdx index e48c46e9b..568bf8be4 100644 --- a/apps/docs/docs/integrations/docker/index.mdx +++ b/apps/docs/docs/integrations/docker/index.mdx @@ -1,32 +1,31 @@ --- -title: 'Docker' +title: "Docker" description: "Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconBrandDocker, IconTool } from "@tabler/icons-react"; -import { dockerIntegration } from '.'; -import { dockerContainersWidget } from '@site/docs/widgets/docker-containers'; +import { dockerIntegration } from "."; +import { dockerContainersWidget } from "@site/docs/widgets/docker-containers"; - - + ### Widgets & Capabilities + - ## Enabling the Docker integration + This integration must first be enabled. If you directly run on the host system and you have docker installed, it will be enabled by default. Otherwise, you'll need to mount the [docker socket](https://docs.docker.com/engine/security/protect-access/) to the Homarr container, @@ -49,15 +48,17 @@ services: environment: - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32` ports: - - '7575:7575' + - "7575:7575" ``` With docker run, add this parameter: `-v /var/run/docker.sock:/var/run/docker.sock`. In Windows, you'll need to adjust the slashes: `-v //var/run/docker.sock:/var/run/docker.sock` ### Managing your Docker containers within Homarr + Homarr allows you to interact with Docker containers running on your system. Each container row has an action menu with the following options: + - **View logs** - opens a dedicated logs page with a live terminal - **Start** - start a stopped container - **Stop** - stop a running container @@ -98,11 +99,13 @@ Currently Homarr supports one label for configuration of the containers: - **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget and tools page. ### Security + Mounting docker sockets can be risky, as they permit full control over your docker service. As an example, a thread actor could abuse Homarr use the socket to start, stop or delete containers on your system. Therefore we recommend the usage of a socket proxy, which can prohibit certain actions. A few examples include: + - https://github.com/linuxserver/docker-socket-proxy - https://github.com/Tecnativa/docker-socket-proxy @@ -110,36 +113,44 @@ See documentation of the respective proxies on how to configure them. Homarr may behave in unexpected ways when you use proxies. #### Permissions + Homarr needs the following permissions from the Docker API: + - Containers/Start - Containers/Stop - Containers/Restart - Containers/Remove For socket proxies, you will need these permissions: + - `CONTAINERS=1` - `POST=1` **Caution:** `POST` access is security critical as it provides extensive capabilities to modify your docker environment. Please leave it disabled if you're concerned about this. As a workaround, you can use [LSIO's socket proxy](https://github.com/linuxserver/docker-socket-proxy) and set the following: + - ALLOW_START=1 - ALLOW_STOP=1 - ALLOW_RESTARTS=1 -These will work even with `POST=0`. +These will work even with `POST=0`. You lose the ability to remove containers, but start, stop and restarts should work just fine. #### Connecting to Docker via Socket Proxies + To connect to Docker via a socket proxy, you'll need to add these two environment variables in the compose file: + - `DOCKER_HOSTNAMES=` - `DOCKER_PORTS=` Refer: https://homarr.dev/docs/advanced/environment-variables/ You will also need to add Homarr to the network of your socket proxy. You can do it like this: + 1. Add the network to your compose file (with appropriate changes): + ```yaml networks: socket-proxy: @@ -148,6 +159,7 @@ networks: ``` 2. Add the network to the homarr service in the compose file: + ```yaml networks: - socket-proxy diff --git a/apps/docs/docs/integrations/emby/index.mdx b/apps/docs/docs/integrations/emby/index.mdx index 907d2bd96..2426a1561 100644 --- a/apps/docs/docs/integrations/emby/index.mdx +++ b/apps/docs/docs/integrations/emby/index.mdx @@ -1,37 +1,35 @@ --- -title: 'Emby' +title: "Emby" description: "Emby is a media server platform that allows you to organize, manage, and stream your personal media collection." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconVideo, IconTicket } from "@tabler/icons-react"; -import { embyIntegration } from '.'; -import { mediaServerWidget } from '@site/docs/widgets/media-server'; -import { mediaReleasesWidget } from '@site/docs/widgets/media-releases'; +import { embyIntegration } from "."; +import { mediaServerWidget } from "@site/docs/widgets/media-server"; +import { mediaReleasesWidget } from "@site/docs/widgets/media-releases"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/glances/index.mdx b/apps/docs/docs/integrations/glances/index.mdx index 2639f87e5..bd047e81d 100644 --- a/apps/docs/docs/integrations/glances/index.mdx +++ b/apps/docs/docs/integrations/glances/index.mdx @@ -1,37 +1,43 @@ --- -title: 'Glances' +title: "Glances" description: "Glances is a cross-platform system monitoring tool." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { glancesIntegration } from '.'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { glancesIntegration } from "."; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/gluetun/index.mdx b/apps/docs/docs/integrations/gluetun/index.mdx index 7c936fc1f..dca490781 100644 --- a/apps/docs/docs/integrations/gluetun/index.mdx +++ b/apps/docs/docs/integrations/gluetun/index.mdx @@ -1,20 +1,17 @@ --- -title: 'Gluetun' -description: 'Connect Gluetun to Homarr as a VPN integration.' +title: "Gluetun" +description: "Connect Gluetun to Homarr as a VPN integration." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { gluetunIntegration } from '.'; -import { vpnWidget } from '@site/docs/widgets/vpn'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { gluetunIntegration } from "."; +import { vpnWidget } from "@site/docs/widgets/vpn"; - + [Gluetun](https://github.com/qdm12/gluetun) exposes a control server that Homarr can query to report the VPN tunnel status, DNS status, public IP address, and active provider details in the VPN widget. @@ -22,9 +19,11 @@ status, DNS status, public IP address, and active provider details in the VPN wi ### Widgets & Capabilities ### Setting up the Gluetun control server @@ -40,13 +39,20 @@ Refer to the [Gluetun control server documentation](https://github.com/qdm12/glu Gluetun's control server can be left unprotected or secured with either an API key or HTTP Basic authentication. Choose the option that matches how your Gluetun instance integration is set up. - + diff --git a/apps/docs/docs/integrations/gotify/index.mdx b/apps/docs/docs/integrations/gotify/index.mdx index 09c81265b..43cde77b0 100644 --- a/apps/docs/docs/integrations/gotify/index.mdx +++ b/apps/docs/docs/integrations/gotify/index.mdx @@ -1,33 +1,39 @@ --- -title: 'Gotify' +title: "Gotify" description: "Gotify is a simple, self-hosted server for sending and receiving messages in real time." hide_title: true --- -import { notificationsWidget } from '@site/docs/widgets/notifications'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { gotifyIntegration } from '.'; +import { notificationsWidget } from "@site/docs/widgets/notifications"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { gotifyIntegration } from "."; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/home-assistant/index.mdx b/apps/docs/docs/integrations/home-assistant/index.mdx index 98ad591d6..65d09d166 100644 --- a/apps/docs/docs/integrations/home-assistant/index.mdx +++ b/apps/docs/docs/integrations/home-assistant/index.mdx @@ -1,45 +1,51 @@ --- -title: 'Home Assistant' +title: "Home Assistant" description: "Home Assistant is an open-source home automation platform that focuses on privacy and local control, allowing you to automate and control your smart home devices." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconBinaryTree } from "@tabler/icons-react"; -import { homeAssistantIntegration } from '.'; -import { smartHomeEntityStateWidget } from '@site/docs/widgets/smart-home-entity-state'; -import { smartHomeExecuteAutomationWidget } from '@site/docs/widgets/smart-home-execute-automation'; +import { homeAssistantIntegration } from "."; +import { smartHomeEntityStateWidget } from "@site/docs/widgets/smart-home-entity-state"; +import { smartHomeExecuteAutomationWidget } from "@site/docs/widgets/smart-home-execute-automation"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/ical/index.mdx b/apps/docs/docs/integrations/ical/index.mdx index 5f5ffc422..475229a34 100644 --- a/apps/docs/docs/integrations/ical/index.mdx +++ b/apps/docs/docs/integrations/ical/index.mdx @@ -1,38 +1,44 @@ --- -title: 'iCal' +title: "iCal" description: "iCal is a standard for calendar data exchange, allowing users to share and manage calendar events across different platforms." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconZoomQuestion, IconChartBar, IconSearch } from "@tabler/icons-react"; -import { icalIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; +import { icalIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - + + ## Using the iCal integration -The iCal integration allows you to add external calendars to Homarr. Any calendar that provides a public iCal URL can be integrated, such as Google Calendar, Apple Calendar, or Outlook. \ No newline at end of file +The iCal integration allows you to add external calendars to Homarr. Any calendar that provides a public iCal URL can be integrated, such as Google Calendar, Apple Calendar, or Outlook. diff --git a/apps/docs/docs/integrations/immich/index.mdx b/apps/docs/docs/integrations/immich/index.mdx index ed88466ce..952921bfb 100644 --- a/apps/docs/docs/integrations/immich/index.mdx +++ b/apps/docs/docs/integrations/immich/index.mdx @@ -1,36 +1,29 @@ --- -title: 'Immich' +title: "Immich" description: "Self-hosted photo and video management solution" hide_title: true --- -import { immichAlbumCarouselWidget } from '../../widgets/immich-album-carousel';import { - IntegrationHeader -} from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { immichIntegration } from '.'; -import { immichServerStatsWidget } from '../../widgets/immich-server-stats'; +import { immichAlbumCarouselWidget } from "../../widgets/immich-album-carousel"; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { immichIntegration } from "."; +import { immichServerStatsWidget } from "../../widgets/immich-server-stats"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets + server.about.
    Additional permissions may be required depending on your Immich version. If you encounter authorization errors, grant any missing permissions requested by the server. + ), - 'Create the integration in Homarr and copy the API key to there' - ] +'Create the integration in Homarr and copy the API key to there' +] }]} /> diff --git a/apps/docs/docs/integrations/jellyfin/index.mdx b/apps/docs/docs/integrations/jellyfin/index.mdx index 4826386b8..83e23fd45 100644 --- a/apps/docs/docs/integrations/jellyfin/index.mdx +++ b/apps/docs/docs/integrations/jellyfin/index.mdx @@ -1,40 +1,39 @@ --- -title: 'Jellyfin' +title: "Jellyfin" description: "Jellyfin is a free and open-source media server software that allows you to organize, manage, and share your media files." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconVideo, IconTicket } from "@tabler/icons-react"; -import { jellyfinIntegration } from '.'; -import { mediaServerWidget } from '@site/docs/widgets/media-server'; -import { mediaReleasesWidget } from '@site/docs/widgets/media-releases'; +import { jellyfinIntegration } from "."; +import { mediaServerWidget } from "@site/docs/widgets/media-server"; +import { mediaReleasesWidget } from "@site/docs/widgets/media-releases"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/jellyseerr/index.mdx b/apps/docs/docs/integrations/jellyseerr/index.mdx index a85d7bd9f..e752906bb 100644 --- a/apps/docs/docs/integrations/jellyseerr/index.mdx +++ b/apps/docs/docs/integrations/jellyseerr/index.mdx @@ -1,45 +1,52 @@ --- -title: 'Jellyseerr' +title: "Jellyseerr" description: "Jellyseerr is a self-hosted media request management system that integrates with Jellyfin and other media servers." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconZoomQuestion, IconChartBar, IconSearch } from "@tabler/icons-react"; -import { jellyseerrIntegration } from '.'; -import { mediaRequestListWidget } from '@site/docs/widgets/media-request-list'; -import { mediaRequestStatsWidget } from '@site/docs/widgets/media-request-stats'; +import { jellyseerrIntegration } from "."; +import { mediaRequestListWidget } from "@site/docs/widgets/media-request-list"; +import { mediaRequestStatsWidget } from "@site/docs/widgets/media-request-stats"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/kubernetes/index.mdx b/apps/docs/docs/integrations/kubernetes/index.mdx index 899c60931..662874467 100644 --- a/apps/docs/docs/integrations/kubernetes/index.mdx +++ b/apps/docs/docs/integrations/kubernetes/index.mdx @@ -1,20 +1,16 @@ --- -title: 'Kubernetes' +title: "Kubernetes" description: "Kubernetes is a powerful container orchestration platform that automates the deployment, scaling, and management of containerized applications." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconBrandDocker, IconTool } from "@tabler/icons-react"; -import { kubernetesIntegration } from '.'; +import { kubernetesIntegration } from "."; - - + Homarr provides a user-friendly Kubernetes dashboard that offers an overview of your cluster’s resources in a clear and structured interface. It allows users to view key Kubernetes objects, including `Pods`, `Services`, `Ingresses`, `Nodes`, `ConfigMaps`, `Secrets`, `Namespaces`, and `Volumes`, as well as basic metrics when the Kubernetes Metrics Server is enabled. @@ -47,7 +43,7 @@ Enabling RBAC in the Helm chart creates the necessary Kubernetes Role-Based Acce - Service Account: A dedicated service account for Homarr. - Role & RoleBinding: Grants permissions within a specific namespace to list, watch, and get pods, services, secrets, configmaps, and more. - ClusterRole & ClusterRoleBinding: Extends the same permissions cluster-wide for additional flexibility. -::: + ::: ### Homarr Dashboard Overview diff --git a/apps/docs/docs/integrations/lidarr/index.mdx b/apps/docs/docs/integrations/lidarr/index.mdx index 498503617..ad5916a3f 100644 --- a/apps/docs/docs/integrations/lidarr/index.mdx +++ b/apps/docs/docs/integrations/lidarr/index.mdx @@ -1,35 +1,40 @@ --- -title: 'Lidarr' +title: "Lidarr" description: "Lidarr is a music management tool that automates the process of downloading, sorting, and renaming music." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconCalendar } from "@tabler/icons-react"; -import { lidarrIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; +import { lidarrIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/navidrome/index.mdx b/apps/docs/docs/integrations/navidrome/index.mdx index 664e6fc58..93c5b076b 100644 --- a/apps/docs/docs/integrations/navidrome/index.mdx +++ b/apps/docs/docs/integrations/navidrome/index.mdx @@ -1,39 +1,38 @@ --- -title: 'Navidrome' +title: "Navidrome" description: "Navidrome is a self-hosted music server and streamer compatible with the Subsonic API." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { navidromeIntegration } from '.'; -import { audioStatsWidget } from '@site/docs/widgets/audio-stats'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { navidromeIntegration } from "."; +import { audioStatsWidget } from "@site/docs/widgets/audio-stats"; - - + Navidrome provides music library statistics including artist, album, and song counts, as well as now playing information via the Subsonic API. ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/nextcloud/index.mdx b/apps/docs/docs/integrations/nextcloud/index.mdx index ba5ab8ee9..f7d7e05fa 100644 --- a/apps/docs/docs/integrations/nextcloud/index.mdx +++ b/apps/docs/docs/integrations/nextcloud/index.mdx @@ -1,40 +1,43 @@ --- -title: 'Nextcloud' +title: "Nextcloud" description: "Nextcloud is a self-hosted productivity platform that provides file storage, collaboration tools, and more." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconCalendar } from "@tabler/icons-react"; -import Alert from '@theme/Admonition'; -import { nextcloudIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; -import { notificationsWidget } from '@site/docs/widgets/notifications'; +import Alert from "@theme/Admonition"; +import { nextcloudIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; +import { notificationsWidget } from "@site/docs/widgets/notifications"; - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - - Users who use 2FA will have to use Nextcloud's App Password tool to grant Homarr access, as 2FA breaks the traditional process. For more information, see [Nextcloud's Documentation](https://docs.nextcloud.com/server/stable/admin_manual/configuration_user/authentication.html#app-passwords) - , -}]} /> + + + Users who use 2FA will have to use Nextcloud's App Password tool to grant Homarr access, as 2FA breaks the + traditional process. For more information, see [Nextcloud's + Documentation](https://docs.nextcloud.com/server/stable/admin_manual/configuration_user/authentication.html#app-passwords) + + ), + }, + ]} +/> diff --git a/apps/docs/docs/integrations/ntfy/index.mdx b/apps/docs/docs/integrations/ntfy/index.mdx index 4b21d16a4..a132de923 100644 --- a/apps/docs/docs/integrations/ntfy/index.mdx +++ b/apps/docs/docs/integrations/ntfy/index.mdx @@ -1,37 +1,44 @@ --- -title: 'Ntfy' +title: "Ntfy" description: "Ntfy is a simple, open-source notification service that allows you to send and receive notifications across devices." hide_title: true --- -import { notificationsWidget } from '@site/docs/widgets/notifications'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; +import { notificationsWidget } from "@site/docs/widgets/notifications"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; import { IconMessage } from "@tabler/icons-react"; -import { ntfyIntegration } from '.'; +import { ntfyIntegration } from "."; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/nzbget/index.mdx b/apps/docs/docs/integrations/nzbget/index.mdx index 3479f317a..1b7c23a1f 100644 --- a/apps/docs/docs/integrations/nzbget/index.mdx +++ b/apps/docs/docs/integrations/nzbget/index.mdx @@ -1,36 +1,41 @@ --- -title: 'NZBGet' +title: "NZBGet" description: "NZBGet is a lightweight and efficient Usenet downloader." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconDownload } from "@tabler/icons-react"; -import { nzbgetIntegration } from '.'; -import Alert from '@theme/Admonition'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { nzbgetIntegration } from "."; +import Alert from "@theme/Admonition"; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/open-media-vault/index.mdx b/apps/docs/docs/integrations/open-media-vault/index.mdx index ac0a42290..b934bf797 100644 --- a/apps/docs/docs/integrations/open-media-vault/index.mdx +++ b/apps/docs/docs/integrations/open-media-vault/index.mdx @@ -1,42 +1,52 @@ --- -title: 'Open Media Vault' +title: "Open Media Vault" description: "Open Media Vault is a free network-attached storage server based on the Debian operating system." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconHeartRateMonitor } from "@tabler/icons-react"; -import { openMediaVaultIntegration } from '.'; -import Alert from '@theme/Admonition' -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; +import { openMediaVaultIntegration } from "."; +import Alert from "@theme/Admonition"; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - - The user used here must have administrative permissions or Homarr won't be able to read the system performance and resource data. - -}]} /> \ No newline at end of file + + + The user used here must have administrative permissions or Homarr won't be able to read the system performance + and resource data. + + ), + }, + ]} +/> diff --git a/apps/docs/docs/integrations/opnsense/index.mdx b/apps/docs/docs/integrations/opnsense/index.mdx index 37e9a78c6..9a3a2b1ee 100644 --- a/apps/docs/docs/integrations/opnsense/index.mdx +++ b/apps/docs/docs/integrations/opnsense/index.mdx @@ -1,65 +1,75 @@ --- -title: 'OPNsense' +title: "OPNsense" description: "OPNsense is an open-source, easy-to-use, and easy-to-build firewall and routing platform." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconHeartRateMonitor } from "@tabler/icons-react"; -import { opnsenseIntegration } from '.'; -import Alert from '@theme/Admonition' -import { firewallWidget } from '../../widgets/firewall'; +import { opnsenseIntegration } from "."; +import Alert from "@theme/Admonition"; +import { firewallWidget } from "../../widgets/firewall"; - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - - This integration does not require full API access to the firewall. The following guide outlines the process for creating a restricted OPNsense user with a scrambled password, designed exclusively for API access. This ensures minimal permissions and prevents local login capability. - , - steps: [ + + + This integration does not require full API access to the firewall. The following guide outlines the process + for creating a restricted OPNsense user with a scrambled password, designed exclusively for API access. This + ensures minimal permissions and prevents local login capability. + + ), + steps: [ "Log in to the OPNsense web interface as an administrator", "Navigate to System → Access → Users", "Click the + (Add) button to create a new user", <> - Fill in the user details: -
      -
    • Username: Enter a unique name
      • -
    • Password: Leave empty
      • -
    • Scrambled Password: Enable this option
      • -
    • Full name: (Optional) Add a descriptive name
      • -
    + Fill in the user details: +
      +
    • Username: Enter a unique name
      • +
    • Password: Leave empty
      • +
    • Scrambled Password: Enable this option
      • +
    • Full name: (Optional) Add a descriptive name
      • +
    , <> - In Privileges section → Select the option below: -
      -
    • Lobby: Dashboard
      • -
    • Reporting: Traffic
      • -
    + In Privileges section → Select the option below: +
      +
    • Lobby: Dashboard
      • +
    • Reporting: Traffic
      • +
    , "Click Save", "Return to the Users list", "Find the user and click the ticket icon in the Commands column", "Click Yes in the popup to confirm", "A txt file will download automatically, containing: Key and Secret", - "Save this file securely—this information will only be shown once" - ], -}]} /> \ No newline at end of file + "Save this file securely—this information will only be shown once", + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/overseerr/index.mdx b/apps/docs/docs/integrations/overseerr/index.mdx index ce9e0a3e5..2dd2d7c8a 100644 --- a/apps/docs/docs/integrations/overseerr/index.mdx +++ b/apps/docs/docs/integrations/overseerr/index.mdx @@ -1,45 +1,52 @@ --- -title: 'Overseerr' +title: "Overseerr" description: "Overseerr is a self-hosted media request management system that integrates with Plex." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconZoomQuestion, IconChartBar, IconSearch } from "@tabler/icons-react"; -import { overseerrIntegration } from '.'; -import { mediaRequestListWidget } from '@site/docs/widgets/media-request-list'; -import { mediaRequestStatsWidget } from '@site/docs/widgets/media-request-stats'; +import { overseerrIntegration } from "."; +import { mediaRequestListWidget } from "@site/docs/widgets/media-request-list"; +import { mediaRequestStatsWidget } from "@site/docs/widgets/media-request-stats"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/paperless-ngx/index.mdx b/apps/docs/docs/integrations/paperless-ngx/index.mdx index e08840110..175fdb15a 100644 --- a/apps/docs/docs/integrations/paperless-ngx/index.mdx +++ b/apps/docs/docs/integrations/paperless-ngx/index.mdx @@ -1,41 +1,40 @@ --- -title: 'Paperless-ngx' +title: "Paperless-ngx" description: "Paperless-ngx is a document management system that transforms your physical documents into a searchable online archive." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { paperlessNgxIntegration } from '.'; -import { paperlessNgxWidget } from '@site/docs/widgets/paperless-ngx'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { paperlessNgxIntegration } from "."; +import { paperlessNgxWidget } from "@site/docs/widgets/paperless-ngx"; - - + Paperless-ngx provides document statistics including total documents, inbox count, correspondents, tags, and document types. ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/patchmon/index.mdx b/apps/docs/docs/integrations/patchmon/index.mdx index 95b827df0..b60c20962 100644 --- a/apps/docs/docs/integrations/patchmon/index.mdx +++ b/apps/docs/docs/integrations/patchmon/index.mdx @@ -1,43 +1,42 @@ --- -title: 'PatchMon' +title: "PatchMon" description: "PatchMon is a patch management and monitoring solution for Linux hosts." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { patchmonIntegration } from '.'; -import { patchmonWidget } from '@site/docs/widgets/patchmon'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { patchmonIntegration } from "."; +import { patchmonWidget } from "@site/docs/widgets/patchmon"; - - + PatchMon provides host and package update statistics including total hosts, hosts needing updates, and security update counts. The PatchMon widget requires users to be **signed in to Homarr**; see the [PatchMon widget documentation](/docs/widgets/patchmon#authentication) for details on authentication and public boards. ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/peanut/index.mdx b/apps/docs/docs/integrations/peanut/index.mdx index 751200bed..7eb7b845b 100644 --- a/apps/docs/docs/integrations/peanut/index.mdx +++ b/apps/docs/docs/integrations/peanut/index.mdx @@ -1,48 +1,53 @@ --- -title: 'PeaNUT' -description: 'A tiny dashboard for Network UPS Tools (NUT) servers.' +title: "PeaNUT" +description: "A tiny dashboard for Network UPS Tools (NUT) servers." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { peaNutIntegration } from '.'; -import { upsWidget } from '@site/docs/widgets/ups'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { peaNutIntegration } from "."; +import { upsWidget } from "@site/docs/widgets/ups"; - + [PeaNUT](https://github.com/Brandawg93/PeaNUT) exposes the data of your [Network UPS Tools](https://networkupstools.org/) servers over a REST API, which Homarr reads to display the status of your UPS devices. ### Widgets & Capabilities + ### Adding the integration + ### Secrets + PeaNUT secures its API with HTTP Basic authentication when the `WEB_USERNAME` and `WEB_PASSWORD` environment variables are set on the PeaNUT instance. Provide the same credentials here. If the instance runs with `AUTH_DISABLED=true`, no secrets are required. - + diff --git a/apps/docs/docs/integrations/pi-hole/index.mdx b/apps/docs/docs/integrations/pi-hole/index.mdx index ca2b400e7..d724b026d 100644 --- a/apps/docs/docs/integrations/pi-hole/index.mdx +++ b/apps/docs/docs/integrations/pi-hole/index.mdx @@ -1,47 +1,54 @@ --- -title: 'Pi-hole' +title: "Pi-hole" description: "Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking unwanted content and improving your browsing experience." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconAd, IconDeviceGamepad } from "@tabler/icons-react"; -import Alert from '@theme/Admonition'; -import { dnsHoleSummaryWidget } from '@site/docs/widgets/dns-hole-summary'; -import { dnsHoleControlsWidget } from '@site/docs/widgets/dns-hole-controls'; -import { piHoleIntegration } from '.'; +import Alert from "@theme/Admonition"; +import { dnsHoleSummaryWidget } from "@site/docs/widgets/dns-hole-summary"; +import { dnsHoleControlsWidget } from "@site/docs/widgets/dns-hole-controls"; +import { piHoleIntegration } from "."; + - - - - Homarr supports both Pi-hole v5 and v6. It automatically detects the version and uses the correct API. + + Homarr supports both Pi-hole v5 and v6. It automatically detects the version and uses the correct API. ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/plex/index.mdx b/apps/docs/docs/integrations/plex/index.mdx index b6394b918..b6e35a6e3 100644 --- a/apps/docs/docs/integrations/plex/index.mdx +++ b/apps/docs/docs/integrations/plex/index.mdx @@ -1,41 +1,47 @@ --- -title: 'Plex' +title: "Plex" description: "Plex is a media server platform that allows you to organize, manage, and stream your personal media collection." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconVideo, IconTicket } from "@tabler/icons-react"; -import { plexIntegration } from '.'; -import { mediaServerWidget } from '@site/docs/widgets/media-server'; -import { mediaReleasesWidget } from '@site/docs/widgets/media-releases'; +import { plexIntegration } from "."; +import { mediaServerWidget } from "@site/docs/widgets/media-server"; +import { mediaReleasesWidget } from "@site/docs/widgets/media-releases"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - - Follow the official Plex documentation to find your authentication token. - - ] -}]} /> \ No newline at end of file + Follow the official{" "} + + Plex documentation + {" "} + to find your authentication token. + , + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/prowlarr/index.mdx b/apps/docs/docs/integrations/prowlarr/index.mdx index 0c5561f91..b3624a97e 100644 --- a/apps/docs/docs/integrations/prowlarr/index.mdx +++ b/apps/docs/docs/integrations/prowlarr/index.mdx @@ -1,32 +1,34 @@ --- -title: 'Prowlarr' +title: "Prowlarr" description: "Prowlarr is an indexer manager for Usenet and BitTorrent, providing a unified interface to manage your indexers." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconHeartRateMonitor } from "@tabler/icons-react"; -import { prowlarrIntegration } from '.'; -import { indexerManagerWidget } from '@site/docs/widgets/indexer-manager'; +import { prowlarrIntegration } from "."; +import { indexerManagerWidget } from "@site/docs/widgets/indexer-manager"; - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/proxmox/index.mdx b/apps/docs/docs/integrations/proxmox/index.mdx index 4ea8eda98..f038dd007 100644 --- a/apps/docs/docs/integrations/proxmox/index.mdx +++ b/apps/docs/docs/integrations/proxmox/index.mdx @@ -1,103 +1,107 @@ --- -title: 'Proxmox' +title: "Proxmox" description: "Proxmox is a powerful open-source virtualization platform that allows you to run virtual machines and containers." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconHeartRateMonitor } from "@tabler/icons-react"; -import { proxmoxIntegration } from '.'; -import Alert from '@theme/Admonition' -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; +import { proxmoxIntegration } from "."; +import Alert from "@theme/Admonition"; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - - The Proxmox API may not work with Linux PAM standard authentication. It is strongly recommended to use the Proxmox VE authentication server realm when creating your API user. - , - credentials: ['username', 'tokenId', 'realm', 'apiKey'], - steps: [ + + + The Proxmox API may not work with Linux PAM standard authentication. It is strongly recommended to use the + Proxmox VE authentication server realm when creating your API user. + + ), + credentials: ["username", "tokenId", "realm", "apiKey"], + steps: [ "Navigate to the Proxmox portal, click on Datacenter", "Expand Permissions, click on Groups", "Click the Create button", "Name the group something informative, like api-users", "Click on the Permissions 'folder'", <> - Click Add {"->"} Group Permission -
      -
    • Path: /
      • -
    • Group: group from Step 4 above
      • -
    • Role: PVEAuditor
      • -
    • Propagate: Checked
      • -
    + Click Add {"->"} Group Permission +
      +
    • Path: /
      • +
    • Group: group from Step 4 above
      • +
    • Role: PVEAuditor
      • +
    • Propagate: Checked
      • +
    , "Expand Permissions, click on Users", <> - Click the Add button -
      -
    • User name: something informative like api
      • -
    • Realm: Proxmox VE authentication server
      • -
    • Password: create a secure password for the user
      • -
    • Confirm Password: re-enter the password
      • -
    • Group: group from Step 4 above
      • -
    + Click the Add button +
      +
    • User name: something informative like api
      • +
    • Realm: Proxmox VE authentication server
      • +
    • Password: create a secure password for the user
      • +
    • Confirm Password: re-enter the password
      • +
    • Group: group from Step 4 above
      • +
    , "Expand Permissions, click on API Tokens", <> - Click the Add button -
      -
    • User: user from Step 8 above
      • -
    • Token ID: something informative like the application or purpose like homarr
      • -
    • Privilege Separation: unchecked
      • -
    + Click the Add button +
      +
    • User: user from Step 8 above
      • +
    • Token ID: something informative like the application or purpose like homarr
      • +
    • Privilege Separation: unchecked
      • +
    , "Copy the Secret that is shown in Step 10 because it is only shown once", "Go back to the 'Permissions' menu", <> - Click Add {"->"} API Token Permission -
      -
    • Path: /
      • -
    • API Token: select the API token created in Step 10
      • -
    • Role: PVE Auditor
      • -
    • Propagate: Checked
      • -
    + Click Add {"->"} API Token Permission +
      +
    • Path: /
      • +
    • API Token: select the API token created in Step 10
      • +
    • Role: PVE Auditor
      • +
    • Propagate: Checked
      • +
    , - ], - body: <> - - Sometimes you'll also find the api@pve!homarr format, - within Homarr you'll have to split it up into: - -
      + ], + body: ( + <> + + Sometimes you'll also find the api@pve!homarr format, within Homarr you'll have to split it up + into: + +
      • - Username: api + Username: api
      • - Realm: pve + Realm: pve
      • - Token ID: homarr + Token ID: homarr
        • -
      - -}]} /> \ No newline at end of file +
    + + ), + }, + ]} +/> diff --git a/apps/docs/docs/integrations/q-bittorent/index.mdx b/apps/docs/docs/integrations/q-bittorent/index.mdx index ae85fc0ea..0bf2474ec 100644 --- a/apps/docs/docs/integrations/q-bittorent/index.mdx +++ b/apps/docs/docs/integrations/q-bittorent/index.mdx @@ -1,37 +1,39 @@ --- -title: 'qBittorrent' +title: "qBittorrent" description: "qBittorrent is a free and open-source BitTorrent client." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconDownload } from "@tabler/icons-react"; -import { qBittorentIntegration } from '.'; -import Alert from '@theme/Admonition'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { qBittorentIntegration } from "."; +import Alert from "@theme/Admonition"; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/radarr/index.mdx b/apps/docs/docs/integrations/radarr/index.mdx index 286e1b0b7..09548cab7 100644 --- a/apps/docs/docs/integrations/radarr/index.mdx +++ b/apps/docs/docs/integrations/radarr/index.mdx @@ -1,33 +1,34 @@ --- -title: 'Radarr' +title: "Radarr" description: "Radarr is a movie management tool that automates the process of downloading, sorting, and renaming movies." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconCalendar } from "@tabler/icons-react"; -import { radarrIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; +import { radarrIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/readarr/index.mdx b/apps/docs/docs/integrations/readarr/index.mdx index a2c153a91..aec31fe1a 100644 --- a/apps/docs/docs/integrations/readarr/index.mdx +++ b/apps/docs/docs/integrations/readarr/index.mdx @@ -1,33 +1,34 @@ --- -title: 'Readarr' +title: "Readarr" description: "Readarr is a book management tool that automates the process of downloading, sorting, and renaming books." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconCalendar } from "@tabler/icons-react"; -import { readarrIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; +import { readarrIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/sabnzbd/index.mdx b/apps/docs/docs/integrations/sabnzbd/index.mdx index 5de72d8c3..8c91c6fef 100644 --- a/apps/docs/docs/integrations/sabnzbd/index.mdx +++ b/apps/docs/docs/integrations/sabnzbd/index.mdx @@ -1,34 +1,35 @@ --- -title: 'SABnzbd' +title: "SABnzbd" description: "SABnzbd is an Open Source Binary Newsreader." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconDownload } from "@tabler/icons-react"; -import { sabnzbdIntegration } from '.'; -import Alert from '@theme/Admonition'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { sabnzbdIntegration } from "."; +import Alert from "@theme/Admonition"; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/seerr/index.mdx b/apps/docs/docs/integrations/seerr/index.mdx index 81b7e0fb1..a1e30798e 100644 --- a/apps/docs/docs/integrations/seerr/index.mdx +++ b/apps/docs/docs/integrations/seerr/index.mdx @@ -1,45 +1,52 @@ --- -title: 'Seerr' +title: "Seerr" description: "Seerr is a self-hosted media request management system that integrates with various media servers." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconZoomQuestion, IconChartBar, IconSearch } from "@tabler/icons-react"; -import { seerrIntegration } from '.'; -import { mediaRequestListWidget } from '@site/docs/widgets/media-request-list'; -import { mediaRequestStatsWidget } from '@site/docs/widgets/media-request-stats'; +import { seerrIntegration } from "."; +import { mediaRequestListWidget } from "@site/docs/widgets/media-request-list"; +import { mediaRequestStatsWidget } from "@site/docs/widgets/media-request-stats"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/slskd/index.mdx b/apps/docs/docs/integrations/slskd/index.mdx index 70674cb04..705ab43c0 100644 --- a/apps/docs/docs/integrations/slskd/index.mdx +++ b/apps/docs/docs/integrations/slskd/index.mdx @@ -1,34 +1,39 @@ --- -title: 'Slskd' +title: "Slskd" description: "A modern client-server application for the Soulseek file sharing network." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { slskdIntegration } from '.'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { slskdIntegration } from "."; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/sonarr/index.mdx b/apps/docs/docs/integrations/sonarr/index.mdx index 7dc3c7a64..c65d3ce3d 100644 --- a/apps/docs/docs/integrations/sonarr/index.mdx +++ b/apps/docs/docs/integrations/sonarr/index.mdx @@ -1,33 +1,34 @@ --- -title: 'Sonarr' +title: "Sonarr" description: "Sonarr is a TV series management tool that automates the process of downloading, sorting, and renaming episodes." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconCalendar } from "@tabler/icons-react"; -import { sonarrIntegration } from '.'; -import { calendarWidget } from '@site/docs/widgets/calendar'; +import { sonarrIntegration } from "."; +import { calendarWidget } from "@site/docs/widgets/calendar"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/speedtest-tracker/index.mdx b/apps/docs/docs/integrations/speedtest-tracker/index.mdx index 2041dad5c..146a09eca 100644 --- a/apps/docs/docs/integrations/speedtest-tracker/index.mdx +++ b/apps/docs/docs/integrations/speedtest-tracker/index.mdx @@ -1,34 +1,39 @@ --- -title: 'Speedtest Tracker' -description: 'Speedtest Tracker is a self-hosted internet performance tracking application.' +title: "Speedtest Tracker" +description: "Speedtest Tracker is a self-hosted internet performance tracking application." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { speedtestTrackerIntegration } from '.'; -import { speedtestTrackerWidget } from '@site/docs/widgets/speedtest-tracker'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { speedtestTrackerIntegration } from "."; +import { speedtestTrackerWidget } from "@site/docs/widgets/speedtest-tracker"; - - + ### Widgets & Capabilities + ### Adding the integration + ### Secrets - + + diff --git a/apps/docs/docs/integrations/synology/index.mdx b/apps/docs/docs/integrations/synology/index.mdx index 4d836513e..c3f50fc3f 100644 --- a/apps/docs/docs/integrations/synology/index.mdx +++ b/apps/docs/docs/integrations/synology/index.mdx @@ -19,11 +19,7 @@ import Alert from "@theme/Admonition"; ### Widgets & Capabilities ### Supported metrics diff --git a/apps/docs/docs/integrations/tdarr/index.mdx b/apps/docs/docs/integrations/tdarr/index.mdx index 89a0730d2..47956343d 100644 --- a/apps/docs/docs/integrations/tdarr/index.mdx +++ b/apps/docs/docs/integrations/tdarr/index.mdx @@ -1,36 +1,38 @@ --- -title: 'Tdarr' +title: "Tdarr" description: "Tdarr is a distributed media transcoding system that allows you to process and optimize your media files across multiple nodes." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconTransform } from "@tabler/icons-react"; -import { tdarrIntegration } from '.'; -import { mediaTranscodingWidget } from '@site/docs/widgets/media-transcoding'; +import { tdarrIntegration } from "."; +import { mediaTranscodingWidget } from "@site/docs/widgets/media-transcoding"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/technitium-dns/index.mdx b/apps/docs/docs/integrations/technitium-dns/index.mdx index 3ca8bda7c..3bf39d820 100644 --- a/apps/docs/docs/integrations/technitium-dns/index.mdx +++ b/apps/docs/docs/integrations/technitium-dns/index.mdx @@ -1,62 +1,72 @@ --- -title: 'Technitium DNS' +title: "Technitium DNS" description: "Technitium DNS Server is a self-hosted DNS server with ad-blocking and network-wide filtering capabilities." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import Alert from '@theme/Admonition'; -import { technitiumDnsIntegration } from '.'; -import { dnsHoleSummaryWidget } from '@site/docs/widgets/dns-hole-summary'; -import { dnsHoleControlsWidget } from '@site/docs/widgets/dns-hole-controls'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import Alert from "@theme/Admonition"; +import { technitiumDnsIntegration } from "."; +import { dnsHoleSummaryWidget } from "@site/docs/widgets/dns-hole-summary"; +import { dnsHoleControlsWidget } from "@site/docs/widgets/dns-hole-controls"; - + - - Homarr supports Technitium DNS v11 and above. The correct API version is detected automatically - no manual configuration is required. + + Homarr supports Technitium DNS v11 and above. The correct API version is detected automatically - no manual + configuration is required. ### Widgets & Capabilities + ### Adding the integration + ### Secrets - - The **API token** option is recommended. API tokens are non-expiring and do not require storing your admin password in Homarr. - Username and password authentication uses a session token that expires after inactivity, triggering a silent re-login on the next request. + + The **API token** option is recommended. API tokens are non-expiring and do not require storing your admin password in + Homarr. Username and password authentication uses a session token that expires after inactivity, triggering a silent + re-login on the next request. - - The **DNS Hole Controls** widget (enabling, disabling, and timed disabling of blocking) requires the token to have settings-level permissions. - The **DNS Hole Summary** widget (stats only) works with any valid token. - If Homarr cannot read the blocking status due to insufficient permissions, the status indicator will be hidden but statistics will still be shown. + + The **DNS Hole Controls** widget (enabling, disabling, and timed disabling of blocking) requires the token to have + settings-level permissions. The **DNS Hole Summary** widget (stats only) works with any valid token. If Homarr cannot + read the blocking status due to insufficient permissions, the status indicator will be hidden but statistics will + still be shown. - + 'Click on your username in the top-right corner and select "Create API Token".', + 'Give the token a name (e.g. "Homarr") and click "Create Token".', + "Copy the generated token and paste it into the API Key field in Homarr.", + ], + }, + { + credentials: ["username", "password"], + steps: [], + body: "Enter your Technitium DNS admin credentials. Homarr will exchange them for a session token and transparently re-authenticate when the session expires.", + }, + ]} +/> diff --git a/apps/docs/docs/integrations/tracearr/index.mdx b/apps/docs/docs/integrations/tracearr/index.mdx index dc4dde8e0..03954a1cc 100644 --- a/apps/docs/docs/integrations/tracearr/index.mdx +++ b/apps/docs/docs/integrations/tracearr/index.mdx @@ -1,38 +1,37 @@ --- -title: 'Tracearr' +title: "Tracearr" description: "Tracearr is a comprehensive media monitoring solution that tracks streams, user activity, and policy violations in your media server (including Plex, Jellyfin, Emby)." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; -import { tracearrIntegration } from '.'; -import { tracearrWidget } from '@site/docs/widgets/tracearr'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { tracearrIntegration } from "."; +import { tracearrWidget } from "@site/docs/widgets/tracearr"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - - In Tracearr, go to Settings → API and generate or copy your API key. - - ] -}]} /> + In Tracearr, go to Settings → API and generate or copy your API key. + , + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/transmission/index.mdx b/apps/docs/docs/integrations/transmission/index.mdx index da0c0209e..c17dbe862 100644 --- a/apps/docs/docs/integrations/transmission/index.mdx +++ b/apps/docs/docs/integrations/transmission/index.mdx @@ -1,34 +1,35 @@ --- -title: 'Transmission' +title: "Transmission" description: "A Fast, Easy and Free Bittorrent Client." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconDownload } from "@tabler/icons-react"; -import { transmissionIntegration } from '.'; -import Alert from '@theme/Admonition'; -import { downloadsWidget } from '@site/docs/widgets/downloads'; +import { transmissionIntegration } from "."; +import Alert from "@theme/Admonition"; +import { downloadsWidget } from "@site/docs/widgets/downloads"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/truenas/index.mdx b/apps/docs/docs/integrations/truenas/index.mdx index 5d29a7019..3ec09bbcf 100644 --- a/apps/docs/docs/integrations/truenas/index.mdx +++ b/apps/docs/docs/integrations/truenas/index.mdx @@ -1,61 +1,67 @@ --- -title: 'TrueNAS' +title: "TrueNAS" description: "Enterprise network-attached storage for your home, office, and cloud." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { truenasIntegration } from '.'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; -import Alert from '@theme/Admonition'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { truenasIntegration } from "."; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; +import Alert from "@theme/Admonition"; - - + ### Widgets & Capabilities - + + ### Adding the integration + - TrueNAS only serves its API over HTTPS, so enter the https:// URL of your TrueNAS web interface. If it uses a self-signed certificate (the default), add it under Management > Tools > Certificates so Homarr can establish the connection. + TrueNAS only serves its API over HTTPS, so enter the https:// URL of your TrueNAS web interface. If it + uses a self-signed certificate (the default), add it under{" "} + Management > Tools > Certificates so Homarr can establish the + connection. ### Secrets - - API key authentication is the recommended method. It works across current TrueNAS versions and does not depend on user group membership. - , - steps: [ - "In the TrueNAS web interface, click your user avatar in the top-right corner and select \"API Keys\".", - "Click \"Add\", give the key a name such as \"Homarr\", and confirm.", - "Copy the generated key immediately - TrueNAS only shows it once - and paste it as the API Key when creating the integration in Homarr.", - ], + credentials: ["apiKey"], + header: ( + + API key authentication is the recommended method. It works across current TrueNAS versions and does not depend + on user group membership. + + ), + steps: [ + 'In the TrueNAS web interface, click your user avatar in the top-right corner and select "API Keys".', + 'Click "Add", give the key a name such as "Homarr", and confirm.', + "Copy the generated key immediately - TrueNAS only shows it once - and paste it as the API Key when creating the integration in Homarr.", + ], }, { - credentials: ['username', 'password'], - steps: [ - "In the TrueNAS web interface, go to \"Credentials\" > \"Users\" > \"Add\" and create a user with a secure password.", - "Grant the user administrative access so Homarr can read system, pool, and reporting data.", - "Save the user and create the integration in Homarr with these credentials.", - ], - body: - The account must have administrative API access. The auxiliary_administrator group was removed in TrueNAS 25.10; on that version or newer, use API key authentication instead, or assign the user a full-admin role. - , + credentials: ["username", "password"], + steps: [ + 'In the TrueNAS web interface, go to "Credentials" > "Users" > "Add" and create a user with a secure password.', + "Grant the user administrative access so Homarr can read system, pool, and reporting data.", + "Save the user and create the integration in Homarr with these credentials.", + ], + body: ( + + The account must have administrative API access. The auxiliary_administrator group was removed in + TrueNAS 25.10; on that version or newer, use API key authentication instead, or assign the user a full-admin + role. + + ), }, -]} /> + ]} +/> diff --git a/apps/docs/docs/integrations/umami/index.mdx b/apps/docs/docs/integrations/umami/index.mdx index 8aeb3c194..6aa5ddced 100644 --- a/apps/docs/docs/integrations/umami/index.mdx +++ b/apps/docs/docs/integrations/umami/index.mdx @@ -1,53 +1,52 @@ --- -title: 'Umami' -description: 'Privacy-focused, open-source web analytics' +title: "Umami" +description: "Privacy-focused, open-source web analytics" hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { umamiIntegration } from '.'; -import { umamiWidget } from '../../widgets/umami'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { umamiIntegration } from "."; +import { umamiWidget } from "../../widgets/umami"; - + ### Widgets & Capabilities - + + ### Adding the integration + :::tip URL configuration + - **Umami Cloud:** Use `https://api.umami.is/v1` - **Self-hosted:** Use `http://your-umami-host:3000/api` -::: + ::: ### Secrets - + + diff --git a/apps/docs/docs/integrations/unifi-controller/index.mdx b/apps/docs/docs/integrations/unifi-controller/index.mdx index 134ce91b8..f25cecaac 100644 --- a/apps/docs/docs/integrations/unifi-controller/index.mdx +++ b/apps/docs/docs/integrations/unifi-controller/index.mdx @@ -1,40 +1,40 @@ --- -title: 'Unifi Controller' +title: "Unifi Controller" description: "Unifi Controller is a network management platform for Unifi devices." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import {IntegrationSecrets} from '@site/src/components/integrations/secrets'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; import { IconTopologyFull } from "@tabler/icons-react"; -import { unifiControllerIntegration } from '.'; -import { networkControllerSummaryWidget } from '@site/docs/widgets/network-controller-summary'; -import { networkControllerStatusWidget } from '@site/docs/widgets/network-controller-status'; +import { unifiControllerIntegration } from "."; +import { networkControllerSummaryWidget } from "@site/docs/widgets/network-controller-summary"; +import { networkControllerStatusWidget } from "@site/docs/widgets/network-controller-status"; - - + 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. ### Widgets & Capabilities + ### Adding the integration + ### Secrets - \ No newline at end of file + + diff --git a/apps/docs/docs/integrations/unraid/index.mdx b/apps/docs/docs/integrations/unraid/index.mdx index bd1546a78..a629fe844 100644 --- a/apps/docs/docs/integrations/unraid/index.mdx +++ b/apps/docs/docs/integrations/unraid/index.mdx @@ -1,59 +1,71 @@ --- -title: 'Unraid' +title: "Unraid" description: "Versatile operating system that lets you run applications, virtual machines, and storage devices on your server" hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { unraidIntegration } from '.'; -import { systemResourcesWidget } from '@site/docs/widgets/system-resources'; -import { healthMonitoringWidget } from '@site/docs/widgets/health-monitoring'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { unraidIntegration } from "."; +import { systemResourcesWidget } from "@site/docs/widgets/system-resources"; +import { healthMonitoringWidget } from "@site/docs/widgets/health-monitoring"; import imgManagement from "./imgs/unraid-management.png"; import imgCreateApiKey from "./imgs/unraid-create-api-key.png"; import imgCopyApiKey from "./imgs/copy-api-key.png"; import imgSelectApikeyPreset from "./imgs/unraid-select-api-key-preset.png"; - - + ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets -Are you using Unraid pre-7.2? If yes, please first follow the steps here to install the Unraid API., - <> - Open the settings and open the management access
    - Unraid management - , - <> - Click on the "API Keys" tab at the top and click on the "create API key" button. Choose "Create new"
    - Unraid management - , - <> - Enter a suitable name for your API key (e.g. Homarr), select the "Viewer" preset and submit the modal.
    - Unraid management - , - <> - Last, copy the API key after your API key has been created
    - Unraid management - - ], -}]} /> \ No newline at end of file + + + Are you using Unraid pre-7.2? If yes, please first{" "} + + follow the steps here to install the Unraid API + + . + , + <> + Open the settings and open the management access +
    + Unraid management + , + <> + + Click on the "API Keys" tab at the top and click on the "create API key" button. Choose "Create new" + +
    + Unraid management + , + <> + + Enter a suitable name for your API key (e.g. Homarr), select the "Viewer" preset and submit the modal. + +
    + Unraid management + , + <> + Last, copy the API key after your API key has been created +
    + Unraid management + , + ], + }, + ]} +/> diff --git a/apps/docs/docs/integrations/uptime-kuma/index.mdx b/apps/docs/docs/integrations/uptime-kuma/index.mdx index 63e6df82b..14834969f 100644 --- a/apps/docs/docs/integrations/uptime-kuma/index.mdx +++ b/apps/docs/docs/integrations/uptime-kuma/index.mdx @@ -1,43 +1,42 @@ --- -title: 'Uptime Kuma' +title: "Uptime Kuma" description: "Uptime Kuma is a self-hosted monitoring tool that tracks the availability of your services and websites." hide_title: true --- -import { IntegrationHeader } from '@site/src/components/integrations/header'; -import { IntegrationCapabilites } from '@site/src/components/integrations/widgets'; -import { AddingIntegration } from '@site/src/components/integrations/adding'; -import { IntegrationSecrets } from '@site/src/components/integrations/secrets'; -import { uptimeKumaIntegration } from '.'; -import { uptimeKumaWidget } from '@site/docs/widgets/uptime-kuma'; +import { IntegrationHeader } from "@site/src/components/integrations/header"; +import { IntegrationCapabilites } from "@site/src/components/integrations/widgets"; +import { AddingIntegration } from "@site/src/components/integrations/adding"; +import { IntegrationSecrets } from "@site/src/components/integrations/secrets"; +import { uptimeKumaIntegration } from "."; +import { uptimeKumaWidget } from "@site/docs/widgets/uptime-kuma"; - - + Uptime Kuma monitors the availability of your services and provides uptime statistics through its status page API. ### Widgets & Capabilities - + + ### Adding the integration + ### Secrets - + ], + }, + ]} +/> :::tip If you don't specify a slug, Homarr will use `default` as the status page slug. diff --git a/apps/docs/docs/management/api/index.mdx b/apps/docs/docs/management/api/index.mdx index 2c5bd42e2..e35c14244 100644 --- a/apps/docs/docs/management/api/index.mdx +++ b/apps/docs/docs/management/api/index.mdx @@ -83,3 +83,16 @@ The OpenAPI and MCP APIs include board management endpoints for common automatio - Configure global board defaults such as public home boards and status behavior Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags. + +## Get Custom Widget authoring resources + +Custom JSX v2 provides four HTTP discovery endpoints: + +- `GET /api/custom-widgets/authoring-prompt` returns the current prompt plus MCP and HTTP resource identifiers. +- `GET /api/custom-widgets/schema` returns the canonical widget JSON Schema. +- `GET /api/custom-widgets/components` returns the release-matched static component catalog. +- `GET /api/custom-widgets/skill` returns the concise live `SKILL.md` plus skills.sh, source, and install metadata. Retrieve the schema, component catalog, and examples through their dedicated resources only when needed. + +Call `customWidget_secretRequestUser` to create a temporary credential entry URL. Do not construct or save this URL. + +Authenticated tRPC and MCP procedures support definition management, validation, previews, template patches, and credential writes. An exported definition does not contain credentials. diff --git a/apps/docs/docs/management/apps/index.mdx b/apps/docs/docs/management/apps/index.mdx index c5c0a2ad7..955a8a3fc 100644 --- a/apps/docs/docs/management/apps/index.mdx +++ b/apps/docs/docs/management/apps/index.mdx @@ -7,8 +7,8 @@ tags: - Ping --- -Apps are the building blocks of your Homarr board. -Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up. +Apps are the building blocks of your Homarr board. +Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up. Apps are used in the bookmark and app widget. ## Create an app @@ -27,7 +27,7 @@ The name must be at least one character long and can be chosen freely. ### Icon URL -This is the URL to the icon that will be displayed on the app widget. +This is the URL to the icon that will be displayed on the app widget. It can be a url to an image in the internet, one from the included icon repositories or a local file uploaded through the upload button. ![Icon URL](./img/app-icon-url.png) @@ -42,7 +42,7 @@ The URL to the website you want to link to. Clicking on the app widget or bookma ### Ping URL -When you want to use another url for the simple status check you can set it here. +When you want to use another url for the simple status check you can set it here. This will allow you to set a different URL for the ping than the URL that is opened when clicking on the app widget. It's useful when you want to ping the service internally for example with a custom ip but open the website externally. @@ -50,4 +50,4 @@ It's useful when you want to ping the service internally for example with a cust On the apps management page you find all apps that exist in your Homarr instance. You can edit and delete them. -![Apps list](./img/app-list.png) \ No newline at end of file +![Apps list](./img/app-list.png) diff --git a/apps/docs/docs/management/backup.mdx b/apps/docs/docs/management/backup.mdx index 558afb82e..1c86837a9 100644 --- a/apps/docs/docs/management/backup.mdx +++ b/apps/docs/docs/management/backup.mdx @@ -24,12 +24,12 @@ Navigate to `Management` → `Tools` → `Backup`. You must have **admin** permi Click the **Export** button in the export card. You'll be prompted to type `I understand` to confirm. Once confirmed, a ZIP file downloads containing: -| File | Description | -| -------------------- | ------------------------------------------------------------------- | -| `db.sqlite` | Full SQLite database with all entities | -| `metadata.json` | Backup metadata: Homarr version, creation timestamp, encryption key | +| File | Description | +| --------------- | ------------------------------------------------------------------- | +| `db.sqlite` | Full SQLite database with all entities | +| `metadata.json` | Backup metadata: Homarr version, creation timestamp, encryption key | -The backup includes everything: apps, integrations, secrets, boards, users, groups, permissions, search engines, custom widgets, and server settings. (It just backs-up the whole database) +The backup contains the complete database. It includes Custom Widgets and all other Homarr configuration. ## Restoring a Backup diff --git a/apps/docs/docs/management/boards/index.mdx b/apps/docs/docs/management/boards/index.mdx index f1eb3c572..1240c7a76 100644 --- a/apps/docs/docs/management/boards/index.mdx +++ b/apps/docs/docs/management/boards/index.mdx @@ -9,11 +9,11 @@ tags: - Layout --- -import iconColorImage from './img/icon-color.png' -import itemRadiusImage from './img/item-radius.png' -import layoutLargeImage from './img/layout-large.png' -import layoutMediumImage from './img/layout-medium.png' -import layoutSmallImage from './img/layout-small.png' +import iconColorImage from "./img/icon-color.png"; +import itemRadiusImage from "./img/item-radius.png"; +import layoutLargeImage from "./img/layout-large.png"; +import layoutMediumImage from "./img/layout-medium.png"; +import layoutSmallImage from "./img/layout-small.png"; Each dashboard is called a "board". You can create as many boards as you want. @@ -24,24 +24,29 @@ Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) Names of boards must be unique because this will be used in the URL to load the desired board. ## Create a new board + When creating a board, the availability of the board name will be checked for you. ![](./img/create-board-modal.png) ### Name + The name must not include any special characters and must be at least one character long. Underscores and hyphen-minus are allowed. ### Column count + Homarr has a complex drag and drop system that can be used from the browser. The column count defines how many horizontal columns are available to drag and drop elements to. ### Public + This will enable public access for everyone - regardless of whether they are logged in or not. This can be really useful if you want to have public boards in your company or for family and fiends. Modifications for public boards must be allowed explicitly using user groups and their permissions. ## Board settings + You navigate to the board settings by clicking on these three dots: ![](./img/navigate-to-settings.png) @@ -51,7 +56,9 @@ Alternatively, you can also navigate from the board page itself using the cog ic ![](./img/navigate-to-settings-2.png) ### General + #### Page title + This is the title that will be visible at the top left in the navigation bar: ![](./img/page-title.png) @@ -59,6 +66,7 @@ This is the title that will be visible at the top left in the navigation bar: This field is optional and Homarr will fall back to "Homarr" if nothing is set. #### Meta title + This is the secondary title of the page that is not directly visible in the page itself. Browser will use it to set the title of tabs: @@ -67,10 +75,12 @@ Browser will use it to set the title of tabs: Homarr will fall back to the board name and a suffix if nothing is set. #### Logo image URL + This is the URL that is used for the image at the top left. Homarr will fall back to the Homarr logo if nothing is set. #### Favicon image URL + This is the URL that is used for the favicon in the tab title. Homarr will fall back to the Homarr logo if nothing is set. @@ -94,51 +104,65 @@ Amount of columns for this layout. Defines how many items can be placed in a row #### Breakpoint -Minimum width of the screen where the layout will be used. +Minimum width of the screen where the layout will be used. Once the minmum of the next layout is reached the layout will change. #### Preview - - - + + + ### Background + #### Background image URL + Homarr can display a background image behind apps and widgets. This URL can be used to define what image should be shown. #### Background image attachment + This defines whether the background should move when the user scrolls. #### Background image size + This defines whether the background should cover the entire page (and possibly be cropped) or never be cropped but may not cover the entire page. #### Background image repeat + This defines whether the background should be repeated if it cannot cover the entire page. This option can be useful if you have patterns that can be repeated easily (e.g. patterns): ![](./img/background-repeat.png) ### Appearance + #### Primary color + Color that can be chosen freely to give accents to active elements. + #### Secondary color + Color that can be chosen freely to give accents. + #### Opacity + Opacity of the colors. + #### Icon color + Change the color of your bookmark / app icons. - + #### Item radius + Change the radius of your items / categories. - - + ### Custom CSS + This is the field where you can enter custom CSS. The styling will only be applied on the respective board page. @@ -147,14 +171,16 @@ The styling will only be applied on the respective board page. ### Behaviour #### Disable app status + This will disable the status check for apps. ### Access control + With the access control, you can permit a single user or a group to your board. The users and groups can have one of these three levels of access: | **Permission Level** | View board | Edit mode | Settings | Danger zone (eg. delete) | -|----------------------|------------|-----------|----------|--------------------------| +| -------------------- | ---------- | --------- | -------- | ------------------------ | | View board | X | | | | | Modify board | X | X | X | | | Full access | X | X | X | X | @@ -173,18 +199,23 @@ After editing permissions, the save button below the table must be pressed. Otherwise, all changes will be discarded. ### Danger zone + #### Rename + Renaming a board will break all existing links to it permanently with no redirect. #### Board visibility + By default, boards will be private. This means only authenticated users that are authorized have access. Making a board public will expose it to everyone - including unauthenticated users. #### Delete + This will permanently delete the board. This action is irreversible and cannot be undone. ## Delete boards + The deletion of boards is permanent and cannot be undone. There are two ways to delete a board: @@ -196,7 +227,7 @@ Both actions will execute the same deletion process. ## Duplicate boards :::note -Duplicating a board will not copy the users and groups that have access to the board +Duplicating a board will not copy the users and groups that have access to the board nor the integrations the user does not have access to. ::: @@ -206,47 +237,51 @@ You can duplicate a board by clicking on the three dots in the list of boards an ![](./img/duplicate-board-modal.png) ## Setting boards as your home board + The home board is the dashboard, that will be shown at the root path of Homarr or if no board name was passed in the URL. All the following paths will lead to the home board: -- ``my-homarr.com`` -- ``my-homarr.com/boards`` + +- `my-homarr.com` +- `my-homarr.com/boards` Your home board will have a special small badge at the top right in the list of boards: ![](./img/home-board-flag.png) ### For yourself + To set the home board yourself, the easiest option is to set it directly in the list of boards: ![](./img/set-as-home-board-menu.png) Alternatively, you can also define it via your user profile: + 1. Click on your user profile at the top right -2. Click on ``Your preferences`` -3. Change the home board in the ``home board`` dropdown and click on ``Save``. +2. Click on `Your preferences` +3. Change the home board in the `home board` dropdown and click on `Save`. ### For other users -1. Navigate to the users: ``Management`` > ``Users`` > ``Manage`` +1. Navigate to the users: `Management` > `Users` > `Manage` 2. Click on the username of the user that you want to adjust -3. Select the desired home board via the dropdown and click on ``Save`` \ -![](./img/set-home-board-other-user.png) +3. Select the desired home board via the dropdown and click on `Save` \ + ![](./img/set-home-board-other-user.png) ### For user groups -1. Navigate to the user groups: ``Management`` > ``Users`` > ``Groups`` > ``Manage`` -2. Go to tab ``Settings`` -3. Select the desired home board via the dropdown and click on ``Save`` \ -![](./img/set-home-board-user-group.png) +1. Navigate to the user groups: `Management` > `Users` > `Groups` > `Manage` +2. Go to tab `Settings` +3. Select the desired home board via the dropdown and click on `Save` \ + ![](./img/set-home-board-user-group.png) ### For whole server You can also set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. -1. Navigate to the settings: ``Management`` > ``Settings`` > ``Boards`` -2. Select the desired home board via the dropdown and click on ``Save`` \ -![](./img/set-home-board-global.png) +1. Navigate to the settings: `Management` > `Settings` > `Boards` +2. Select the desired home board via the dropdown and click on `Save` \ + ![](./img/set-home-board-global.png) :::note For the global home board you can only select boards that are public. @@ -255,4 +290,4 @@ For the global home board you can only select boards that are public. ### Mobile home board Same as the home board, you can also set a mobile home board. -It will be used for devices that are detected as mobile devices. (Using User-Agent header) \ No newline at end of file +It will be used for devices that are detected as mobile devices. (Using User-Agent header) diff --git a/apps/docs/docs/management/certificates/index.mdx b/apps/docs/docs/management/certificates/index.mdx index cceaa54fd..aa843bfe0 100644 --- a/apps/docs/docs/management/certificates/index.mdx +++ b/apps/docs/docs/management/certificates/index.mdx @@ -7,27 +7,29 @@ tags: --- # Certificates -On this page you can manage your trusted certificates. + +On this page you can manage your trusted certificates. For example if you use a self signed certificate for one of the integrations you want to connect, you can add it here. -Below you can see a screenshot of the certificates page. -The items show the subject, filename and when it expires. +Below you can see a screenshot of the certificates page. +The items show the subject, filename and when it expires. The color of the icon indicates how long it is valid. ![](./img/screenshot.png) -| Color | Meaning | -| --- | --- | -| 🟩 Green | Valid for more than 30 days | +| Color | Meaning | +| --------- | --------------------------- | +| 🟩 Green | Valid for more than 30 days | | 🟨 Yellow | Valid for less than 30 days | -| 🟧 Orange | Valid for less than a week | -| 🟥 Red | Valid for less than a day | - +| 🟧 Orange | Valid for less than a week | +| 🟥 Red | Valid for less than a day | ## Opening the certificates page -Navigate to ``Management`` > ``Tools`` > ``Certificates``. + +Navigate to `Management` > `Tools` > `Certificates`. ## Add a certificate + To add a certificate click on the "Add certificate" button. ![](./img/add-button.png) @@ -62,4 +64,4 @@ Below you can find instructions for some of the integrations. Since version 6 of Pi-hole, the web interface can be accessed through HTTPS. The certificate can be found in the path `/etc/pihole/tls_ca.crt`. To add the certificate, this file needs to be copied and uploaded to Homarr. -You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/). \ No newline at end of file +You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/). diff --git a/apps/docs/docs/management/custom-widgets/_category_.json b/apps/docs/docs/management/custom-widgets/_category_.json new file mode 100644 index 000000000..23e215294 --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Custom Widgets", + "collapsed": true, + "position": 8, + "link": { + "type": "doc", + "id": "management/custom-widgets/index" + } +} diff --git a/apps/docs/docs/management/custom-widgets/agent-authoring.mdx b/apps/docs/docs/management/custom-widgets/agent-authoring.mdx new file mode 100644 index 000000000..23e3cf8b0 --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/agent-authoring.mdx @@ -0,0 +1,86 @@ +# Use agents and skills.sh + +An external agent creates one widget at a time with the Homarr MCP server. The agent harness manages the list for multiple widgets. + +Homarr does not create widget packs or drafts for multiple widgets. + + + View the Custom Widget Skill on skills.sh + + +Install the Agent Skill from the verified Homarr repository: + +```sh +npx skills add https://github.com/homarr-labs/homarr --skill homarr-custom-widget +``` + +The portable skill gives concise authoring guidance. The Homarr MCP prompt gives connected agents a retrieval workflow: read the live schema, then fetch only the component documentation needed for the widget. + +The workbench's **Copy AI prompt** action is separate. It creates a self-contained prompt below 12,000 characters for an ordinary ChatGPT or Claude conversation. It includes the lean contract, bindings, recommended components, and two polished examples. It never tells an offline model to call MCP tools. + +The source is in [`.agents/skills/homarr-custom-widget`](https://github.com/homarr-labs/homarr/tree/HEAD/.agents/skills/homarr-custom-widget). `HEAD` follows the repository default branch, so the link is not tied to an unreleased feature branch. Homarr does not provide a ZIP archive. + +After publication, run the installation command once. This action registers installation activity. + +Then, verify the skills.sh page. Request official maker attribution for `homarr-labs` from skills.sh. + +Repository code cannot give this attribution. + +## Get MCP resources + +- Prompt: `homarr-custom-widget-author` +- Resources: `homarr://custom-widgets/schema`, `components`, `components/{name}`, `examples/{name}`, and `skill` +- HTTP: `GET /api/custom-widgets/authoring-prompt`, `schema`, `components`, and `skill` + +The authoring-prompt tool description contains one sentence. The prompt contains the workflow instructions and resource links. + +`GET /api/custom-widgets/skill` and the MCP tool return the concise skill discovery payload: + +```ts +{ + name: "homarr-custom-widget"; + version: string; + skillMd: string; + skillsShUrl: string; + sourceUrl: string; + installCommand: string; +} +``` + +The full installed component catalog stays available through `homarr://custom-widgets/components` and per-component resources. It is deliberately not embedded in the skill or clipboard prompt. + +These interfaces do not return an archive URL or archive hash. + +## Create a Custom Widget with MCP + +1. Get the prompt, live schema, and component catalog. +2. Read the external API documentation. +3. Build one definition. +4. Validate the definition without saving it. +5. Create a preview session. +6. Test the queries and actions. +7. Open the preview URL with browser tools. +8. Set the credential if the user supplied it. +9. Otherwise, ask the user for the credential with the ten-minute Homarr credential URL. +10. Inspect the redacted journal. +11. Patch the definition until it is valid. +12. Create the widget. +13. Repeat the procedure for the next widget. + +Each credential URL applies to one definition or preview, one source, and the required fields. The agent receives only the request status. + +Homarr encrypts the plaintext immediately. Homarr does not return the plaintext. + +## Evaluate the copied prompt + +Homarr maintainers can run the same self-contained prompt that the workbench copies through the live generation-quality suite: + +```sh +OPENROUTER_API_KEY=... pnpm --filter @homarr/custom-widgets test:ai +``` + +The suite uses DeepSeek V4 Pro to author five complex widgets and DeepSeek V4 Flash to judge only widgets that pass Homarr's real parser and canonical schema. It saves every response, validated `widget.json`, `widget.jsx`, and detailed category scores under `packages/custom-widgets/.ai-evaluations/`. + +The run has a hard budget of ten generation attempts across all scenarios. Override the models or budget with `OPENROUTER_GENERATOR_MODEL`, `OPENROUTER_JUDGE_MODEL`, and `CUSTOM_WIDGET_AI_MAX_LOOPS`. Generated artifacts are local and ignored by Git; promote a reviewed, validated result into the bundled-widget source deliberately. + +The reference API check uses a real PokeAPI list/detail request and a read-only Portainer container query when `PORTAINER_BASE_URL` and `PORTAINER_API_KEY` are set. Use `pnpm --filter @homarr/custom-widgets test:reference-apis -- --pokeapi-only` for the public PokeAPI check alone. To exercise start, restart, and stop against a disposable container, also set `PORTAINER_TEST_CONTAINER_ID` and the explicit safeguard `PORTAINER_ALLOW_MUTATIONS=1`; the script restores the container's original running state. diff --git a/apps/docs/docs/management/custom-widgets/authoring.mdx b/apps/docs/docs/management/custom-widgets/authoring.mdx new file mode 100644 index 000000000..2fc8d2c1f --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/authoring.mdx @@ -0,0 +1,37 @@ +# Create a Custom Widget + +import { CanonicalCustomWidgetExample } from "@site/src/components/custom-widget-code"; + +The workbench is visual-first: configure the default API connection, add request cards, add option rows, then write JSX. Additional sources and raw manifest JSON remain under Advanced. Code and preview sit side by side on desktop and use tabs on mobile. + +## Manual workflow + +1. Configure the default API source, network scope, authentication, and credential. +2. Add query/action cards. Values can be literals, widget options, or invocation parameters. +3. Add widget options with their control and default value. +4. Write responsive JSX using `data`, `status`, `options`, and temporary `inputs`. +5. Test and preview, inspect Data and the redacted request journal, then save. + + + + + +Every option has a default. Supported controls include text, textarea, number, switch, select, multi-select, slider, date, time, color, icon, URL, duration, time zone, and JSON. Dynamic choices use `choicesFrom` with a query ID and value/label paths. + +## ChatGPT or Claude + +Enter the desired widget and optional API documentation URL, then select **Copy AI prompt**. The single self-contained prompt is below 12,000 characters, starts with your request, includes the lean contract and two polished examples, and never claims that an offline chat has MCP tools. + +The model must return exactly: + +1. One fenced `json` block with `template: "__HOMARR_TEMPLATE__"`. +2. One fenced `jsx` block with the readable template. + +Select **Paste AI response**. Homarr fills the visual builders and shows all actionable schema or JSX errors inline. Enter credentials separately. The prompt deliberately recommends a focused Mantine component set, visual hierarchy, responsive layout, theme compatibility, and loading, empty, failure, and success states. + +Connected agents should use the skills.sh skill and retrieve the live schema and individual component metadata only as needed. diff --git a/apps/docs/docs/management/custom-widgets/custom-jsx.mdx b/apps/docs/docs/management/custom-widgets/custom-jsx.mdx new file mode 100644 index 000000000..b21c489d5 --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/custom-jsx.mdx @@ -0,0 +1,44 @@ +# Use the safe JSX runtime + +Templates are JSX expressions interpreted inside a widget-local safety and render budget. They can read: + +- `data.requestId` — the latest response +- `status.requestId` — `{ loading, ok, status, statusText, error }` +- `options.name` — saved widget configuration +- `inputs.name` — temporary values from declarative `bind` + +Use normal Mantine layouts, typography, feedback, dates, and charts. Official compound names such as `Card.Section`, `Tabs.List`, and `Radio.Group` are supported. Ordinary safe props pass through; a dangerous capability produces an explicit error. + +## Temporary inputs + +```jsx + + + + {(results) => ( + + {(results ?? []).map((item) => ( + {item.name} + ))} + + )} + + +``` + +Bound values live only in React memory while the widget is mounted. They are not saved to the database, board options, exports, browser storage, or `localStorage`. Remounting resets them. Components can share a binding when their adapter types agree. + +## Expression language + +Use expressions, conditionals, optional chaining, arrays, objects, template strings, safe standard helpers, and expression callbacks for `map`, `filter`, `sort`, and trusted runtime slots. Callback blocks, authored `const`, IIFEs, authored recursion, arbitrary functions, imports, hooks, refs, raw events, browser requests, `eval`, and bigint are blocked. + +Bounded regex literals are supported for string matching, splitting, search, and replacement. Patterns with lookbehind, backreferences, nested quantifiers, excessive length, or unsupported flags are rejected. + +## Runtime components + +- `SubFetch` runs a manual query with its `params`. +- `ActionButton` and `ToggleSwitch` run actions. +- `RefreshButton` refreshes load queries. +- `Icon`/`TablerIcon` resolves installed safe icons. + +Always include responsive loading, empty, error, and success states. Runtime failures remain inside the widget tile. diff --git a/apps/docs/docs/management/custom-widgets/index.mdx b/apps/docs/docs/management/custom-widgets/index.mdx index 0395253dc..aa7334880 100644 --- a/apps/docs/docs/management/custom-widgets/index.mdx +++ b/apps/docs/docs/management/custom-widgets/index.mdx @@ -1,208 +1,72 @@ --- -tags: - - Custom Widgets - - API - - Widgets - - JSX +title: Custom Widgets +sidebar_label: Overview +tags: [Custom Widgets, API, JSX, MCP] --- +import { BundledCustomWidgetGallery, CustomWidgetCodeExample } from "@site/src/components/custom-widget-code"; + +export const completeManifest = `{ + "$schema": "homarr-custom-widget-v2", + "name": "Service status", + "sources": { + "default": { "name": "Service API", "baseUrl": "https://status.example.com", "networkScope": "public", "auth": "none" } + }, + "requests": { "status": { "path": "/api/status" } }, + "options": {}, + "template": "{data.status?.label ?? 'Unknown'}" +}`; + # Custom Widgets -:::warning +:::warning Experimental feature -Custom widgets are a new feature. Share feedback, ask questions, and discuss ideas in our [GitHub Discussions](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets). +This feature is experimental and will probably change. If you encounter bugs, need more capabilities, or find something confusing, tell us in the [official discussion thread](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets). Your feedback directly shapes what comes next. Happy hacking! ::: -Custom widgets allow you to fetch data from any HTTP API and display it on your Homarr dashboard. You define the API endpoint, authentication, and how the response should be rendered - no code compilation or server restart required. +Custom JSX v2 is Homarr's only Custom Widget format. A definition contains keyed API sources, keyed requests, optional widget options, and one safe JSX template. Credentials are encrypted separately and never exported. -## Creating a Custom Widget - -To create a custom widget, navigate to the **Custom Widgets** section in the management sidebar and click the **Add** button. Fill in the configuration: - -- **Name** - Display name shown in the widget picker and on the dashboard -- **Description** - Optional description shown in tooltips and management UI -- **Icon URL** - Optional URL to an icon image for the widget -- **URL** - The API endpoint to fetch data from (must include protocol, e.g. `https://api.example.com/stats`) -- **Authentication** - How the API request is authenticated: - - `none` - Public APIs with no authentication - - `bearer` - Bearer token authentication - - `basic` - HTTP Basic auth (username + password) - - `apiKeyHeader` - API key sent as a custom HTTP header - - `apiKeyQuery` - API key sent as a query parameter -- **Header Name** - Custom header or query parameter name for API key auth (e.g. `X-API-Key`) -- **HTTP Method** - `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` -- **Request Body** - JSON string body for `POST`/`PUT`/`PATCH` requests -- **Display Type** - How the API response is rendered (see below) - -## Display Types - -| Display Type | Description | Best For | -| -------------------- | ---------------------------------------------------- | ---------------------------------------- | -| **Single Value** | Extracts a single value with a label and unit | Metrics: temperature, uptime, user count | -| **Key Value** | Multiple labeled key-value pairs with optional units | System stats: CPU, memory, disk | -| **Table** | API array data rendered as a sortable table | Lists of items with columns | -| **Stat Grid** | Labeled values in colored stat cards | Counts: movies, series, albums | -| **Progress Bars** | Values as progress bars with percentages | Usage: disk, quota, capacity | -| **Status Indicator** | Green/red status dots for health checks | Service monitoring | -| **Count Grid** | Simple counts in a grid (no colors) | Library counts | -| **Raw** | Pretty-prints the raw JSON response | Debugging | -| **Action Button** | Clickable button executing the API request | Triggers: restart, clear cache | -| **Custom JSX** | Custom JSX template with Mantine v9 components | Full layout control | - -### AI-Powered JSX Generation - -When editing or creating a custom widget with the **Custom JSX** display type, you'll find a **Copy Prompt** button. Clicking it copies a pre-formatted prompt describing your widget's name, API endpoint, and available Mantine components. Paste this into your preferred AI assistant (ChatGPT, Claude, Copilot, etc.) to generate a JSX template tailored to your data. - -
    -Example: Pokédex widget using Custom JSX - -```json -{ - "$schema": "homarr-custom-widget-v2", - "name": "Pokédex", - "description": "Browseable Pokémon list", - "iconUrl": "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/items/poke-ball.png", - "url": "https://pokeapi.co/api/v2/pokemon?limit=75", - "authType": "none", - "method": "GET", - "displayType": "customJsx", - "displayConfig": { - "type": "customJsx", - "template": "\n \n \n Pokédex\n \n \n \n \n {data.results.map((pokemon, i) =>\n \n \n \n \n \n #{i + 1}\n {pokemon.name}\n \n \n \n \n \n \n )}\n \n \n" - } +```ts +interface HomarrCustomWidgetV2 { + $schema: "homarr-custom-widget-v2"; + name: string; + description?: string; + iconUrl?: string; + sources: Record; + requests: Record; + options?: Record; + template: string; } ``` -
    + -## Importing and Exporting +The browser renders JSX. Homarr's server executes named requests, applies board permissions and network protections, and injects credentials. The browser never receives source credentials. -Custom widgets can be exported and imported as JSON files. To export, select the widget in the list and click the export button. To import, click the import button and paste the JSON. Secrets (API keys, passwords) are never included in exports and must be configured after import. +## Authoring paths -The import format uses `"$schema": "homarr-custom-widget-v2"` to identify the widget version. +- [Create a Custom Widget](./authoring) visually or with one copied AI prompt. +- [Use the JSX runtime](./custom-jsx) for data, Mantine components, temporary inputs, and diagnostics. +- [Configure requests and security](./requests-and-security). +- [Use MCP and the skills.sh skill](./agent-authoring). +- [Correct problems](./troubleshooting). -## Available Mantine Components for Custom JSX +The workbench keeps one continuous layout with visual source, request, and option editors. Advanced raw JSON remains available for experts and AI paste. Invalid values stay inline and only disable the widget preview. -When using the `customJsx` display type, your template has access to a whitelist of [Mantine v9](https://mantine.dev) components. Unrecognized components, event handlers, and dangerous tags are stripped for security. +Exports, imports, Workshop, MCP, and storage all validate the same schema. Old formats are rejected. A missing definition only renders **Custom widget unavailable** inside its tile. -### Layout +## Import and Workshop -| Component | Doc | -| ------------------- | --------------------------------------------- | -| `Stack` | [docs](https://mantine.dev/core/stack) | -| `Group` | [docs](https://mantine.dev/core/group) | -| `Flex` | [docs](https://mantine.dev/core/flex) | -| `Grid` / `Grid.Col` | [docs](https://mantine.dev/core/grid) | -| `SimpleGrid` | [docs](https://mantine.dev/core/simple-grid) | -| `Center` | [docs](https://mantine.dev/core/center) | -| `Container` | [docs](https://mantine.dev/core/container) | -| `Space` | [docs](https://mantine.dev/core/space) | -| `AspectRatio` | [docs](https://mantine.dev/core/aspect-ratio) | +Import review shows origins, authentication modes, network scopes, methods, actions, and permissions. It also lets the user supply each required credential before import. Workshop publishes technically valid widgets immediately; users can vote or report them, and administrators can delete submissions. -### Typography & Content +## Bundled examples -| Component | Doc | -| ----------------- | ------------------------------------------------- | -| `Text` | [docs](https://mantine.dev/core/text) | -| `Title` | [docs](https://mantine.dev/core/title) | -| `Code` | [docs](https://mantine.dev/core/code) | -| `Highlight` | [docs](https://mantine.dev/core/highlight) | -| `Mark` | [docs](https://mantine.dev/core/mark) | -| `Kbd` | [docs](https://mantine.dev/core/kbd) | -| `Blockquote` | [docs](https://mantine.dev/core/blockquote) | -| `Anchor` | [docs](https://mantine.dev/core/anchor) | -| `NumberFormatter` | [docs](https://mantine.dev/core/number-formatter) | +Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public contract. The Tautulli example is the highest-scoring widget preserved from Homarr's AI authoring evaluation: -### Data Display - -| Component | Doc | -| ------------------------- | ------------------------------------------------- | -| `Badge` | [docs](https://mantine.dev/core/badge) | -| `Card` / `Card.Section` | [docs](https://mantine.dev/core/card) | -| `Paper` | [docs](https://mantine.dev/core/paper) | -| `Alert` | [docs](https://mantine.dev/core/alert) | -| `ThemeIcon` | [docs](https://mantine.dev/core/theme-icon) | -| `ColorSwatch` | [docs](https://mantine.dev/core/color-swatch) | -| `Avatar` / `Avatar.Group` | [docs](https://mantine.dev/core/avatar) | -| `Image` | [docs](https://mantine.dev/core/image) | -| `BackgroundImage` | [docs](https://mantine.dev/core/background-image) | -| `Indicator` | [docs](https://mantine.dev/core/indicator) | -| `Pill` | [docs](https://mantine.dev/core/pill) | -| `Spoiler` | [docs](https://mantine.dev/core/spoiler) | - -### Tables - -| Component | Doc | -| --------------------------------------- | -------------------------------------- | -| `Table` / `Table.Thead` / `Table.Tbody` | [docs](https://mantine.dev/core/table) | -| `Table.Tr` / `Table.Th` / `Table.Td` | [docs](https://mantine.dev/core/table) | - -### Lists - -| Component | Doc | -| ---------------------------- | ----------------------------------------- | -| `List` / `List.Item` | [docs](https://mantine.dev/core/list) | -| `Timeline` / `Timeline.Item` | [docs](https://mantine.dev/core/timeline) | - -### Feedback & Loading - -| Component | Doc | -| ------------------------------- | ---------------------------------------------- | -| `Progress` / `Progress.Section` | [docs](https://mantine.dev/core/progress) | -| `RingProgress` | [docs](https://mantine.dev/core/ring-progress) | -| `Skeleton` | [docs](https://mantine.dev/core/skeleton) | -| `Loader` | [docs](https://mantine.dev/core/loader) | - -### Navigation & Overlay - -| Component | Doc | -| ------------------------------------------------------------------------ | -------------------------------------------- | -| `TabsContainer` / `TabPanel` | Custom interactive component | -| `Accordion` / `Accordion.Item` / `Accordion.Control` / `Accordion.Panel` | [docs](https://mantine.dev/core/accordion) | -| `ScrollArea` | [docs](https://mantine.dev/core/scroll-area) | -| `Tooltip` | [docs](https://mantine.dev/core/tooltip) | - -### Charts - -| Component | Doc | -| ---------------- | --------------------------------------------------- | -| `AreaChart` | [docs](https://mantine.dev/charts/area-chart) | -| `BarChart` | [docs](https://mantine.dev/charts/bar-chart) | -| `LineChart` | [docs](https://mantine.dev/charts/line-chart) | -| `DonutChart` | [docs](https://mantine.dev/charts/donut-chart) | -| `PieChart` | [docs](https://mantine.dev/charts/pie-chart) | -| `RadarChart` | [docs](https://mantine.dev/charts/radar-chart) | -| `RadialBarChart` | [docs](https://mantine.dev/charts/radial-bar-chart) | -| `Sparkline` | [docs](https://mantine.dev/charts/sparkline) | - -### Interactive Components - -| Component | Description | -| --------------- | ---------------------------------------- | -| `PaginatedList` | Client-side pagination wrapper | -| `Collapsible` | Expandable/collapsible section | -| `StatBar` | Horizontal stat bar | -| `TypeBadge` | Type-styled badge | -| `Divider` | [docs](https://mantine.dev/core/divider) | - -## Template Bindings - -Your template receives: - -- `data` - The sanitized API response object. Access fields via `data.fieldName` or `data.results[0].name`. -- `String(v)` - Type-safe string conversion -- `Number(v)` - Type-safe number conversion -- `Boolean(v)` - Type-safe boolean conversion -- `Math` - Safe subset: `round`, `floor`, `ceil`, `abs`, `min`, `max`, `pow`, `sqrt`, `PI` -- `JSON.stringify(v)` - JSON serialization -- `Array.isArray(v)` - Array type check -- `Object.keys(v)`, `Object.values(v)`, `Object.entries(v)` - Object utilities - -## Security Constraints - -- Event handlers (`onClick`, `onChange`, etc.) are stripped -- Dangerous HTML attributes (`dangerouslySetInnerHTML`) are stripped -- `script`, `iframe`, `object`, `embed`, `form`, `style`, `link`, `meta`, `base` tags are forbidden -- Template strings containing `eval`, `Function`, `import`, `require`, `globalThis`, `window`, `document`, `fetch` are rejected -- Anchor `href` attributes are validated to only allow `https://`, relative (`/`), and hash (`#`) URLs + diff --git a/apps/docs/docs/management/custom-widgets/requests-and-security.mdx b/apps/docs/docs/management/custom-widgets/requests-and-security.mdx new file mode 100644 index 000000000..cc784cbe9 --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/requests-and-security.mdx @@ -0,0 +1,42 @@ +# Configure requests and security + +Most widgets use a single source named `default`. Extra keyed sources are available under Advanced for widgets that combine APIs. Authentication is `none`, `bearer`, `basic`, an API-key header, or an API-key query parameter. Credentials belong to the widget but remain outside its manifest. + +## Named requests + +Requests are keyed by ID. `source`, `kind`, `method`, `trigger`, `auth`, and `permission` have sensible defaults, so a load query can be as small as: + +```json +{ "status": { "path": "/api/status" } } +``` + +The request `path` is appended to the source `baseUrl`, including a base path such as `/api/v2`. + +GET, POST, PUT, PATCH, and DELETE work for queries and actions. Kind—not method—controls behavior. Load queries run automatically, manual queries run through `SubFetch`, and actions run only from `ActionButton` or `ToggleSwitch`. + +Bind values directly where they are used: + +```json +{ + "containers": { + "path": "/api/endpoints/{option:endpointId}/docker/containers/json", + "query": { "all": { "$option": "showAll" } } + }, + "restart": { + "kind": "action", + "method": "POST", + "path": "/api/endpoints/{option:endpointId}/docker/containers/{param:id}/restart", + "invalidates": ["containers"] + } +} +``` + +`{option:name}` and `$option` read saved widget options. `{param:name}` and `$param` read invocation-time `params`. Load queries cannot use invocation parameters. Homarr infers the exact parameter names and primitive values from these references, rejecting missing or extra invocation params at the request boundary. + +Paths and query-string values must resolve to text, numbers, or booleans. JSON bodies can also use structured `json` and `multiSelect` option values, for example `{ "entity_ids": { "$option": "entities" } }`. + +## Protection + +Every request uses Homarr's existing server executor: same-origin source enforcement, network scope, DNS and redirect validation, SSRF protection, board permissions, rate and request limits, body and response limits, timeouts, and encrypted credential injection. Static headers cannot override credentials, cookies, routing, proxy, forwarding, or hop-by-hop headers. + +Queries default to view permission and actions to modify. DELETE always requires full permission and confirmation. Actions are never cached, retried, or run on load. diff --git a/apps/docs/docs/management/custom-widgets/troubleshooting.mdx b/apps/docs/docs/management/custom-widgets/troubleshooting.mdx new file mode 100644 index 000000000..20b216afe --- /dev/null +++ b/apps/docs/docs/management/custom-widgets/troubleshooting.mdx @@ -0,0 +1,59 @@ +# Correct Custom Widget problems + +## Correct an unavailable widget + +The definition does not exist. Remove the unavailable tile from the board. + +Then, install or create a Custom JSX v2 definition. Homarr does not provide recovery or migration for old formats. + +## Correct an invalid saved definition + +The Custom Widgets page isolates a definition that does not conform to the current schema. The other definitions remain available. + +An invalid definition shows its validation errors. You can delete it. + +You cannot edit, enable, export, duplicate, publish, or select an invalid definition. Recreate the definition or import a valid definition. + +Homarr does not migrate old Custom JSX formats. + +## Correct validation errors + +Read the first schema or JSX diagnostic. Use its path to find the invalid value. + +Make sure keyed API source and request names are valid and unique. + +Make sure that each named request references an API source. Use explicit `$option` and `$param` references. + +Make sure every option default matches its control. Use the correct request kind for each runtime component. + +An incomplete API source URL or icon URL causes a form validation error. The workbench keeps the draft open. + +The workbench marks the invalid field while you type. An invalid URL does not replace the form with the error boundary. + +An invalid definition disables only the widget preview. The Data, Options, Actions, and Diagnostics tabs remain available. + +The Diagnostics tab shows the current schema errors. + +## Correct request errors + +Check the API source network scope. Check the base URL and credentials. + +Check the request method, path, body, direct value bindings, and board permission. + +For “invalid placeholder,” use `{option:name}` or `{param:name}`. Load queries can only reference options. The preview journal does not show credentials. + +The journal shows the method, request ID, path template, status, and duration. + +## Correct a Mantine prop warning + +`UNKNOWN_MANTINE_PROP` is a warning. Homarr passes the prop to Mantine. + +Check the prop in the documentation for the installed Mantine version. `BLOCKED_CAPABILITY` identifies an unsafe capability. + +Use safe widget options, temporary inputs, or named requests instead. + +## Repair an existing item + +The widget option definitions changed and the saved values are invalid. Open the item settings. + +Correct the marked configuration values. Homarr does not infer widget option migrations. diff --git a/apps/docs/docs/management/integrations/index.mdx b/apps/docs/docs/management/integrations/index.mdx index 51b3424d3..de819e692 100644 --- a/apps/docs/docs/management/integrations/index.mdx +++ b/apps/docs/docs/management/integrations/index.mdx @@ -6,11 +6,13 @@ tags: --- # Integrations + Integrations are connections to supported third party applications. This page will describe the process of managing integrations but the process may vary depending on your specific integration. Check [the available integrations](/docs/category/integrations) for further information. ## Create an integration + To create an integration, you can choose the supported application from the dropdown at the top right: ![](./img/create-integration-dropdown.png) @@ -20,19 +22,24 @@ Next, you'll need to fill out the required fields to configure the integration: ![](./img/form-create-integration.png) ### Name + Must be at least 1 character long, can be chosen freely. ### Url + This must be the base URL of the application where Homarr should connect to. A few examples for this field include: + - http://sabnzbd.example.com - https://example.com/sabnzbd You must not append any path after the base URL. Some examples for incorrect usage: + - http://sabnzbd.example.com/settings - https://example.com/sabnzbd/settings ### Secrets + An integration may or may not require secrets to function. To process to obtain them is usually [documented in the integration pages](/docs/category/integrations). Secrets are encrypted using a symmetric encryption and stored in the database. @@ -47,6 +54,7 @@ If you already have an application created, you can also link it to the integrat On the edit page you can always change or remove the linked application. ### Testing and saving integration + It is not allowed to create an integration without passing the test. This is to ensure that you minimize the amount of broken applications on your Homarr instance. The test and create button will perform a network request to the application and authenticate if required. @@ -62,6 +70,7 @@ On the edit page of an integration, you can manage which users / groups can ![](./img/integration-permissions.png) ## Troubleshooting connection + The connection to your integrations can fail due to many factors. Most of the time it should show you the reason why it failed. If it doesn't, you can follow these steps to troubleshoot the issue: @@ -70,23 +79,23 @@ If it doesn't, you can follow these steps to troubleshoot the issue: - The secrets must be correct and have the correct permissions. 2. If you use https to connect to the application, check the chapter below about [certificate issues](#certificate-issues). 3. Check whether you followed the Homarr documentation and didn't skip any steps. -This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems. + This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems. 4. Check Homarr's logs for more information. As we have no control over breaking changes in upstream APIs and third party software, -they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported -and fixed within the source code of Homarr. -5. Check whether the host can reach the destination hostname / IP using ``ping`` and ``curl`` or ``wget`` afterward. -Execute this command on the host machine, not inside containers, to check whether it can connect or not. + they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported + and fixed within the source code of Homarr. +5. Check whether the host can reach the destination hostname / IP using `ping` and `curl` or `wget` afterward. + Execute this command on the host machine, not inside containers, to check whether it can connect or not. 6. Check whether the container / pod can reach the destination hostname / IP. Execute the same commands in the shell inside the container / pod. 7. Check your reverse proxy / authentication proxy logs for failures / hints 8. Check your security log of tunnels and VPNs 9. Check your router for security events 10. Check your VLAN configuration and firewall rules 11. Check your DNS settings for the host machine and the containers / pods and whether they can resolve the hostnames -12. Check throughput and stability of your network connection using ``iperf3`` +12. Check throughput and stability of your network connection using `iperf3` 13. Check syslog / drivers of your OS for hints 14. Check logs of your destination applications (eg. SABnzbd) 15. Attempt to disable CSRF / tamper protections when absolutely no other workaround available -> this comes with some security implications - be careful! -Re-enable if this didn't fix the issue. + Re-enable if this didn't fix the issue. If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub. @@ -95,4 +104,4 @@ If none of these troubleshooting steps worked, you can request support from our If you are using a self-signed certificate you'll need to add it to the [trusted certificates](../certificates) in Homarr. Most of the time you should also get a button to add the certificate automatically when you try to connect to the integration. Please check that the certificate is the one you are expecting to prevent Man in the Middle attacks. -For some integrations, you can find a guide on how to retrieve the certificate [here](../certificates/#obtaining-certificates). \ No newline at end of file +For some integrations, you can find a guide on how to retrieve the certificate [here](../certificates/#obtaining-certificates). diff --git a/apps/docs/docs/management/mcp.mdx b/apps/docs/docs/management/mcp.mdx index 7c79d9a8d..4f3b818dc 100644 --- a/apps/docs/docs/management/mcp.mdx +++ b/apps/docs/docs/management/mcp.mdx @@ -73,13 +73,7 @@ Replace `` with your actual API key. Never commit API keys to vers "mcpServers": { "homarr": { "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://your-homarr-instance.com/api/mcp/mcp", - "--header", - "ApiKey:" - ] + "args": ["-y", "mcp-remote", "https://your-homarr-instance.com/api/mcp/mcp", "--header", "ApiKey:"] } } } @@ -126,25 +120,26 @@ curl -s -X POST \ Homarr exposes 50+ tools organized by namespace. Each tool is either a **query** (GET, read-only) or **mutation** (POST, write action). -| Namespace | Example Tools | Type | -| ------------------ | -------------------------------------------------------- | ---------- | -| `app` | List all apps, get app by ID, create/update/delete app | GET + POST | -| `apiKeys` | List API keys | GET | -| `beszel` | Systems status, alerts, historical system metrics | GET | -| `board` | List boards, get board by ID, create/update/delete board | GET + POST | -| `docker` | List containers, inspect container, start/stop/restart | GET + POST | -| `icon` | Search icons | GET | -| `info` | Server health, version info | GET | -| `integration` | List integrations, test connection, delete integration | GET + POST | -| `invite` | List invitations, delete invite | GET + POST | -| `calendar` | Calendar events from media servers | GET | -| `dnsHole` | DNS hole summary, toggle blocking | GET + POST | -| `downloads` | Active downloads, pause/resume/delete | GET + POST | -| `healthMonitoring` | Resource usage stats | GET | -| `patchmon` | Host patch and security update statistics | GET | -| `mediaRequests` | Approve/decline media requests | GET + POST | -| `mediaServer` | Media server sessions and stats | GET | -| `smartHome` | Execute automations, device states | GET + POST | +| Namespace | Example Tools | Type | +| ------------------ | --------------------------------------------------------- | ---------- | +| `app` | List all apps, get app by ID, create/update/delete app | GET + POST | +| `apiKeys` | List API keys | GET | +| `beszel` | Systems status, alerts, historical system metrics | GET | +| `board` | List boards, get board by ID, create/update/delete board | GET + POST | +| `docker` | List containers, inspect container, start/stop/restart | GET + POST | +| `icon` | Search icons | GET | +| `info` | Server health, version info | GET | +| `integration` | List integrations, test connection, delete integration | GET + POST | +| `invite` | List invitations, delete invite | GET + POST | +| `calendar` | Calendar events from media servers | GET | +| `customWidget` | Validate, preview, create, and iteratively update widgets | GET + POST | +| `dnsHole` | DNS hole summary, toggle blocking | GET + POST | +| `downloads` | Active downloads, pause/resume/delete | GET + POST | +| `healthMonitoring` | Resource usage stats | GET | +| `patchmon` | Host patch and security update statistics | GET | +| `mediaRequests` | Approve/decline media requests | GET + POST | +| `mediaServer` | Media server sessions and stats | GET | +| `smartHome` | Execute automations, device states | GET + POST | The tools table on the MCP tab is dynamically generated - it always reflects the latest available procedures from your Homarr instance. @@ -154,6 +149,8 @@ The tools table on the MCP tab is dynamically generated - it always reflects the - Tools inherit the permissions of the API key's owner - OAuth endpoints are rate-limited to prevent abuse - Tool execution errors are contained - a failing tool call does not crash the MCP server +- Custom-widget MCP actions are simulation-only; live preview actions must be enabled explicitly in the browser workbench +- Custom-widget secret values are never returned through MCP - All communication uses HTTPS (configure HTTP → HTTPS redirects on your reverse proxy) ## Use Cases @@ -165,3 +162,60 @@ The tools table on the MCP tab is dynamically generated - it always reflects the - **"How many users are on my Homarr instance?"** - AI lists all users (admin only) - **"Toggle Pi-hole blocking for 5 minutes"** - AI interacts with DNS controls - **"How are my servers doing?"** - AI fetches Beszel system stats including CPU, memory, disk, and alerts +- **"Build a Custom Widget for this API"** - AI validates and previews one definition before it saves the definition + +## Create a Custom Widget with an AI agent + +An agent creates one `homarr-custom-widget-v2` definition at a time. Start with the native prompt `homarr-custom-widget-author`. + +Then, read the live schema and component resources. These resources describe the installed Mantine components. + +1. Call `customWidget_getAuthoringPrompt` and `customWidget_schema`. +2. Build one Custom Widget definition. +3. Call `customWidget_validate` without saving the definition. +4. Call `customWidget_previewCreate`. +5. Test named requests with `customWidget_previewQuery` and `customWidget_previewAction`. +6. Open the returned preview URL. +7. Examine `customWidget_previewJournal`. +8. Change the definition with `customWidget_templatePatch` or `customWidget_update`. +9. Set a supplied credential with `customWidget_secretSet`. +10. Otherwise, call `customWidget_secretRequestUser` to create a ten-minute Homarr entry URL. +11. Call `customWidget_create`. +12. Repeat this procedure for the next Custom Widget. + +The agent receives the credential request status. The agent does not receive the plaintext credential. + +Discovery resources: + +- `homarr://custom-widgets/schema` +- `homarr://custom-widgets/components` +- `homarr://custom-widgets/components/{name}` +- `homarr://custom-widgets/examples/{name}` +- `homarr://custom-widgets/skill` + +An HTTP-only harness can use the matching `/api/custom-widgets/authoring-prompt`, `/schema`, `/components`, and `/skill` endpoints instead of MCP resource URIs. + +The Custom Widget tools are: + +- `customWidget_schema` +- `customWidget_validate` +- `customWidget_list` +- `customWidget_get` +- `customWidget_create` +- `customWidget_update` +- `customWidget_delete` +- `customWidget_templatePatch` +- `customWidget_previewCreate` +- `customWidget_previewQuery` +- `customWidget_previewAction` +- `customWidget_previewJournal` +- `customWidget_secretSet` +- `customWidget_secretRequestUser` +- `customWidget_getAuthoringPrompt` +- `customWidget_getSkill` + +The `custom-widget-manage` permission permits authoring. A direct credential write also requires the `custom-widget-secret-write` permission. + +Homarr applies its request security controls during request execution. These controls include SSRF, DNS, redirect, size, timeout, rate, and permission controls. + +Read [Use agents and skills.sh](./custom-widgets/agent-authoring) for the complete procedure and the portable Agent Skill. diff --git a/apps/docs/docs/management/media/index.mdx b/apps/docs/docs/management/media/index.mdx index 090a6559b..e55a05659 100644 --- a/apps/docs/docs/management/media/index.mdx +++ b/apps/docs/docs/management/media/index.mdx @@ -7,7 +7,8 @@ tags: --- # Media + Using the media feature, you can upload images for custom icons to Homarr. Images will be stored in the database. They can be selected in the [icon picker](/docs/advanced/icons). -![](./img/screenshot.png) \ No newline at end of file +![](./img/screenshot.png) diff --git a/apps/docs/docs/management/search-engines/index.mdx b/apps/docs/docs/management/search-engines/index.mdx index ef9fba2a3..07f2f3098 100644 --- a/apps/docs/docs/management/search-engines/index.mdx +++ b/apps/docs/docs/management/search-engines/index.mdx @@ -6,6 +6,7 @@ tags: --- # Search Engines + Using the search engines, terms can be quickly searched simply by opening the search bar at the top or using the keyboard shortcut `CTRL + K`. ![](./img/search-engines.png) @@ -13,31 +14,36 @@ Using the search engines, terms can be quickly searched simply by opening the se You can add any search engine that has a search URL that accepts a search term as a parameter. ## Create search engine + To create a custom search engine, you can click the button at the top of the page. ![](./img/create-search-engine.png) ### Name + The name can be chosen freely. It will be displayed in the search box popover. ### Short + Prefix that is used to choose the search engine in the popover using the keyboard. -It is recommended that this value is kept short (for example ``g`` for Google and ``e`` for Ecosia). +It is recommended that this value is kept short (for example `g` for Google and `e` for Ecosia). ### Configuration In the configuration section you can select between two options. #### Search template -The template must be a valid URL that incldues the ``%s`` placeholder. -Homarr will replace the ``%s`` with the term that the user entered. + +The template must be a valid URL that incldues the `%s` placeholder. +Homarr will replace the `%s` with the term that the user entered. ##### Examples -- Google: ``https://www.google.com/search?q=%s`` -- Ecosia: ``https://www.ecosia.org/search?q=%s`` -- DuckDuckGo: ``https://duckduckgo.com/?q=%s`` -- Bing: ``https://www.bing.com/search?q=%s`` -- YouTube: ``https://www.youtube.com/results?search_query=%s`` + +- Google: `https://www.google.com/search?q=%s` +- Ecosia: `https://www.ecosia.org/search?q=%s` +- DuckDuckGo: `https://duckduckgo.com/?q=%s` +- Bing: `https://www.bing.com/search?q=%s` +- YouTube: `https://www.youtube.com/results?search_query=%s` ## Media request search @@ -45,12 +51,14 @@ Jellyseerr, Overseerr, and Seerr integrations have a dedicated **Spotlight mode* This mode does not require creating a search engine entry - it is available automatically when you have a compatible integration configured. You can access it from: + - The **Modes list** in Spotlight (opened with `CTRL + K`) - The **search button** on the media request list and stats widgets ### Availability indicators Search results display colored status badges showing the media's current state in your integration: + - **Available** - fully available in your media library - **Partial** - some content (e.g. seasons) is available - **Processing** - currently being downloaded or processed diff --git a/apps/docs/docs/management/settings/index.mdx b/apps/docs/docs/management/settings/index.mdx index d7705e61a..d5ffcff8b 100644 --- a/apps/docs/docs/management/settings/index.mdx +++ b/apps/docs/docs/management/settings/index.mdx @@ -9,10 +9,12 @@ tags: --- # Settings + The settings page has a few options that will be applied to the entire Homarr application. They may require a full page reload for changes to apply. ## Analytics + By default, Homarr is collecting anonymous analytics to identify issues and prioritize bugfixes and improvements. The data is never shared with any third-parties and is fully GDPR & CCPA compliant. The software being used is [Umami Analytics](https://umami.is/) which is fully open source. @@ -21,25 +23,29 @@ The main server software can be found [here](https://github.com/umami-software/u A full list of the collected data by default can be found here: https://umami.is/docs/metric-definitions. We understand that you might not want Homarr to communicate with our services. -By unchecking the ``Send anonymous analytics`` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected. -If you are paranoid, you can permanently block ``umami.homarr.dev`` from your DNS / firewall. +By unchecking the `Send anonymous analytics` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected. +If you are paranoid, you can permanently block `umami.homarr.dev` from your DNS / firewall. Additionally, you opt in to more data collection to help us provide more useful data. ### Integration data + Enabling this optional data will send the types of integrations (e.g. SABnzbd, Sonarr, ...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. ### Widget data + Enabling this optional data will send the types of widgets (e.g. downloads, media streams, iframe, ...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. ### Users data + Enabling this optional data will send the count of users and whether you activated SSO. This will not include any usernames, passwords, emails, URLs, authentication flows or client IDs. This is disabled by default. ## Search Engine Optimization (SEO) + Big companies [like Google, Microsoft, Baidu and Yandex](https://de.wikipedia.org/wiki/Web-Index) will use [web crawlers](https://de.wikipedia.org/wiki/Webcrawler) to index the Internet for new websites & pages. This is desirable in many cases (for example when selling products in an online shop) but can lead to unwanted traffic and attention to your personal dashboard. Homarr is requesting the crawlers to not index Homarr instances by default for this reason. @@ -47,22 +53,26 @@ If you use Homarr as a public website and want it to be searchable on these sear Please note that Homarr doesn't have control over what the crawlers do; it is a mere request to them to not perform these actions but will not guarantee that your website doesn't land on some index. ### No index + This will ask crawlers to not index your Homarr instance on any indexes. It is up to the crawler to properly respect this request. By default, this setting is enabled. Disabling it will allow indexing. ### No follow + If indexing is allowed, crawlers will also attempt to follow any links on your page to further "discover" new parts of the Internet and on your website. By default, this setting is enabled and will ask crawlers to not follow any links. Crawler of different companies may behave differently when indexing is prohibited and following is allowed. ### No translate + Google and Chrome on Android will prompt users to translate pages that are not in their device language. This can lead to some shifting and can be undesired in some cases. By enabling this, you ask crawlers to never translate and never prompt users for translation. It should be noted that some browsers will ignore this and translate regardless. ### No site links search box + This setting is exclusive to Google. [Google will create a box below your domain](https://developers.google.com/search/docs/appearance/structured-data/sitelinks-searchbox) that lists the paths that were discovered by the "folowing". The user can search them directly in Google. @@ -72,7 +82,8 @@ This setting is disabled by default. ## Boards ### Global home board -You can set a global home board that will be used for all users that have not set a home board themselves. + +You can set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. Note that the board must be public to be used as a global home board. @@ -97,9 +108,11 @@ You can decide if the app status should be disabled for all boards. ## Appearance ### Default color scheme + You can set the default color scheme for all users that have not set a color scheme themselves. ## Culture ### Default language -You can set the default language for all users that have not set a language themselves. \ No newline at end of file + +You can set the default language for all users that have not set a language themselves. diff --git a/apps/docs/docs/management/tasks/index.mdx b/apps/docs/docs/management/tasks/index.mdx index bd9395610..c47eb1a74 100644 --- a/apps/docs/docs/management/tasks/index.mdx +++ b/apps/docs/docs/management/tasks/index.mdx @@ -38,6 +38,3 @@ You can disable a task by clicking the "Power" button, which will change it to a When a task is disabled, it will not run automatically according to its schedule. You can enable it again by clicking the "Power-Off" button, which will change it back to a "Power" button. Running a task manually is still possible when it is disabled. - - - diff --git a/apps/docs/docs/management/users/index.mdx b/apps/docs/docs/management/users/index.mdx index 7be233af0..6170a02eb 100644 --- a/apps/docs/docs/management/users/index.mdx +++ b/apps/docs/docs/management/users/index.mdx @@ -20,8 +20,10 @@ Homarr supports [single sign on for easier and seamless authentication](/docs/ad ::: ## Manage users + ### Creating new users -To create new users, you must navigate to ``Mangement`` > ``Users`` > ``Manage`` and click on the create button to create a new one: \ + +To create new users, you must navigate to `Mangement` > `Users` > `Manage` and click on the create button to create a new one: \ ![](./img/button-create-user.png) You'll be guided through the process using a wizard: \ @@ -35,25 +37,31 @@ After you completed all steps, you can start over to create another user or choo ![](./img/wizard-complete.png) ## Editing a user -A user can be edited on the ``Mangement`` > ``Users`` > ``Manage`` page when you click on the username. + +A user can be edited on the `Mangement` > `Users` > `Manage` page when you click on the username. Here you'll have access to two tabs: **General** and **Security**. ### General tab + #### Username + This is the unique username that identifies this user. It can be changed to anything but must be at least 3 characters long with a limit of 255 characters. This name will be used for the credential's login. It is also used to auto-generate profile pictures if no picture was uploaded. #### E-Mail + This is the unique email of the user. As of 1.0, it is not used for any notifications and only for organizational purposes. This field is optional. #### Language + This is the currently selected language of the user. Changing the language will change all text & the right to left (RTL) feature in some languages. By default, Homarr will choose English as the default language. Here you can override the language for this specific user. The user may choose a different language by themselves afterward. #### Home board + Optional field for the board that is loaded by default if no board was specified in the URL. Only boards that the user has permission to are being shown. @@ -70,6 +78,7 @@ Choose the first day of the week for the user. This will affect the calendar wid Option to show icons for status check instead of colored dots. #### Delete + This action will permanently delete the user from the database, including any preferences they set. If the user created boards, they wil **not** be deleted. This action is **irreversible** and cannot be undone. All data is permanently lost. @@ -77,6 +86,7 @@ This action is **irreversible** and cannot be undone. All data is permanently lo ### Security tab #### Change password + Here the password for this user can be changed. It must also meet the password requirements of Homarr. The password is stored as an encrypted value with a salt in the database - this means the value cannot be read out from the database afterward. @@ -85,50 +95,63 @@ This functionality can also be useful to lock out a bad actor without tampering For security reasons, you must confirm the password a second time. ## Groups + Using groups, you can manage the permissions of users. Members can be directly assigned to groups. -A user will have the permissions of all groups they are a member of. +A user will have the permissions of all groups they are a member of. Some permissions include other permissions, for example the "Full board access" permission includes all board permissions. By default, a group called "credentials-admin" will be generated where the first user will be placed. However, you can create as many groups as you'd like. ### Creating a group -Click on the button ``New group`` to create a new one. + +Click on the button `New group` to create a new one. Homarr will prompt you for a group name. ### Managing a group + #### General tab + ##### Name + Name for the group that can be chosen freely. ##### Transfer ownership + Every group has an owner. Using this button, the ownership can be transferred to a different user. Group ownership is only organizational. ##### Delete + Deletes the group permanently. This change is irreversible. #### Settings tab + In this tab, you can configure some settings for the group. Those settings will be prioritized by the order of the groups on the groups list page ##### Priorization + The higher a group in the list, the higher the priority. This means that if a user is in multiple groups, the permissions of the group with the highest priority will be used. It will always fallback to the everyone group if no other group permissions are set. ![](./img/groups-list.png) ##### Boards + Configure board settings for a group. User specific settings will override group settings. ###### Home board + The board that is loaded by default if no board was specified in the URL. ###### Mobile board + The board that is loaded by default on mobile devices. #### Members tab + In this tab, you can assign users to the group. With the button at the top right, a new member can be added to the group: ![](./img/add-group-member.png) @@ -138,6 +161,7 @@ Members can be removed from the group using the remove button at the end: ![](./img/remove-group-member.png) #### Permissions tab + In this tab, you manage what permissions the members of this group will have. Currently, the following permissions are available: @@ -158,9 +182,11 @@ When you changed permissions, you must confirm your changes by clicking the bann ![](./img/changing-group-permissions.png) #### Special groups + Currently one special group exists. This group is `everyone`. It automatically adds every user that is known to Homarr to its members. Neither its name nor its members can be changed. ## Invites + Invites are an easy-to-use system to allow users to onboard themselves. It is useful in companies or large-scale homelabs where many users must be onboarded at the same time. You should trust the end user that they enter their data truthfully as the administrator will not confirm the entered data after the user has completed the onboarding. @@ -169,6 +195,7 @@ This feature can only be used when credentials authentication is enabled. An invitation link can be used indefinitely. ### Creating an invitation + Click on the button: ![](./img/create-invitation-button.png) @@ -179,14 +206,15 @@ The default is 4 hours in the future. ![](./img/invitation-expiry-date.png) -Next, click ``Create`` and you'll get a confirmation with an ID, Token and a link that can be copied: +Next, click `Create` and you'll get a confirmation with an ID, Token and a link that can be copied: ![](./img/create-invitation-confirmation.png) Both ID and Token are also in the URL. Ensure that you copy either ID & Token or the URL - it will never be shown again. -Clicking the ``Copy & close`` button will copy the URL to your clipboard. +Clicking the `Copy & close` button will copy the URL to your clipboard. ### Self-onboarding + Clicking the invitation link will bring up a form with fields for the username and password: ![](./img/invitation-self-onboarding.png) @@ -194,6 +222,7 @@ Clicking the invitation link will bring up a form with fields for the username a At the bottom of the page, the user who created the invitation can be seen. ### Deleting an invitation + If an invitation needs to be deleted before or after the expiry, the delete button at the end of the table can be used: ![](./img/deleting-invitation.png) diff --git a/apps/docs/docs/management/workshop/index.mdx b/apps/docs/docs/management/workshop/index.mdx index c187e2f99..8330b0572 100644 --- a/apps/docs/docs/management/workshop/index.mdx +++ b/apps/docs/docs/management/workshop/index.mdx @@ -7,6 +7,12 @@ tags: # Community Workshop +:::warning Experimental feature + +This feature is experimental and will probably change. If you encounter bugs, need more capabilities, or find something confusing, tell us in the [official discussion thread](https://github.com/homarr-labs/homarr/discussions/categories/custom-widgets). Your feedback directly shapes what comes next. Happy hacking! + +::: + The [Community Workshop](pathname:///workshop) is where Homarr users share and discover **custom CSS themes** and **custom widgets**. You can browse submissions, upvote the ones you like, report abuse, and install entries directly into your own Homarr instance. @@ -19,9 +25,15 @@ The workshop contains community-made content. Widgets may contain unwanted or ma ## Browsing and voting -- Filter by **Widgets** or **CSS**, and sort by **Top rated** or **Newest**. +- Filter by **Widgets** or **CSS**, show or hide outdated entries, and sort by popularity, creation date, recent updates, or discussion activity. - Sign in with **GitHub** to upvote/downvote, submit your own creations, or report a submission. -- Each submission shows its title, description, author, version, an optional screenshot, and the full content. +- Each submission shows its title, description, linked GitHub author, revision, optional screenshots, reports, comments, and full content. +- A new submission receives one real upvote owned by its author. Votes remain unique per user and submission. +- Reports and the manual **Outdated** badge are warnings, not automatic removal. Reported and outdated entries remain installable after confirmation. + +## Comments + +Comments are publicly readable. Signed-in users can post; authors can edit or delete their own comments, and Workshop administrators can delete any comment. Failed posts keep the text you typed. When SMTP and `WORKSHOP_PUBLIC_ORIGIN` are configured, the submission author receives one email for a comment from another user. Self-comments, edits, and deletions do not send mail. ## Submitting @@ -30,7 +42,7 @@ The workshop contains community-made content. Widgets may contain unwanted or ma - **Custom widget** — paste the JSON exported from **Manage → Custom Widgets → Export**. It must match the `homarr-custom-widget-v2` schema (validated before submission). - **Custom CSS** — paste your stylesheet (max 16384 characters). -3. Add a title, description, optional screenshot, and changelog, then submit. +3. Add a title, description, optional screenshots, and changelog, then submit. Submissions are published immediately. Reported entries are reviewed and may be removed. @@ -52,8 +64,14 @@ You can install workshop entries without leaving Homarr: Alternatively, use **Copy** (or **Download** for widgets) on any submission and import it manually. +Custom Widget imports detect required bearer, basic, header, or query credentials. You can enter them during import or explicitly defer them; secret values are never stored in Workshop content. Missing credentials remain visible on the local Custom Widget afterward. + ## Workshop deployment Workshop is powered by [PocketBase](https://pocketbase.io). The production image compiles the current Docusaurus site and serves it together with the API from one origin. The deployment lives in `apps/workshop/` with a Dockerfile, Compose configuration, version-controlled migrations, hooks, a smoke test, and ACT-local workflow instructions. +Run `pnpm docker:workshop` for the PocketBase development service or `pnpm docker:docs` for the built documentation and Workshop site. Both use `apps/workshop/docker-compose.yml` and the persistent `pb_data` volume. Normal start and stop commands retain data; `docker compose -f apps/workshop/docker-compose.yml down --volumes` intentionally recreates the database. + +GitHub needs only the central callback `https:///api/oauth2-redirect`. Keep PocketBase origins unrestricted unless every self-hosted Homarr caller is explicitly listed. Configure `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `WORKSHOP_PUBLIC_ORIGIN`, and PocketBase SMTP settings for authentication and comment email. + Homarr instances use `NEXT_PUBLIC_WORKSHOP_API_URL` to reach the central API and `NEXT_PUBLIC_WORKSHOP_URL` for links to the public page. Docusaurus uses `WORKSHOP_URL` only when its development server runs separately; the combined production image always uses its own origin. diff --git a/apps/docs/docs/widgets/anchor-note/index.mdx b/apps/docs/docs/widgets/anchor-note/index.mdx index 453a5b51c..db925e95a 100644 --- a/apps/docs/docs/widgets/anchor-note/index.mdx +++ b/apps/docs/docs/widgets/anchor-note/index.mdx @@ -1,35 +1,35 @@ --- -title: 'Anchor Note' -description: 'Display and edit a selected note from Anchor' +title: "Anchor Note" +description: "Display and edit a selected note from Anchor" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { anchorNoteWidget } from '.'; -import { anchorIntegration } from '@site/docs/integrations/anchor'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { anchorNoteWidget } from "."; +import { anchorIntegration } from "@site/docs/integrations/anchor"; - - + The Anchor Note widget shows a selected note from your Anchor integration. If your note permissions allow it, you can also edit the note title and content directly in Homarr. ### Screenshots -import anchorNoteWidgetScreenshot from './img/widget.png'; +import anchorNoteWidgetScreenshot from "./img/widget.png"; anchor-note-widget ### Supported Integrations - + ### Interactions diff --git a/apps/docs/docs/widgets/app/index.mdx b/apps/docs/docs/widgets/app/index.mdx index ec62d862e..77d8ec878 100644 --- a/apps/docs/docs/widgets/app/index.mdx +++ b/apps/docs/docs/widgets/app/index.mdx @@ -1,30 +1,26 @@ --- -title: 'App' -description: 'Embeds an app into the board.' +title: "App" +description: "Embeds an app into the board." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { appWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { appWidget } from "."; - - + The app widget allows you to add a link to an application or a website that you want to access quickly from your Homarr board. It also supports a status check to indicate whether Homarr can reach the application or website. ### Screenshots -import githubApp from './img/github.png'; -import jellyseerrApp from './img/jellyseerr-description-tooltip.png'; -import piHoleApp from './img/pi-hole-ping-icon.png'; +import githubApp from "./img/github.png"; +import jellyseerrApp from "./img/jellyseerr-description-tooltip.png"; +import piHoleApp from "./img/pi-hole-ping-icon.png"; -
    +
    app github with-status-check app pi-hole with-status-check status-check-icon app jellyseerr with-description-tooltip @@ -34,4 +30,5 @@ import piHoleApp from './img/pi-hole-ping-icon.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/audio-stats/index.mdx b/apps/docs/docs/widgets/audio-stats/index.mdx index f37a4eb83..687c1cde9 100644 --- a/apps/docs/docs/widgets/audio-stats/index.mdx +++ b/apps/docs/docs/widgets/audio-stats/index.mdx @@ -1,22 +1,18 @@ --- -title: 'Audio Stats' -description: 'Displays library statistics from Navidrome or Audiobookshelf, adapting its display based on the linked integration.' +title: "Audio Stats" +description: "Displays library statistics from Navidrome or Audiobookshelf, adapting its display based on the linked integration." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { audioStatsWidget } from '.'; -import { navidromeIntegration } from '@site/docs/integrations/navidrome'; -import { audiobookshelfIntegration } from '@site/docs/integrations/audiobookshelf'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { audioStatsWidget } from "."; +import { navidromeIntegration } from "@site/docs/integrations/navidrome"; +import { audiobookshelfIntegration } from "@site/docs/integrations/audiobookshelf"; - - + This widget adapts its display based on the linked integration: @@ -27,17 +23,23 @@ Only options relevant to your linked integration are shown in the configuration ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/bazarr/index.mdx b/apps/docs/docs/widgets/bazarr/index.mdx index e262cfa75..6a87a4e0f 100644 --- a/apps/docs/docs/widgets/bazarr/index.mdx +++ b/apps/docs/docs/widgets/bazarr/index.mdx @@ -1,26 +1,23 @@ --- -title: 'Bazarr' -description: 'Displays missing subtitle counts and health indicators from your Bazarr instance.' +title: "Bazarr" +description: "Displays missing subtitle counts and health indicators from your Bazarr instance." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { bazarrWidget } from '.'; -import { bazarrIntegration } from '@site/docs/integrations/bazarr'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { bazarrWidget } from "."; +import { bazarrIntegration } from "@site/docs/integrations/bazarr"; - + This widget shows subtitle status from your Bazarr instance, including missing episode and movie subtitles, provider issues, and health warnings. ### Screenshots -import widgetOverview from './img/widget-overview.png'; +import widgetOverview from "./img/widget-overview.png";
    bazarr-widget-overview @@ -28,14 +25,19 @@ import widgetOverview from './img/widget-overview.png'; ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/beszel-alerts/index.mdx b/apps/docs/docs/widgets/beszel-alerts/index.mdx index 3a4899d17..4a669f3f4 100644 --- a/apps/docs/docs/widgets/beszel-alerts/index.mdx +++ b/apps/docs/docs/widgets/beszel-alerts/index.mdx @@ -1,22 +1,19 @@ --- -title: 'Beszel Alerts' -description: 'View Beszel alert configurations and history with triggered/ok status indicators.' +title: "Beszel Alerts" +description: "View Beszel alert configurations and history with triggered/ok status indicators." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { beszelAlertsWidget } from '.'; -import { beszelIntegration } from '@site/docs/integrations/beszel'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { beszelAlertsWidget } from "."; +import { beszelIntegration } from "@site/docs/integrations/beszel"; -import beszelAlerts from './img/beszel-alerts.png'; +import beszelAlerts from "./img/beszel-alerts.png"; - + This widget displays your Beszel alert configurations separated by status (triggered and ok). It also shows alert history with timestamps. Alerts are updated in real time via WebSocket subscriptions. @@ -26,14 +23,19 @@ This widget displays your Beszel alert configurations separated by status (trigg ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/beszel-system-grid/index.mdx b/apps/docs/docs/widgets/beszel-system-grid/index.mdx index e3b17623b..993974914 100644 --- a/apps/docs/docs/widgets/beszel-system-grid/index.mdx +++ b/apps/docs/docs/widgets/beszel-system-grid/index.mdx @@ -1,22 +1,19 @@ --- -title: 'Beszel Systems (Grid)' -description: 'Card grid view of all Beszel-monitored systems with real-time metrics.' +title: "Beszel Systems (Grid)" +description: "Card grid view of all Beszel-monitored systems with real-time metrics." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { beszelSystemGridWidget } from '.'; -import { beszelIntegration } from '@site/docs/integrations/beszel'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { beszelSystemGridWidget } from "."; +import { beszelIntegration } from "@site/docs/integrations/beszel"; -import beszelSystemGrid from './img/beszel-system-grid.png'; +import beszelSystemGrid from "./img/beszel-system-grid.png"; - + This widget displays all your Beszel-monitored systems as a responsive card grid. Each card shows real-time metrics like CPU, memory, disk, network, temperature, and more. Cards adapt their layout based on available space. If Beszel reports multiple filesystems, the disk bar exposes a hover breakdown for the root disk and each extra mount. @@ -28,14 +25,19 @@ Select a system card to open the complete statistics view, including system, fil ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/beszel-system-table/index.mdx b/apps/docs/docs/widgets/beszel-system-table/index.mdx index df68fcc1b..87cb16ac5 100644 --- a/apps/docs/docs/widgets/beszel-system-table/index.mdx +++ b/apps/docs/docs/widgets/beszel-system-table/index.mdx @@ -1,21 +1,17 @@ --- -title: 'Beszel Systems (Table)' -description: 'Table view of all Beszel-monitored systems with sortable columns and status indicators.' +title: "Beszel Systems (Table)" +description: "Table view of all Beszel-monitored systems with sortable columns and status indicators." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { beszelSystemTableWidget } from '.'; -import { beszelIntegration } from '@site/docs/integrations/beszel'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { beszelSystemTableWidget } from "."; +import { beszelIntegration } from "@site/docs/integrations/beszel"; - - + This widget displays all your Beszel-monitored systems in a sortable data table. Each row shows system metrics like CPU, memory, disk, network, temperature, and more. Columns can be toggled on or off, and the table supports sorting by any column. When Beszel reports extra filesystems, the disk column adds a hover breakdown for each mount alongside the root disk. @@ -23,14 +19,19 @@ Select a system row to open the complete statistics view, including system, file ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/bookmarks/index.mdx b/apps/docs/docs/widgets/bookmarks/index.mdx index c3104ad5b..ed8be9bb6 100644 --- a/apps/docs/docs/widgets/bookmarks/index.mdx +++ b/apps/docs/docs/widgets/bookmarks/index.mdx @@ -1,29 +1,25 @@ --- -title: 'Bookmarks' -description: 'Displays multiple app links' +title: "Bookmarks" +description: "Displays multiple app links" hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { bookmarksWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { bookmarksWidget } from "."; - - + The bookmarks widget allows you to display multiple app links in a single widget. You can add links to your favorite applications, websites, or any other resources you want quick access to. ### Screenshots -import gridIconsOnly from './img/grid-icons-only.png'; -import gridWithTitle from './img/grid-with-title.png'; -import verticalListAll from './img/vertical-list-all.png'; -import vericalListSimple from './img/vertical-list-simple.png'; +import gridIconsOnly from "./img/grid-icons-only.png"; +import gridWithTitle from "./img/grid-with-title.png"; +import verticalListAll from "./img/vertical-list-all.png"; +import vericalListSimple from "./img/vertical-list-simple.png";
    @@ -33,12 +29,13 @@ import vericalListSimple from './img/vertical-list-simple.png'; bookmarks grid with-title bookmarks vertical-list all-elements -
    +
    ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/calendar/index.mdx b/apps/docs/docs/widgets/calendar/index.mdx index 5db4e9b30..f84a0daae 100644 --- a/apps/docs/docs/widgets/calendar/index.mdx +++ b/apps/docs/docs/widgets/calendar/index.mdx @@ -1,65 +1,71 @@ --- -title: 'Calendar' -description: 'Display events from your integrations in a calendar view within a certain relative time period' +title: "Calendar" +description: "Display events from your integrations in a calendar view within a certain relative time period" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { calendarWidget } from '.'; -import { lidarrIntegration } from '@site/docs/integrations/lidarr'; -import { nextcloudIntegration } from '@site/docs/integrations/nextcloud'; -import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant'; -import { radarrIntegration } from '@site/docs/integrations/radarr'; -import { readarrIntegration } from '@site/docs/integrations/readarr'; -import { sonarrIntegration } from '@site/docs/integrations/sonarr'; -import { icalIntegration } from '@site/docs/integrations/ical'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { calendarWidget } from "."; +import { lidarrIntegration } from "@site/docs/integrations/lidarr"; +import { nextcloudIntegration } from "@site/docs/integrations/nextcloud"; +import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant"; +import { radarrIntegration } from "@site/docs/integrations/radarr"; +import { readarrIntegration } from "@site/docs/integrations/readarr"; +import { sonarrIntegration } from "@site/docs/integrations/sonarr"; +import { icalIntegration } from "@site/docs/integrations/ical"; - - + The calendar widget shows a month view of events from different integrations. It allows you to view calendar events or upcoming releases from your media managers. ### Screenshots -import popover from './img/popover.png'; -import withIntegrations from './img/with-integrations.png'; -import withoutIntegrations from './img/without-integrations.png'; +import popover from "./img/popover.png"; +import withIntegrations from "./img/with-integrations.png"; +import withoutIntegrations from "./img/without-integrations.png"; -
    - calendar with-integrations big-size -
    - calendar popover-details the-mandalorian - calendar without-integrations small-size -
    +
    + calendar with-integrations big-size +
    + calendar popover-details the-mandalorian + calendar without-integrations small-size +
    ### Supported Integrations - + ### Interactions @@ -72,4 +78,5 @@ import withoutIntegrations from './img/without-integrations.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/clock/index.mdx b/apps/docs/docs/widgets/clock/index.mdx index efdab31d4..0c41d7ae7 100644 --- a/apps/docs/docs/widgets/clock/index.mdx +++ b/apps/docs/docs/widgets/clock/index.mdx @@ -1,38 +1,34 @@ --- -title: 'Date and time' -description: 'Displays the current date and time.' +title: "Date and time" +description: "Displays the current date and time." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { clockWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { clockWidget } from "."; - - + The clock widget displays the current date and time in a customizable format. ### Screenshots -import localClock from './img/local.png'; -import londonClock from './img/london-with-seconds.png'; -import tokyoClock from './img/tokyo-12-hour.png'; +import localClock from "./img/local.png"; +import londonClock from "./img/london-with-seconds.png"; +import tokyoClock from "./img/tokyo-12-hour.png"; -
    - clock format-24-hours timezone-local - clock format-24-hours with-seconds timezone-london - clock format-12-hours timezone-tokyo +
    + clock format-24-hours timezone-local + clock format-24-hours with-seconds timezone-london + clock format-12-hours timezone-tokyo
    - ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/coolify/index.mdx b/apps/docs/docs/widgets/coolify/index.mdx index 23eb6ba03..807ad502d 100644 --- a/apps/docs/docs/widgets/coolify/index.mdx +++ b/apps/docs/docs/widgets/coolify/index.mdx @@ -1,28 +1,29 @@ --- -title: 'Coolify' -description: 'Overview of your Coolify instance with servers, applications, and services.' +title: "Coolify" +description: "Overview of your Coolify instance with servers, applications, and services." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { coolifyWidget } from '.'; -import { coolifyIntegration } from '@site/docs/integrations/coolify'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { coolifyWidget } from "."; +import { coolifyIntegration } from "@site/docs/integrations/coolify"; - + The Coolify widget displays a compact overview of your Coolify instance. It can show servers, applications, and services with status indicators, project and environment context, direct links to Coolify, and the installed Coolify version. ### Supported Integrations - + ### Adding the widget @@ -34,11 +35,11 @@ The Coolify widget displays a compact overview of your Coolify instance. It can ### Sections -| Section | Description | -|---|---| -| **Servers** | Lists Coolify servers, reachability status, and application/service counts per server. | +| Section | Description | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| **Servers** | Lists Coolify servers, reachability status, and application/service counts per server. | | **Applications** | Lists applications with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links. | -| **Services** | Lists services with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links. | +| **Services** | Lists services with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links. | ### Notes diff --git a/apps/docs/docs/widgets/custom-api/index.mdx b/apps/docs/docs/widgets/custom-api/index.mdx index 78d0bcbba..b3d1e15ab 100644 --- a/apps/docs/docs/widgets/custom-api/index.mdx +++ b/apps/docs/docs/widgets/custom-api/index.mdx @@ -1,29 +1,57 @@ --- -title: 'Custom API' -description: 'Displays data from a custom API endpoint using configurable display types and optional JSX templates.' +title: "Custom API" +description: "The Custom API widget shows a Custom JSX v2 definition with server-side API requests, widget options, and actions." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { customApiWidget } from '.'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { customApiWidget } from "."; + - +The Custom API widget shows a Custom JSX v2 definition. Create the definition in [Management → Custom Widgets](/docs/management/custom-widgets). -This widget fetches data from a custom API endpoint defined in [Custom Widgets management](/docs/management/custom-widgets) and renders it using configurable display types. +A definition contains API sources, named requests, a widget options schema, and one safe JSX template. -Custom API widgets are created and configured through the admin management page. Each widget definition specifies the API endpoint, authentication, display type, and refresh interval. +Temporary inputs exist only while the tile is mounted. Homarr encrypts source credentials separately. -See the [Custom Widgets documentation](/docs/management/custom-widgets) for full details on creating and configuring custom widgets. +Homarr does not send these credentials to the browser. Homarr does not include them in an export. -### Adding the widget +### Add the widget +Select a definition from the searchable picker. Configure its generated widget options. + +Select a refresh interval. The board item stores the definition ID and the validated widget option values. + +Credentials remain on the server. + :::note -Custom API widgets must first be created in **Management → Custom Widgets** before they appear in the widget picker. + +Enable the definition before you use it. The definition must also be available to the board. + ::: + +### Permissions and actions + +Each named request declares its minimum board permission. This permission does not depend on the HTTP method. + +Queries and actions can use GET, POST, PUT, PATCH, or DELETE. The `kind` value controls runtime behavior. + +A DELETE request requires full board permission and confirmation. An anonymous viewer cannot run an action. + +Homarr disables interactive controls in board edit mode. An action runs only after a user action. + +Mounting, refresh polling, and automatic retries do not run actions. An authoring preview simulates actions by default. + +An administrator can enable live actions for the short preview session. + +### Refresh behavior + +The refresh interval runs load queries again. `SubFetch` runs manual queries. + +Each query can declare a cache duration. A successful action can invalidate only its declared queries. + +Read [Custom Widgets management](/docs/management/custom-widgets) for authoring, widget options, named requests, Mantine, network scopes, and security limits. diff --git a/apps/docs/docs/widgets/custom-api/index.ts b/apps/docs/docs/widgets/custom-api/index.ts index c6c56bc53..6b72691d0 100644 --- a/apps/docs/docs/widgets/custom-api/index.ts +++ b/apps/docs/docs/widgets/custom-api/index.ts @@ -4,6 +4,7 @@ import { IconApi } from "@tabler/icons-react"; export const customApiWidget: WidgetDefinition = { icon: IconApi, name: "Custom API", - description: "Displays data from a custom API endpoint using configurable display types and optional JSX templates.", + description: + "Renders an administrator-defined Custom JSX v2 widget with server-side API requests, options, and actions.", path: "../../widgets/custom-api", }; diff --git a/apps/docs/docs/widgets/dns-hole-controls/index.mdx b/apps/docs/docs/widgets/dns-hole-controls/index.mdx index cea517545..74c8cc88b 100644 --- a/apps/docs/docs/widgets/dns-hole-controls/index.mdx +++ b/apps/docs/docs/widgets/dns-hole-controls/index.mdx @@ -1,47 +1,48 @@ --- -title: 'DNS Hole Controls' +title: "DNS Hole Controls" description: "Control PiHole or AdGuard from your dashboard." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { dnsHoleControlsWidget } from '.'; -import { adguardHomeIntegration } from '@site/docs/integrations/adguard-home'; -import { piHoleIntegration } from '@site/docs/integrations/pi-hole'; -import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { dnsHoleControlsWidget } from "."; +import { adguardHomeIntegration } from "@site/docs/integrations/adguard-home"; +import { piHoleIntegration } from "@site/docs/integrations/pi-hole"; +import { technitiumDnsIntegration } from "@site/docs/integrations/technitium-dns"; - - + This widget allows you to enable or disable your DNS Hole. ### Screenshots -import bigSize from './img/big.png'; -import smallSize from './img/small.png'; - +import bigSize from "./img/big.png"; +import smallSize from "./img/small.png"; dns-hole-controls big-size with-toggle-all-buttons dns-hole-controls small-size no-toggle-all-buttons ### Supported Integrations - + ### Interactions @@ -54,4 +55,5 @@ import smallSize from './img/small.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/dns-hole-summary/index.mdx b/apps/docs/docs/widgets/dns-hole-summary/index.mdx index 1dcb123da..99fd69dbd 100644 --- a/apps/docs/docs/widgets/dns-hole-summary/index.mdx +++ b/apps/docs/docs/widgets/dns-hole-summary/index.mdx @@ -1,38 +1,34 @@ --- -title: 'DNS Hole Summary' +title: "DNS Hole Summary" description: "Displays the summary of your DNS Hole." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { dnsHoleSummaryWidget } from '.'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { dnsHoleSummaryWidget } from "."; - - + This widget allows you to display statistics about your DNS Hole like total queries, blocked queries, and more. ### Screenshots -import gridLayout from './img/grid.png'; -import verticalLayout from './img/vertical.png'; -import horizontalLayout from './img/horizontal.png'; -import { adguardHomeIntegration } from '@site/docs/integrations/adguard-home'; -import { piHoleIntegration } from '@site/docs/integrations/pi-hole'; -import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns'; +import gridLayout from "./img/grid.png"; +import verticalLayout from "./img/vertical.png"; +import horizontalLayout from "./img/horizontal.png"; +import { adguardHomeIntegration } from "@site/docs/integrations/adguard-home"; +import { piHoleIntegration } from "@site/docs/integrations/pi-hole"; +import { technitiumDnsIntegration } from "@site/docs/integrations/technitium-dns"; -
    +
    grid-layout pi-hole-colors -
    +
    vertical-layout no-colors horizontal-layout pi-hole-colors
    @@ -40,17 +36,24 @@ import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/docker-containers/index.mdx b/apps/docs/docs/widgets/docker-containers/index.mdx index fe509f86a..898d2f3a5 100644 --- a/apps/docs/docs/widgets/docker-containers/index.mdx +++ b/apps/docs/docs/widgets/docker-containers/index.mdx @@ -1,24 +1,20 @@ --- -title: 'Docker stats' -description: 'Stats of your containers' +title: "Docker stats" +description: "Stats of your containers" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { dockerContainersWidget } from '.'; -import { dockerIntegration } from '@site/docs/integrations/docker'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { dockerContainersWidget } from "."; +import { dockerIntegration } from "@site/docs/integrations/docker"; - - + This widget displays the resource usage of your Docker containers and allows you to manage them. @@ -28,19 +24,24 @@ This widget can only be used with administrator privileges. ### Screenshots -import dockerTable from './img/table.png'; +import dockerTable from "./img/table.png"; docker-stats table docker-containers ### Supported Integrations - + ### Interactions Each container row has an action menu (accessible via the three-dot icon) with the following options: + - **View logs** - opens a dedicated terminal page streaming the container's logs - **Start** / **Stop** / **Restart** - manage the container's state - **Remove** - remove the container diff --git a/apps/docs/docs/widgets/downloads/index.mdx b/apps/docs/docs/widgets/downloads/index.mdx index 9242a84eb..20c7fbfc0 100644 --- a/apps/docs/docs/widgets/downloads/index.mdx +++ b/apps/docs/docs/widgets/downloads/index.mdx @@ -1,61 +1,66 @@ --- -title: 'Download Client' -description: 'Allows you to view and manage your Downloads from both Torrent and Usenet clients.' +title: "Download Client" +description: "Allows you to view and manage your Downloads from both Torrent and Usenet clients." hide_title: true --- -import { delugeIntegration } from '@site/docs/integrations/deluge'; -import { nzbgetIntegration } from '@site/docs/integrations/nzbget'; -import { qBittorentIntegration } from '@site/docs/integrations/q-bittorent'; -import { sabnzbdIntegration } from '@site/docs/integrations/sabnzbd'; -import { transmissionIntegration } from '@site/docs/integrations/transmission'; -import { slskdIntegration } from '@site/docs/integrations/slskd'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { delugeIntegration } from "@site/docs/integrations/deluge"; +import { nzbgetIntegration } from "@site/docs/integrations/nzbget"; +import { qBittorentIntegration } from "@site/docs/integrations/q-bittorent"; +import { sabnzbdIntegration } from "@site/docs/integrations/sabnzbd"; +import { transmissionIntegration } from "@site/docs/integrations/transmission"; +import { slskdIntegration } from "@site/docs/integrations/slskd"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; -import { downloadsWidget } from '.'; +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; +import { downloadsWidget } from "."; - - + This widget displays a list of torrents or usenet-articles that are currently being downloaded, along with their progress and other relevant information. ### Screenshots -import downloadsCard from './img/screenshot.png'; +import downloadsCard from "./img/screenshot.png";
    - downloads + downloads
    ### Supported Integrations - + ### Interactions @@ -68,4 +73,5 @@ import downloadsCard from './img/screenshot.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/firewall/index.mdx b/apps/docs/docs/widgets/firewall/index.mdx index 95aaa56d6..425ab8854 100644 --- a/apps/docs/docs/widgets/firewall/index.mdx +++ b/apps/docs/docs/widgets/firewall/index.mdx @@ -1,22 +1,18 @@ --- -title: 'Firewall Monitoring' -description: 'Displays a summary of firewalls.' +title: "Firewall Monitoring" +description: "Displays a summary of firewalls." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { firewallWidget } from '.'; -import { opnsenseIntegration } from '../../integrations/opnsense'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { firewallWidget } from "."; +import { opnsenseIntegration } from "../../integrations/opnsense"; - - + ### Screenshots @@ -24,9 +20,13 @@ import { opnsenseIntegration } from '../../integrations/opnsense'; ### Supported Integrations - + ### Adding the widget diff --git a/apps/docs/docs/widgets/iframe/index.mdx b/apps/docs/docs/widgets/iframe/index.mdx index 5be26f3b2..2c183368f 100644 --- a/apps/docs/docs/widgets/iframe/index.mdx +++ b/apps/docs/docs/widgets/iframe/index.mdx @@ -1,19 +1,15 @@ --- -title: 'iFrame' -description: 'Embed any content from the internet. Some websites may restrict access.' +title: "iFrame" +description: "Embed any content from the internet. Some websites may restrict access." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { iframeWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { iframeWidget } from "."; - - + If your application is not supported natively by Homarr, you can integrate it using the iframe widget. It uses the [iframe element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe), @@ -22,8 +18,8 @@ This means, no traffic is routed through Homarr (and the URL must be reachable f ### Screenshots -import wikipediaHomepage from './img/wikipedia.png'; -import youtubeStream from './img/nasa-iss-stream.png'; +import wikipediaHomepage from "./img/wikipedia.png"; +import youtubeStream from "./img/nasa-iss-stream.png";
    iframe wikipedia-homepage @@ -50,12 +46,14 @@ the appropriate headers (such as `X-Frame-Options` or `Content-Security-Policy`) For example, to allow your site to be embedded in iframes from specific domains: **Apache (.htaccess or httpd.conf):** + ```apache Header set Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com" Header set X-Frame-Options "ALLOW-FROM https://trusted-domain.com" ``` **Nginx:** + ```nginx add_header Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com"; add_header X-Frame-Options "ALLOW-FROM https://trusted-domain.com"; @@ -67,6 +65,7 @@ add_header X-Frame-Options "ALLOW-FROM https://trusted-domain.com"; - **Any YouTube video or stream:** https://www.youtube.com/embed/dQw4w9WgXcQ?si=MWUbbG66UNTla_Ni ### Configuration + ### Transparent iframes @@ -75,15 +74,16 @@ To create a transparent iframe like below you can use the following html code an ```html - + - + ``` ![transparent iframe](./img/transparent-iframe.png) ### Third party content + :::warning The content below is an overview of third party projects. All support requests/problems must be redirected to the appropriate repository. @@ -92,11 +92,12 @@ We cannot guarantee the functionality nor security of these tools. ::: ### homarr-iframes from Diogo Valentim + The project [homarr-iframes](https://github.com/diogovalentte/homarr-iframes) has iframes designed to be used with Homarr, these iframes offer a minimalist view of other systems: - [Vikunja](https://github.com/go-vikunja/vikunja): overview of your tasks with links to them. - [Linkwarden](https://github.com/linkwarden/linkwarden): overview of your bookmarks with links to them. -- [Cinemark Brazil](https://www.cinemark.com.br): overview of the movies in Cinemark theaters in your city (*only in Brazil*). +- [Cinemark Brazil](https://www.cinemark.com.br): overview of the movies in Cinemark theaters in your city (_only in Brazil_). ![Image of the Vikunja (left), Linkwarden (middle), and Cinemark Brazil (right) iframes on a Homarr dashboard](./img/homarr-iframes-example.webp "Image of the Vikunja (left), Linkwarden (middle), and Cinemark Brazil (right) iframes on a Homarr dashboard") diff --git a/apps/docs/docs/widgets/immich-album-carousel/index.mdx b/apps/docs/docs/widgets/immich-album-carousel/index.mdx index 59b1beeb9..d33bf184b 100644 --- a/apps/docs/docs/widgets/immich-album-carousel/index.mdx +++ b/apps/docs/docs/widgets/immich-album-carousel/index.mdx @@ -1,40 +1,38 @@ --- -title: 'Immich Album Carousel' -description: 'Shows a slideshow of your album pictures from Immich' +title: "Immich Album Carousel" +description: "Shows a slideshow of your album pictures from Immich" hide_title: true --- -import { immichIntegration } from '../../integrations/immich';import { - AddingWidget -} from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { immichAlbumCarouselWidget } from '.'; +import { immichIntegration } from "../../integrations/immich"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { immichAlbumCarouselWidget } from "."; - - + ### Screenshots -import screen from './img/screen.png'; +import screen from "./img/screen.png"; immich album size-big ### Supported Integrations - + ### Adding the widget - ### Configuration - + diff --git a/apps/docs/docs/widgets/immich-server-stats/index.mdx b/apps/docs/docs/widgets/immich-server-stats/index.mdx index 73d278a91..4fcb5d4cc 100644 --- a/apps/docs/docs/widgets/immich-server-stats/index.mdx +++ b/apps/docs/docs/widgets/immich-server-stats/index.mdx @@ -1,40 +1,38 @@ --- -title: 'Immich Server Stats' -description: 'Information about your Immich instance' +title: "Immich Server Stats" +description: "Information about your Immich instance" hide_title: true --- -import { immichIntegration } from '../../integrations/immich'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { immichServerStatsWidget } from '.'; +import { immichIntegration } from "../../integrations/immich"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { immichServerStatsWidget } from "."; - - + ### Screenshots -import screen from './img/screen.png'; - +import screen from "./img/screen.png"; immich server stats size-big ### Supported Integrations - + ### Adding the widget - ### Configuration - + diff --git a/apps/docs/docs/widgets/indexer-manager/index.mdx b/apps/docs/docs/widgets/indexer-manager/index.mdx index fad8c341b..aed26828b 100644 --- a/apps/docs/docs/widgets/indexer-manager/index.mdx +++ b/apps/docs/docs/widgets/indexer-manager/index.mdx @@ -1,37 +1,37 @@ --- -title: 'Indexer manager status' -description: 'View the status of your indexers.' +title: "Indexer manager status" +description: "View the status of your indexers." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { indexerManagerWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { indexerManagerWidget } from "."; - - + ### Screenshots -import bigItem from './img/big.png'; -import smallItem from './img/small.png'; -import { prowlarrIntegration } from '@site/docs/integrations/prowlarr'; +import bigItem from "./img/big.png"; +import smallItem from "./img/small.png"; +import { prowlarrIntegration } from "@site/docs/integrations/prowlarr"; -
    +
    indexer-manager size-big indexer-manager size-small
    ### Supported Integrations - + ### Interactions @@ -41,7 +41,6 @@ import { prowlarrIntegration } from '@site/docs/integrations/prowlarr'; - ### Configuration - + diff --git a/apps/docs/docs/widgets/media-missing/index.mdx b/apps/docs/docs/widgets/media-missing/index.mdx index 648bd4190..06799ae2e 100644 --- a/apps/docs/docs/widgets/media-missing/index.mdx +++ b/apps/docs/docs/widgets/media-missing/index.mdx @@ -1,29 +1,26 @@ --- -title: 'Media Missing & Queue' -description: 'Track missing media and active downloads from Radarr and Sonarr' +title: "Media Missing & Queue" +description: "Track missing media and active downloads from Radarr and Sonarr" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { mediaMissingWidget } from '.'; -import { radarrIntegration } from '@site/docs/integrations/radarr'; -import { sonarrIntegration } from '@site/docs/integrations/sonarr'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { mediaMissingWidget } from "."; +import { radarrIntegration } from "@site/docs/integrations/radarr"; +import { sonarrIntegration } from "@site/docs/integrations/sonarr"; - + Monitor which movies and episodes are missing from your library, and track what is currently being downloaded. The widget pulls data from Radarr and Sonarr and groups results by type in two tabs. ### Screenshots -import widgetMissing from './img/missing.png'; -import widgetQueued from './img/queued.png'; -import widgetCompact from './img/compact.png'; +import widgetMissing from "./img/missing.png"; +import widgetQueued from "./img/queued.png"; +import widgetCompact from "./img/compact.png";
    media-missing widget showing missing movies and episodes in a grid @@ -33,18 +30,23 @@ import widgetCompact from './img/compact.png'; ### Supported Integrations - + ### Tabs -| Tab | Description | -|---|---| +| Tab | Description | +| ----------- | ----------------------------------------------------------------------------------------------------- | | **Missing** | Lists movies (Radarr) and episodes (Sonarr) that are monitored but not yet available in your library. | -| **Queued** | Shows items currently being downloaded with a progress bar and estimated time remaining. | +| **Queued** | Shows items currently being downloaded with a progress bar and estimated time remaining. | ### Sizing diff --git a/apps/docs/docs/widgets/media-releases/index.mdx b/apps/docs/docs/widgets/media-releases/index.mdx index fece199eb..71af2b04a 100644 --- a/apps/docs/docs/widgets/media-releases/index.mdx +++ b/apps/docs/docs/widgets/media-releases/index.mdx @@ -1,30 +1,26 @@ --- -title: 'Media releases' -description: 'Display newly added medias or upcoming releases from different integrations' +title: "Media releases" +description: "Display newly added medias or upcoming releases from different integrations" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { mediaReleasesWidget } from '.'; -import { embyIntegration } from '@site/docs/integrations/emby'; -import { jellyfinIntegration } from '@site/docs/integrations/jellyfin'; -import { plexIntegration } from '@site/docs/integrations/plex'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { mediaReleasesWidget } from "."; +import { embyIntegration } from "@site/docs/integrations/emby"; +import { jellyfinIntegration } from "@site/docs/integrations/jellyfin"; +import { plexIntegration } from "@site/docs/integrations/plex"; - - + Provides a list of newly added media or upcoming releases from your media server. ### Screenshots -import backdrop from './img/backdrop.png'; -import poster from './img/poster.png'; +import backdrop from "./img/backdrop.png"; +import poster from "./img/poster.png";
    media-releases layout-backdrop @@ -33,17 +29,24 @@ import poster from './img/poster.png'; ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/media-request-list/index.mdx b/apps/docs/docs/widgets/media-request-list/index.mdx index 2f52a8e1f..1c491a051 100644 --- a/apps/docs/docs/widgets/media-request-list/index.mdx +++ b/apps/docs/docs/widgets/media-request-list/index.mdx @@ -1,41 +1,44 @@ --- -title: 'Media Request List' -description: 'See a list of all media requests from your integration' +title: "Media Request List" +description: "See a list of all media requests from your integration" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { mediaRequestListWidget } from '.'; -import { jellyseerrIntegration } from '@site/docs/integrations/jellyseerr'; -import { overseerrIntegration } from '@site/docs/integrations/overseerr'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { mediaRequestListWidget } from "."; +import { jellyseerrIntegration } from "@site/docs/integrations/jellyseerr"; +import { overseerrIntegration } from "@site/docs/integrations/overseerr"; - - + Provides a list of all open and recently closed requests. It also provides the functionality to approve or reject requests. +You can limit the list to specific request statuses (for example, only show `pending`) and restrict it to requests created within the last N days. + ### Screenshots -import mediaRequestList from './img/list.png'; +import mediaRequestList from "./img/list.png"; media-request-list ### Supported Integrations - + ### Interactions @@ -47,4 +50,5 @@ import mediaRequestList from './img/list.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/media-request-list/index.ts b/apps/docs/docs/widgets/media-request-list/index.ts index 8eb9d8bfb..1732d6fd7 100644 --- a/apps/docs/docs/widgets/media-request-list/index.ts +++ b/apps/docs/docs/widgets/media-request-list/index.ts @@ -14,6 +14,18 @@ export const mediaRequestListWidget: WidgetDefinition = { values: { type: "boolean" }, defaultValue: "yes", }, + { + name: "Statuses to show", + description: "Only requests with these statuses will be shown. Defaults to all statuses.", + values: "List of: 'pending', 'approved', 'declined', 'failed', 'completed'", + defaultValue: "All statuses", + }, + { + name: "Show only recent requests", + description: "Limit to requests created within this many days. Set to 0 to disable the time filter.", + values: "0-365", + defaultValue: "0", + }, ], }, }; diff --git a/apps/docs/docs/widgets/media-request-stats/index.mdx b/apps/docs/docs/widgets/media-request-stats/index.mdx index a7b40f624..fc7d7f465 100644 --- a/apps/docs/docs/widgets/media-request-stats/index.mdx +++ b/apps/docs/docs/widgets/media-request-stats/index.mdx @@ -1,39 +1,40 @@ --- -title: 'Media Requests Stats' -description: 'Statistics about your media requests' +title: "Media Requests Stats" +description: "Statistics about your media requests" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { mediaRequestStatsWidget } from '.'; -import { jellyseerrIntegration } from '@site/docs/integrations/jellyseerr'; -import { overseerrIntegration } from '@site/docs/integrations/overseerr'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { mediaRequestStatsWidget } from "."; +import { jellyseerrIntegration } from "@site/docs/integrations/jellyseerr"; +import { overseerrIntegration } from "@site/docs/integrations/overseerr"; - - + Provide a statistics overview of your media requests, such as mount of requests, open requests, approvement and rejections. ### Supported Integrations - + ### Screenshots -import mediaRequestStats from './img/stats.png'; +import mediaRequestStats from "./img/stats.png"; media-request-stats diff --git a/apps/docs/docs/widgets/media-server/index.mdx b/apps/docs/docs/widgets/media-server/index.mdx index accd83f8e..f73e07b5c 100644 --- a/apps/docs/docs/widgets/media-server/index.mdx +++ b/apps/docs/docs/widgets/media-server/index.mdx @@ -1,53 +1,53 @@ --- -title: 'Media server streams' -description: 'Show the current streams on your media servers' +title: "Media server streams" +description: "Show the current streams on your media servers" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { mediaServerWidget } from '.'; -import { embyIntegration } from '@site/docs/integrations/emby'; -import { jellyfinIntegration } from '@site/docs/integrations/jellyfin'; -import { plexIntegration } from '@site/docs/integrations/plex'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { mediaServerWidget } from "."; +import { embyIntegration } from "@site/docs/integrations/emby"; +import { jellyfinIntegration } from "@site/docs/integrations/jellyfin"; +import { plexIntegration } from "@site/docs/integrations/plex"; + - - -The media server widget enables you to watch and view current active sessions over all your media servers. +The media server widget enables you to watch and view current active sessions over all your media servers. It also displays useful information, that you can use when providing support to users or debugging a problem. - - ### Screenshots -import mediaTable from './img/table.png'; +import mediaTable from "./img/table.png"; media-server-streams ### Supported Integrations - + ### Adding the widget ### Configuration - + diff --git a/apps/docs/docs/widgets/media-transcoding/index.mdx b/apps/docs/docs/widgets/media-transcoding/index.mdx index 0fc280021..62dd00af3 100644 --- a/apps/docs/docs/widgets/media-transcoding/index.mdx +++ b/apps/docs/docs/widgets/media-transcoding/index.mdx @@ -1,35 +1,29 @@ --- -title: 'Media transcoding' -description: 'Statistics, current queue and worker status of your media transcoding' +title: "Media transcoding" +description: "Statistics, current queue and worker status of your media transcoding" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { mediaTranscodingWidget } from '.'; -import { tdarrIntegration } from '@site/docs/integrations/tdarr'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { mediaTranscodingWidget } from "."; +import { tdarrIntegration } from "@site/docs/integrations/tdarr"; + - - -The media transcoding widget provides you with an overview of your media transcoding status. +The media transcoding widget provides you with an overview of your media transcoding status. It shows you the current queue, worker status, and statistics about your transcoding jobs. - - ### Screenshots -import queueCard from './img/queue.png'; -import workersCard from './img/workers.png'; -import statisticsCard from './img/statistics.png'; +import queueCard from "./img/queue.png"; +import workersCard from "./img/workers.png"; +import statisticsCard from "./img/statistics.png";
    media-transcoding workers-tab @@ -39,13 +33,18 @@ import statisticsCard from './img/statistics.png'; ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/minecraft-server-status/index.mdx b/apps/docs/docs/widgets/minecraft-server-status/index.mdx index 51101246b..d96a2f190 100644 --- a/apps/docs/docs/widgets/minecraft-server-status/index.mdx +++ b/apps/docs/docs/widgets/minecraft-server-status/index.mdx @@ -1,32 +1,28 @@ --- -title: 'Minecraft Server Status' -description: 'Displays the status of a Minecraft server.' +title: "Minecraft Server Status" +description: "Displays the status of a Minecraft server." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; -import { minecraftServerStatusWidget } from '.'; +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; +import { minecraftServerStatusWidget } from "."; - - + Shows the status and amount of players on a Minecraft server. It supports both Java and Bedrock editions, however only public servers are supported which can be reached through the used api of [api.mcsrvstat.us](https://api.mcsrvstat.us). ### Screenshots -import javaItem from './img/java.png'; -import bedrockItem from './img/bedrock.png'; +import javaItem from "./img/java.png"; +import bedrockItem from "./img/bedrock.png"; -
    +
    minecraft-server-status java-edition minecraft-server-status bedrock-editon
    @@ -36,9 +32,10 @@ import bedrockItem from './img/bedrock.png'; ### Configuration + ### Data source We use the Minecraft Server Status API to fetch the server status. -If you need to whitelist the api, please use the following URL: `hhttps://api.mcsrvstat.us` \ No newline at end of file +If you need to whitelist the api, please use the following URL: `hhttps://api.mcsrvstat.us` diff --git a/apps/docs/docs/widgets/network-controller-status/index.mdx b/apps/docs/docs/widgets/network-controller-status/index.mdx index a01496234..29a5bbb8e 100644 --- a/apps/docs/docs/widgets/network-controller-status/index.mdx +++ b/apps/docs/docs/widgets/network-controller-status/index.mdx @@ -1,44 +1,45 @@ --- -title: 'Network Status' -description: 'Display connected devices on a network' +title: "Network Status" +description: "Display connected devices on a network" hide_title: true --- -import { unifiControllerIntegration } from '@site/docs/integrations/unifi-controller'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { unifiControllerIntegration } from "@site/docs/integrations/unifi-controller"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; -import { networkControllerStatusWidget } from '.'; +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; +import { networkControllerStatusWidget } from "."; - - + Shows connected users and connected guest devices on wired or wireless networks. ### Screenshots -import wifiCard from './img/wifi.png'; -import wiredCard from './img/wired.png'; +import wifiCard from "./img/wifi.png"; +import wiredCard from "./img/wired.png"; network-controller-status wifi network-controller-status wired ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/network-controller-summary/index.mdx b/apps/docs/docs/widgets/network-controller-summary/index.mdx index fe4cd3357..c7c2f4d4d 100644 --- a/apps/docs/docs/widgets/network-controller-summary/index.mdx +++ b/apps/docs/docs/widgets/network-controller-summary/index.mdx @@ -1,38 +1,38 @@ --- -title: 'Network Controller Summary' -description: 'Displays the summary of a Network Controller' +title: "Network Controller Summary" +description: "Displays the summary of a Network Controller" hide_title: true --- -import { unifiControllerIntegration } from '@site/docs/integrations/unifi-controller'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { unifiControllerIntegration } from "@site/docs/integrations/unifi-controller"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; -import { networkControllerSummaryWidget } from '.'; +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; +import { networkControllerSummaryWidget } from "."; - - + Shows information whether your WAN is connected, Wi-Fi is active and several other information. ### Screenshots -import summaryCard from './img/summary.png'; +import summaryCard from "./img/summary.png"; network-controller-summary ### Supported Integrations - + ### Adding the widget diff --git a/apps/docs/docs/widgets/notifications/index.mdx b/apps/docs/docs/widgets/notifications/index.mdx index 0a715ab3c..3ca096e3c 100644 --- a/apps/docs/docs/widgets/notifications/index.mdx +++ b/apps/docs/docs/widgets/notifications/index.mdx @@ -1,42 +1,35 @@ --- -title: 'Notifications' -description: 'Display notification history from an integration' +title: "Notifications" +description: "Display notification history from an integration" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { notificationsWidget } from '.'; -import { ntfyIntegration } from '@site/docs/integrations/ntfy'; -import { nextcloudIntegration } from '@site/docs/integrations/nextcloud'; -import { gotifyIntegration } from '@site/docs/integrations/gotify'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { notificationsWidget } from "."; +import { ntfyIntegration } from "@site/docs/integrations/ntfy"; +import { nextcloudIntegration } from "@site/docs/integrations/nextcloud"; +import { gotifyIntegration } from "@site/docs/integrations/gotify"; - + The notifications widget allows you to display notifications from various integrations in a unified view. ### Screenshots -import notificationsScreenshot from './img/notifications.png'; +import notificationsScreenshot from "./img/notifications.png"; notifications ### Supported Integrations ### Adding the widget diff --git a/apps/docs/docs/widgets/paperless-ngx/index.mdx b/apps/docs/docs/widgets/paperless-ngx/index.mdx index 3dd684efd..140d667c0 100644 --- a/apps/docs/docs/widgets/paperless-ngx/index.mdx +++ b/apps/docs/docs/widgets/paperless-ngx/index.mdx @@ -1,34 +1,35 @@ --- -title: 'Paperless-ngx' -description: 'Displays document management statistics including inbox ratio, document counts, and metadata.' +title: "Paperless-ngx" +description: "Displays document management statistics including inbox ratio, document counts, and metadata." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { paperlessNgxWidget } from '.'; -import { paperlessNgxIntegration } from '@site/docs/integrations/paperless-ngx'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { paperlessNgxWidget } from "."; +import { paperlessNgxIntegration } from "@site/docs/integrations/paperless-ngx"; - - + This widget displays statistics from your Paperless-ngx instance, including an inbox ratio ring showing how many documents are in your inbox versus total, along with counts for correspondents, tags, and document types. ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/patchmon/index.mdx b/apps/docs/docs/widgets/patchmon/index.mdx index d16ab8d68..cde2a0da5 100644 --- a/apps/docs/docs/widgets/patchmon/index.mdx +++ b/apps/docs/docs/widgets/patchmon/index.mdx @@ -1,21 +1,17 @@ --- -title: 'PatchMon' -description: 'Displays host patch statistics from PatchMon including update and security counts.' +title: "PatchMon" +description: "Displays host patch statistics from PatchMon including update and security counts." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { patchmonWidget } from '.'; -import { patchmonIntegration } from '@site/docs/integrations/patchmon'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { patchmonWidget } from "."; +import { patchmonIntegration } from "@site/docs/integrations/patchmon"; - - + This widget displays patch statistics from your PatchMon instance, including total hosts, hosts needing updates, and security update counts. Each stat is shown with a dedicated icon and severity-tinted card background for quick visual scanning. @@ -39,13 +35,13 @@ In **1-column-wide** layouts (such as 1×1), the compliance hero switches to a r When **Enable threshold colors** is on (default), stat values and card backgrounds are colored for at-a-glance severity: -| Stat | Green | Yellow | Red | -|------|-------|--------|-----| -| Needs Updates | 0 | 1–4 | 5+ | -| Security Updates | 0 | 1–9 | 10+ | -| Hosts with Security Updates | 0 | — | 1+ | -| Up-to-Date Hosts | 100% of total | 90–99% | below 90% | -| Outdated Packages | 0 | 1–49 | 50+ | +| Stat | Green | Yellow | Red | +| --------------------------- | ------------- | ------ | --------- | +| Needs Updates | 0 | 1–4 | 5+ | +| Security Updates | 0 | 1–9 | 10+ | +| Hosts with Security Updates | 0 | — | 1+ | +| Up-to-Date Hosts | 100% of total | 90–99% | below 90% | +| Outdated Packages | 0 | 1–49 | 50+ | Enable **Advanced thresholds** to override warning and critical values per stat, using either absolute counts or percentages of total hosts. @@ -62,13 +58,13 @@ The OS distribution limit defaults to **All**. A widget size of **2×3** or larg The widget adapts its layout based on the available space: -| Widget size | Layout | -|-------------|--------| -| **1×1** | Primary selected content: compliance ring (no label), compact OS distribution, or up to two enabled stats | +| Widget size | Layout | +| ----------------- | ------------------------------------------------------------------------------------------------------------------- | +| **1×1** | Primary selected content: compliance ring (no label), compact OS distribution, or up to two enabled stats | | **2×1** / **1×2** | Compact primary content; **2×1** shows compliance label and host ratio beside the ring; **1×2** uses ring-only hero | -| **2×2** (default) | Compliance hero, stat grid with icons, and tinted cards | -| **2×3** / **3×2** | Hero, stats, OS distribution, and "last updated" footer | -| **3×3** or larger | Full layout with up to 4-column stat grid, donut chart, and optional OS legend | +| **2×2** (default) | Compliance hero, stat grid with icons, and tinted cards | +| **2×3** / **3×2** | Hero, stats, OS distribution, and "last updated" footer | +| **3×3** or larger | Full layout with up to 4-column stat grid, donut chart, and optional OS legend | ### Last updated @@ -76,14 +72,19 @@ When the widget has enough space, a "last updated" timestamp appears at the bott ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/rss-feed/index.mdx b/apps/docs/docs/widgets/rss-feed/index.mdx index 68bbb1071..d4e0b2d74 100644 --- a/apps/docs/docs/widgets/rss-feed/index.mdx +++ b/apps/docs/docs/widgets/rss-feed/index.mdx @@ -1,25 +1,21 @@ --- -title: 'RSS Feed' -description: 'Monitor and display one or more generic RSS, ATOM or JSON feeds.' +title: "RSS Feed" +description: "Monitor and display one or more generic RSS, ATOM or JSON feeds." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { rssFeedWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { rssFeedWidget } from "."; - - + Using the RSS standard, you can integrate most News websites, applications and more on your dashboard. ### Screenshots -import screenshot from './img/screenshot.png'; +import screenshot from "./img/screenshot.png"; rss-feed noted-lol @@ -28,10 +24,13 @@ import screenshot from './img/screenshot.png'; ### Configuration + ### Examples + Here's a small collection of examples, that you can use for testing or actual use (in no particular order): + - https://noted.lol/rss/ - https://blog.google/products/chrome/rss/ - https://www.w3.org/blog/feed/ @@ -45,4 +44,4 @@ Here's a small collection of examples, that you can use for testing or actual us - http://feeds.foxnews.com/foxnews/latest There is a good list of feeds here: -https://github.com/greysonp/rss-feeds/blob/master/feeds.json \ No newline at end of file +https://github.com/greysonp/rss-feeds/blob/master/feeds.json diff --git a/apps/docs/docs/widgets/smart-home-entity-state/index.mdx b/apps/docs/docs/widgets/smart-home-entity-state/index.mdx index d101d6376..f01e4f0df 100644 --- a/apps/docs/docs/widgets/smart-home-entity-state/index.mdx +++ b/apps/docs/docs/widgets/smart-home-entity-state/index.mdx @@ -1,34 +1,30 @@ --- -title: 'Entity State' -description: 'Display the state of an entity and toggle it optionally' +title: "Entity State" +description: "Display the state of an entity and toggle it optionally" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { smartHomeEntityStateWidget } from '.'; -import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { smartHomeEntityStateWidget } from "."; +import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant"; - - + The entity state enables you to display the current state of an entity. -This works with most entities and enables you display almost any data. +This works with most entities and enables you display almost any data. It is recommended that you transform data on the integration as much as possible since Homarr's capabilities in transformation are very limited. ### Screenshots -import sun from './img/sun.png'; -import lightSwitch from './img/light-switch.png'; -import temperature from './img/temperature.png'; +import sun from "./img/sun.png"; +import lightSwitch from "./img/light-switch.png"; +import temperature from "./img/temperature.png"; smart-home-entity-state sun smart-home-entity-state light-switch @@ -36,9 +32,13 @@ import temperature from './img/temperature.png'; ### Supported Integrations - + ### Interactions @@ -49,19 +49,21 @@ import temperature from './img/temperature.png'; ### Configuration + ### How to find the entity ID To find the entity ID in Home Assistant, follow these steps: + 1. Open Home Assistant and go to the **Developer Tools** section (usually found in the sidebar). 2. Click on the **States** tab. 3. In the list of entities, find the entity you want to use. 4. The entity ID will be displayed in the format `domain.object_id` (e.g., `light.living_room_light`). 5. Copy the entity ID and paste it into the widget configuration in Homarr. It will then show the State that is visible in Home Assistant. -import retrieveEntityId from './img/retrieve-entity-id.png'; +import retrieveEntityId from "./img/retrieve-entity-id.png";
    homeassistant retrieve-entity-id -
    \ No newline at end of file +
    diff --git a/apps/docs/docs/widgets/smart-home-execute-automation/index.mdx b/apps/docs/docs/widgets/smart-home-execute-automation/index.mdx index 522c113ca..f31a79b93 100644 --- a/apps/docs/docs/widgets/smart-home-execute-automation/index.mdx +++ b/apps/docs/docs/widgets/smart-home-execute-automation/index.mdx @@ -1,42 +1,47 @@ --- -title: 'Execute Automation' -description: 'Trigger an automation with one click' +title: "Execute Automation" +description: "Trigger an automation with one click" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; import { IconAd } from "@tabler/icons-react"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import { smartHomeExecuteAutomationWidget } from '.'; -import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { smartHomeExecuteAutomationWidget } from "."; +import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant"; - - + The execute automation widget allows you to trigger an automation with one click. ### Screenshots -import empty from './img/empty.png'; -import withDisplayname from './img/with-displayname.png'; +import empty from "./img/empty.png"; +import withDisplayname from "./img/with-displayname.png";
    smart-home-execute-automation empty - smart-home-execute-automation with-displayname + smart-home-execute-automation with-displayname
    ### Supported Integrations - + ### Interactions @@ -47,4 +52,5 @@ import withDisplayname from './img/with-displayname.png'; ### Configuration + diff --git a/apps/docs/docs/widgets/speedtest-tracker/index.mdx b/apps/docs/docs/widgets/speedtest-tracker/index.mdx index 94be18dd7..4b0760e0a 100644 --- a/apps/docs/docs/widgets/speedtest-tracker/index.mdx +++ b/apps/docs/docs/widgets/speedtest-tracker/index.mdx @@ -1,39 +1,41 @@ --- -title: 'Speedtest Tracker' -description: 'Displays speed test results from your Speedtest Tracker instance.' +title: "Speedtest Tracker" +description: "Displays speed test results from your Speedtest Tracker instance." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { speedtestTrackerWidget } from '.'; -import { speedtestTrackerIntegration } from '@site/docs/integrations/speedtest-tracker'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { speedtestTrackerWidget } from "."; +import { speedtestTrackerIntegration } from "@site/docs/integrations/speedtest-tracker"; - + This widget displays internet speed test results from your [Speedtest Tracker](https://docs.speedtest-tracker.dev/) instance, including the latest result, historical averages, and a live chart of the last 12 hours. ### Screenshots -import screenshot from './img/screenshot.png'; +import screenshot from "./img/screenshot.png"; speedtest-tracker image ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/stock-price/index.mdx b/apps/docs/docs/widgets/stock-price/index.mdx index 5d9a24c64..dcd091be7 100644 --- a/apps/docs/docs/widgets/stock-price/index.mdx +++ b/apps/docs/docs/widgets/stock-price/index.mdx @@ -1,28 +1,24 @@ --- -title: 'Stock Price' -description: 'Displays the current stock price of a company.' +title: "Stock Price" +description: "Displays the current stock price of a company." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { stockPriceWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { stockPriceWidget } from "."; - - + Using the Stocks widget, you can show the current stock prices of your favorite companies on your dashboard. ### Screenshots -import apple from './img/apple.png'; -import google from './img/google.png'; -import ethereum from './img/ethereum.png'; -import nvidia from './img/nvidia.png'; +import apple from "./img/apple.png"; +import google from "./img/google.png"; +import ethereum from "./img/ethereum.png"; +import nvidia from "./img/nvidia.png";
    @@ -34,17 +30,19 @@ import nvidia from './img/nvidia.png';
    stock-price nvidia
    - ### Adding the widget ### Configuration + ### Examples + Here's a small collection of examples, that you can use for testing or actual use (in no particular order): + - AAPL - GOOGL - AMZN @@ -59,4 +57,4 @@ Here's a small collection of examples, that you can use for testing or actual us ### Data source We use the Yahoo Finance API to fetch the stock prices. -If you need to whitelist the api, please use the following URL: `https://query1.finance.yahoo.com` \ No newline at end of file +If you need to whitelist the api, please use the following URL: `https://query1.finance.yahoo.com` diff --git a/apps/docs/docs/widgets/system-disks/index.ts b/apps/docs/docs/widgets/system-disks/index.ts index 8dd68f057..ade53efc0 100644 --- a/apps/docs/docs/widgets/system-disks/index.ts +++ b/apps/docs/docs/widgets/system-disks/index.ts @@ -19,7 +19,11 @@ export const systemDisksWidget: WidgetDefinition = { description: "How disk usage values are shown", values: { type: "select", - options: ["Percentage (e.g., 76%)", "Absolute values (e.g., 800GB / 1TB)", "Free space percentage (e.g., 24% free)"], + options: [ + "Percentage (e.g., 76%)", + "Absolute values (e.g., 800GB / 1TB)", + "Free space percentage (e.g., 24% free)", + ], }, defaultValue: "Percentage (e.g., 76%)", }, diff --git a/apps/docs/docs/widgets/timetable/index.mdx b/apps/docs/docs/widgets/timetable/index.mdx index e9bdfd326..bea69cfb4 100644 --- a/apps/docs/docs/widgets/timetable/index.mdx +++ b/apps/docs/docs/widgets/timetable/index.mdx @@ -19,16 +19,8 @@ import trainDepartures from "./img/train-departures.png"; import streetDepartures from "./img/street-departures.png";
    - timetable-widget-train-departures - timetable-widget-bus-and-tram-departures + timetable-widget-train-departures + timetable-widget-bus-and-tram-departures
    ### Adding the widget diff --git a/apps/docs/docs/widgets/tracearr/index.mdx b/apps/docs/docs/widgets/tracearr/index.mdx index a579d8af3..797f83a3e 100644 --- a/apps/docs/docs/widgets/tracearr/index.mdx +++ b/apps/docs/docs/widgets/tracearr/index.mdx @@ -1,37 +1,33 @@ --- -title: 'Tracearr' -description: 'Monitor media server streams, user activity, and policy violations.' +title: "Tracearr" +description: "Monitor media server streams, user activity, and policy violations." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { tracearrWidget } from '.'; -import { tracearrIntegration } from '@site/docs/integrations/tracearr'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { tracearrWidget } from "."; +import { tracearrIntegration } from "@site/docs/integrations/tracearr"; - - + The Tracearr widget provides a real-time monitoring dashboard for your media server activity. It displays active streams, user statistics, recent watching history, and policy violations. ### Sections -| Section | Description | -|---|---| -| **Stats Bar** | Displays Active Streams, Total Users, Transcode Count, and Total Bandwidth at a glance. | -| **Active Streams** | Shows currently playing media with poster art, user info, progress bar, resolution, and transcoding status (Direct Play or Transcode). | -| **Recent Activity** | A paginated list of watching history with user avatars and watched status. | -| **Violations** | Alerts for policy violations (e.g., concurrent stream limits) with severity levels. | +| Section | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| **Stats Bar** | Displays Active Streams, Total Users, Transcode Count, and Total Bandwidth at a glance. | +| **Active Streams** | Shows currently playing media with poster art, user info, progress bar, resolution, and transcoding status (Direct Play or Transcode). | +| **Recent Activity** | A paginated list of watching history with user avatars and watched status. | +| **Violations** | Alerts for policy violations (e.g., concurrent stream limits) with severity levels. | ### Screenshots -import widgetOverview from './img/widget-overview.png'; -import streamsAndStats from './img/streams-and-stats.png'; +import widgetOverview from "./img/widget-overview.png"; +import streamsAndStats from "./img/streams-and-stats.png";
    tracearr-widget-overview @@ -44,9 +40,14 @@ import streamsAndStats from './img/streams-and-stats.png'; ### Supported Integrations - + ### Configuration + diff --git a/apps/docs/docs/widgets/umami/index.mdx b/apps/docs/docs/widgets/umami/index.mdx index 0d0006054..b208a3311 100644 --- a/apps/docs/docs/widgets/umami/index.mdx +++ b/apps/docs/docs/widgets/umami/index.mdx @@ -1,28 +1,29 @@ --- -title: 'Umami Analytics' -description: 'Display visitor stats from your Umami analytics instance' +title: "Umami Analytics" +description: "Display visitor stats from your Umami analytics instance" hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { umamiWidget } from '.'; -import { umamiIntegration } from '@site/docs/integrations/umami'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { umamiWidget } from "."; +import { umamiIntegration } from "@site/docs/integrations/umami"; - + The Umami Analytics widget displays key visitor metrics from a website tracked by your [Umami](https://umami.is) instance - pageviews, unique visitors, visits, bounce rate, avg. visit duration, and real-time active visitor count. The widget body can be switched between a visitor/event chart, a multi-event chart, and ranked top pages or referrers lists. ### Supported Integrations - + ### Adding the widget @@ -34,12 +35,12 @@ The Umami Analytics widget displays key visitor metrics from a website tracked b ### View modes -| View | Description | -|---|---| -| **Chart** | Bar chart or sparkline of unique visitors over the selected time frame. Optionally overlay a single named event as a second series. | -| **Events chart** | Multi-select one or more named events and chart each as its own colored series - no visitor baseline. Supports bar and sparkline. | -| **Top pages** | Ranked list of URLs by pageview count for the selected time frame. | -| **Top referrers** | Ranked list of referrer sources by session count. Direct traffic (no referrer) is labeled "Direct". | +| View | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Chart** | Bar chart or sparkline of unique visitors over the selected time frame. Optionally overlay a single named event as a second series. | +| **Events chart** | Multi-select one or more named events and chart each as its own colored series - no visitor baseline. Supports bar and sparkline. | +| **Top pages** | Ranked list of URLs by pageview count for the selected time frame. | +| **Top referrers** | Ranked list of referrer sources by session count. Direct traffic (no referrer) is labeled "Direct". | ### Notes diff --git a/apps/docs/docs/widgets/ups/index.mdx b/apps/docs/docs/widgets/ups/index.mdx index bf512990d..3e57ee57b 100644 --- a/apps/docs/docs/widgets/ups/index.mdx +++ b/apps/docs/docs/widgets/ups/index.mdx @@ -1,20 +1,17 @@ --- -title: 'UPS' -description: 'Monitor the status of your UPS devices through a NUT server.' +title: "UPS" +description: "Monitor the status of your UPS devices through a NUT server." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { upsWidget } from '.'; -import { peaNutIntegration } from '@site/docs/integrations/peanut'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { upsWidget } from "."; +import { peaNutIntegration } from "@site/docs/integrations/peanut"; - + This widget displays the status of the UPS devices reported by a Network UPS Tools (NUT) server. Each device shows its status (online, on battery, charging or low battery), battery charge and estimated runtime, output load, and input and @@ -22,27 +19,32 @@ output voltage. ### Layouts -import screenshotFull from './img/screenshot.png'; -import screenshotCompact from './img/screenshot-compact.png'; -import screenshotMini from './img/screenshot-mini.png'; +import screenshotFull from "./img/screenshot.png"; +import screenshotCompact from "./img/screenshot-compact.png"; +import screenshotMini from "./img/screenshot-mini.png"; The widget adapts to the size of the tile, so it stays readable from a full dashboard panel down to a single cell. Multiple UPS devices scroll within the widget at any height. -| Layout | Size | Preview | -| --- | --- | --- | -| Full | 3+ columns wide | UPS widget full layout | -| Compact | ~2 columns | UPS widget compact layout | -| Mini | 1 column | UPS widget mini layout | +| Layout | Size | Preview | +| ------- | --------------- | --------------------------------------------------------------------------- | +| Full | 3+ columns wide | UPS widget full layout | +| Compact | ~2 columns | UPS widget compact layout | +| Mini | 1 column | UPS widget mini layout | ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/uptime-kuma/index.mdx b/apps/docs/docs/widgets/uptime-kuma/index.mdx index 3a6592b2e..0a7e649e8 100644 --- a/apps/docs/docs/widgets/uptime-kuma/index.mdx +++ b/apps/docs/docs/widgets/uptime-kuma/index.mdx @@ -1,34 +1,35 @@ --- -title: 'Uptime Kuma' -description: 'Displays monitor uptime statistics, average uptime percentage, and service status counts.' +title: "Uptime Kuma" +description: "Displays monitor uptime statistics, average uptime percentage, and service status counts." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { uptimeKumaWidget } from '.'; -import { uptimeKumaIntegration } from '@site/docs/integrations/uptime-kuma'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { uptimeKumaWidget } from "."; +import { uptimeKumaIntegration } from "@site/docs/integrations/uptime-kuma"; - - + This widget displays uptime statistics from your Uptime Kuma status page, including a visual uptime ring, average uptime percentage, and per-status monitor counts. ### Supported Integrations - + ### Adding the widget ### Configuration + diff --git a/apps/docs/docs/widgets/video/index.mdx b/apps/docs/docs/widgets/video/index.mdx index 3ccf3760a..e5225a022 100644 --- a/apps/docs/docs/widgets/video/index.mdx +++ b/apps/docs/docs/widgets/video/index.mdx @@ -1,19 +1,15 @@ --- -title: 'Video Stream' -description: 'Embed a video stream or video from a camera or a website.' +title: "Video Stream" +description: "Embed a video stream or video from a camera or a website." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { videoWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { videoWidget } from "."; - - + Do you run surveilance cameras? Or maybe you have a favourite video? The video widget enables you to integrate both seamlessly into your dashboard. @@ -22,7 +18,6 @@ This widget uses [video.js](https://videojs.com/) to play HLS or DASH video nati DRM content is not yet supported. More info here: https://videojs.com/guides/faqs/#q-what-is-videojs - You can use the following URL to test: http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4 @@ -35,4 +30,5 @@ http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp ### Configuration + diff --git a/apps/docs/docs/widgets/vpn/index.mdx b/apps/docs/docs/widgets/vpn/index.mdx index 0aa6a1a16..0c774a7b0 100644 --- a/apps/docs/docs/widgets/vpn/index.mdx +++ b/apps/docs/docs/widgets/vpn/index.mdx @@ -1,19 +1,16 @@ --- -title: 'VPN' -description: 'Monitor the status of your VPN integrations.' +title: "VPN" +description: "Monitor the status of your VPN integrations." hide_title: true --- -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetIntegrations } from '@site/src/components/widgets/integrations'; -import { vpnWidget } from '.'; -import { gluetunIntegration } from '@site/docs/integrations/gluetun'; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetIntegrations } from "@site/src/components/widgets/integrations"; +import { vpnWidget } from "."; +import { gluetunIntegration } from "@site/docs/integrations/gluetun"; - + The VPN widget provides a compact overview of each configured VPN integration. It shows whether the tunnel and DNS services are up, the currently exposed public IP address, and the VPN provider and protocol being used. @@ -23,7 +20,7 @@ current status at a glance. ### Screenshots -import singleIntegrationImage from './img/single.png'; +import singleIntegrationImage from "./img/single.png";
    VPN widget showing a single integration @@ -31,9 +28,13 @@ import singleIntegrationImage from './img/single.png'; ### Supported Integrations - + ### Adding the widget diff --git a/apps/docs/docs/widgets/weather/index.mdx b/apps/docs/docs/widgets/weather/index.mdx index 0ff4081d7..05b918785 100644 --- a/apps/docs/docs/widgets/weather/index.mdx +++ b/apps/docs/docs/widgets/weather/index.mdx @@ -1,26 +1,22 @@ --- -title: 'Weather' -description: 'Displays the current weather information of a set location.' +title: "Weather" +description: "Displays the current weather information of a set location." hide_title: true --- -import { AddingWidget } from '@site/src/components/widgets/adding'; -import { WidgetConfig } from '@site/src/components/widgets/configuration'; -import { WidgetHeader } from '@site/src/components/widgets/header'; -import { weatherWidget } from '.'; +import { AddingWidget } from "@site/src/components/widgets/adding"; +import { WidgetConfig } from "@site/src/components/widgets/configuration"; +import { WidgetHeader } from "@site/src/components/widgets/header"; +import { weatherWidget } from "."; - - + The Weather Widget uses your location to display the current, highest and lowest temperature. ### Screenshots -import forecastWeather from './img/forecast.png'; -import currentWeather from './img/current.png'; +import forecastWeather from "./img/forecast.png"; +import currentWeather from "./img/current.png";
    weather forecast-5-days @@ -32,9 +28,10 @@ import currentWeather from './img/current.png'; ### Configuration + ### Data source We use the Open Meteo API to fetch the weather and locations. -If you need to whitelist the api, please use the following URL: `https://open-meteo.com` \ No newline at end of file +If you need to whitelist the api, please use the following URL: `https://open-meteo.com` diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts index 62384c741..2995580ee 100644 --- a/apps/docs/docusaurus.config.ts +++ b/apps/docs/docusaurus.config.ts @@ -12,6 +12,9 @@ const config: Config = { favicon: "img/logo.png", organizationName: "homarr-labs", projectName: "homarr", + customFields: { + workshopUrl: process.env.WORKSHOP_URL ?? "", + }, i18n: { defaultLocale: "en", locales: ["en"], @@ -20,11 +23,6 @@ const config: Config = { onBrokenAnchors: "throw", onDuplicateRoutes: "throw", - customFields: { - // Empty means same-origin, which is the production Workshop image shape. - workshopUrl: process.env.WORKSHOP_URL ?? "", - }, - future: { v4: { removeLegacyPostBuildHeadAttribute: true, @@ -287,12 +285,21 @@ const config: Config = { function homarrPackagesPlugin() { return { name: "resolve-homarr-packages", - configureWebpack() { + configureWebpack(_config, isServer, { getJSLoader }) { return { resolve: { symlinks: false, alias: { "@": require("path").resolve(__dirname, "src") }, }, + module: { + rules: [ + { + test: /\.[jt]sx?$/iu, + include: /node_modules[\\/]@homarr/u, + use: [getJSLoader({ isServer })], + }, + ], + }, }; }, }; @@ -324,19 +331,18 @@ const config: Config = { }, }; }, - function workshopDetailRoutePlugin() { + function workshopRoutesPlugin() { return { - name: "workshop-detail-route", + name: "workshop-routes", async contentLoaded({ actions }) { actions.addRoute({ path: "/workshop/:id", - component: "@site/src/components/workshop/DetailPage", + component: "@site/src/components/workshop/WorkshopDetailRoutePage", exact: true, }); }, }; }, - "@signalwire/docusaurus-plugin-llms-txt", async function tailwindCssPlugin() { return { name: "docusaurus-tailwindcss", diff --git a/apps/docs/package.json b/apps/docs/package.json index b5b359b80..eed994a7a 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -21,20 +21,22 @@ "verify:search": "node ./scripts/verify-algolia-search.mjs" }, "dependencies": { - "@base-ui/react": "catalog:", + "@base-ui/react": "^1.5.0", "@docusaurus/core": "^3.10.1", "@docusaurus/faster": "^3.10.1", "@docusaurus/plugin-content-docs": "^3.10.1", "@docusaurus/plugin-sitemap": "^3.10.1", "@docusaurus/preset-classic": "^3.10.1", + "@homarr/custom-widgets": "workspace:^", "@homarr/definitions": "workspace:^", + "@homarr/workshop": "workspace:^", + "@mantine/core": "catalog:", "@mdx-js/react": "^3.1.1", "@nivo/line": "^0.99.0", "@scalar/api-reference-react": "catalog:", - "@signalwire/docusaurus-plugin-llms-txt": "^1.2.2", "@tabler/icons-react": "catalog:", "@tailwindcss/postcss": "^4.3.2", - "class-variance-authority": "catalog:", + "class-variance-authority": "^0.7.1", "clsx": "catalog:", "dayjs": "catalog:", "docusaurus-plugin-image-zoom": "^3.0.1", @@ -46,10 +48,9 @@ "random-word-slugs": "^0.1.7", "react": "catalog:", "react-dom": "catalog:", - "swiper": "^14.0.2", - "tailwind-merge": "catalog:", - "tailwindcss": "^4.3.2", - "zod": "catalog:" + "swiper": "^14.0.5", + "tailwind-merge": "^3.6.0", + "tailwindcss": "^4.3.2" }, "devDependencies": { "@docusaurus/module-type-aliases": "^3.10.1", @@ -60,7 +61,8 @@ "@types/react": "catalog:", "@types/react-dom": "catalog:", "cheerio": "^1.2.0", - "typescript": "catalog:" + "typescript": "catalog:", + "zod": "catalog:" }, "peerDependencies": { "@docusaurus/theme-common": "^3.10.1", diff --git a/apps/docs/scripts/dump-contributors.mjs b/apps/docs/scripts/dump-contributors.mjs index f2cd60fb4..b16057c99 100644 --- a/apps/docs/scripts/dump-contributors.mjs +++ b/apps/docs/scripts/dump-contributors.mjs @@ -1,14 +1,14 @@ -import { z } from 'zod'; -import fs from 'fs/promises'; +import { z } from "zod"; +import fs from "fs/promises"; const sources = { crowdin: [ - { projectId: 534422, tokenName: 'HOMARR_CROWDIN_TOKEN' }, - { projectId: 742587, tokenName: 'HOMARR_LABS_CROWDIN_TOKEN' }, + { projectId: 534422, tokenName: "HOMARR_CROWDIN_TOKEN" }, + { projectId: 742587, tokenName: "HOMARR_LABS_CROWDIN_TOKEN" }, ], github: [ - { repository: 'homarr', slug: 'ajnart' }, - { repository: 'homarr', slug: 'homarr-labs' }, + { repository: "homarr", slug: "ajnart" }, + { repository: "homarr", slug: "homarr-labs" }, ], }; @@ -23,11 +23,11 @@ const env = schema.parse(process.env); const fetchGithubContributors = async (slug, repository) => { const url = `https://api.github.com/repos/${slug}/${repository}/contributors?per_page=999`; const options = { - method: 'GET', + method: "GET", headers: { Authorization: `Bearer ${env.GITHUB_TOKEN}`, - Accept: 'application/vnd.github+json', - 'X-GitHub-Api-Version': '2022-11-28', + Accept: "application/vnd.github+json", + "X-GitHub-Api-Version": "2022-11-28", }, }; @@ -39,7 +39,7 @@ const fetchGithubContributors = async (slug, repository) => { login: z.string(), avatar_url: z.string().url(), contributions: z.number(), - }) + }), ); return dataSchema.parse(data); @@ -48,9 +48,9 @@ const fetchGithubContributors = async (slug, repository) => { const fetchCrowdinMembers = async (projectId, tokenName) => { const url = `https://crowdin.com/api/v2/projects/${projectId}/members`; const options = { - method: 'GET', + method: "GET", headers: { - Accept: 'application/json', + Accept: "application/json", Authorization: `Bearer ${env[tokenName]}`, }, }; @@ -65,7 +65,7 @@ const fetchCrowdinMembers = async (projectId, tokenName) => { username: z.string(), avatarUrl: z.string().url(), }), - }) + }), ), }); @@ -88,16 +88,11 @@ const distinctGithubContributors = githubContributors .filter(distinctBy((contributor) => contributor.login)) .sort((a, b) => b.contributions - a.contributions) .map(({ contributions, ...props }) => props) - .filter((contributor) => !contributor.login.includes('[bot]')); -await fs.writeFile('./static/data/contributions.json', JSON.stringify(distinctGithubContributors)); + .filter((contributor) => !contributor.login.includes("[bot]")); +await fs.writeFile("./static/data/contributions.json", JSON.stringify(distinctGithubContributors)); for (const { projectId, tokenName } of sources.crowdin) { crowdinContributors.push(...(await fetchCrowdinMembers(projectId, tokenName))); } -const distinctCrowdinContributors = crowdinContributors.filter( - distinctBy((contributor) => contributor.username) -); -await fs.writeFile( - './static/data/translation-contributions.json', - JSON.stringify(distinctCrowdinContributors) -); +const distinctCrowdinContributors = crowdinContributors.filter(distinctBy((contributor) => contributor.username)); +await fs.writeFile("./static/data/translation-contributions.json", JSON.stringify(distinctCrowdinContributors)); diff --git a/apps/docs/scripts/verify-algolia-search.mjs b/apps/docs/scripts/verify-algolia-search.mjs index 4aa5e30e7..93e83baa8 100644 --- a/apps/docs/scripts/verify-algolia-search.mjs +++ b/apps/docs/scripts/verify-algolia-search.mjs @@ -1,41 +1,32 @@ -const APP_ID = 'N69WSPZTID'; -const API_KEY = 'b2b00f4ed8ca3dc87b5d211c55121416'; -const DOCSEARCH_INDEX = 'Docusaurus'; -const MARKDOWN_INDEX = 'markdown'; +const APP_ID = "N69WSPZTID"; +const API_KEY = "b2b00f4ed8ca3dc87b5d211c55121416"; +const DOCSEARCH_INDEX = "Docusaurus"; +const MARKDOWN_INDEX = "markdown"; const MIN_DOCSEARCH_HITS = 100; const MIN_MARKDOWN_HITS = 10; -const DOCSEARCH_FACETS = [ - 'docusaurus_tag', - 'language', - 'lang', - 'version', - 'type', -]; +const DOCSEARCH_FACETS = ["docusaurus_tag", "language", "lang", "version", "type"]; const SEARCH_CASES = [ - { term: 'docker', minHits: 1 }, - { term: 'coolify', minHits: 1 }, - { term: 'jellyseerr', minHits: 1 }, - { term: 'keyboard shortcuts', minHits: 1 }, - { term: 'version 0.12', minHits: 1 }, + { term: "docker", minHits: 1 }, + { term: "coolify", minHits: 1 }, + { term: "jellyseerr", minHits: 1 }, + { term: "keyboard shortcuts", minHits: 1 }, + { term: "version 0.12", minHits: 1 }, ]; const STALE_URL_PATTERN = /\/docs\/(next|\d+(?:\.\d+)+)\//; async function algoliaQuery(index, body) { - const response = await fetch( - `https://${APP_ID}-dsn.algolia.net/1/indexes/${index}/query`, - { - method: 'POST', - headers: { - 'X-Algolia-Application-Id': APP_ID, - 'X-Algolia-API-Key': API_KEY, - 'Content-Type': 'application/json', - }, - body: JSON.stringify(body), + const response = await fetch(`https://${APP_ID}-dsn.algolia.net/1/indexes/${index}/query`, { + method: "POST", + headers: { + "X-Algolia-Application-Id": APP_ID, + "X-Algolia-API-Key": API_KEY, + "Content-Type": "application/json", }, - ); + body: JSON.stringify(body), + }); if (!response.ok) { throw new Error(`Algolia query on "${index}" failed: HTTP ${response.status}`); @@ -45,7 +36,7 @@ async function algoliaQuery(index, body) { } function reportLine(ok, message) { - const prefix = ok ? 'OK' : 'FAIL'; + const prefix = ok ? "OK" : "FAIL"; console.log(`${prefix}: ${message}`); return ok; } @@ -54,14 +45,14 @@ async function resolveDocsearchIndex() { const candidates = [DOCSEARCH_INDEX, `${DOCSEARCH_INDEX}.tmp`]; for (const index of candidates) { - const result = await algoliaQuery(index, { query: '', hitsPerPage: 0 }); + const result = await algoliaQuery(index, { query: "", hitsPerPage: 0 }); const hitCount = result.nbHits ?? 0; if (hitCount >= MIN_DOCSEARCH_HITS) { return { index, hitCount }; } } - const fallback = await algoliaQuery(DOCSEARCH_INDEX, { query: '', hitsPerPage: 0 }); + const fallback = await algoliaQuery(DOCSEARCH_INDEX, { query: "", hitsPerPage: 0 }); return { index: DOCSEARCH_INDEX, hitCount: fallback.nbHits ?? 0 }; } @@ -69,14 +60,14 @@ async function resolveMarkdownIndex() { const candidates = [MARKDOWN_INDEX, `${MARKDOWN_INDEX}.tmp`]; for (const index of candidates) { - const result = await algoliaQuery(index, { query: '', hitsPerPage: 0 }); + const result = await algoliaQuery(index, { query: "", hitsPerPage: 0 }); const hitCount = result.nbHits ?? 0; if (hitCount >= MIN_MARKDOWN_HITS) { return { index, hitCount }; } } - const fallback = await algoliaQuery(MARKDOWN_INDEX, { query: '', hitsPerPage: 0 }); + const fallback = await algoliaQuery(MARKDOWN_INDEX, { query: "", hitsPerPage: 0 }); return { index: MARKDOWN_INDEX, hitCount: fallback.nbHits ?? 0 }; } @@ -87,13 +78,13 @@ async function verifyDocsearchIndex(index, hitCount) { ); const sample = await algoliaQuery(index, { - query: 'docker', + query: "docker", hitsPerPage: 1, attributesToRetrieve: DOCSEARCH_FACETS, }); const record = sample.hits?.[0] ?? {}; - const recordFields = ['docusaurus_tag', 'language', 'lang', 'version', 'type']; + const recordFields = ["docusaurus_tag", "language", "lang", "version", "type"]; for (const field of recordFields) { const present = record[field] !== undefined && record[field] !== null; ok = reportLine(present, `records include "${field}"`) && ok; @@ -103,7 +94,7 @@ async function verifyDocsearchIndex(index, hitCount) { const result = await algoliaQuery(index, { query: searchCase.term, hitsPerPage: 5, - attributesToRetrieve: ['url'], + attributesToRetrieve: ["url"], }); const caseHits = result.nbHits ?? 0; @@ -113,9 +104,7 @@ async function verifyDocsearchIndex(index, hitCount) { `"${searchCase.term}" returns ${caseHits} hits (need >= ${searchCase.minHits})`, ) && ok; - const staleUrls = (result.hits ?? []) - .map((hit) => hit.url) - .filter((url) => STALE_URL_PATTERN.test(url)); + const staleUrls = (result.hits ?? []).map((hit) => hit.url).filter((url) => STALE_URL_PATTERN.test(url)); ok = reportLine( @@ -134,51 +123,39 @@ async function verifyMarkdownIndex(index, hitCount) { ); const coolify = await algoliaQuery(index, { - query: 'coolify', + query: "coolify", hitsPerPage: 3, - attributesToRetrieve: ['url', 'title', 'heading', 'text'], + attributesToRetrieve: ["url", "title", "heading", "text"], }); ok = - reportLine( - (coolify.nbHits ?? 0) >= 1, - `markdown index "${index}" returns coolify (${coolify.nbHits ?? 0} hits)`, - ) && ok; + reportLine((coolify.nbHits ?? 0) >= 1, `markdown index "${index}" returns coolify (${coolify.nbHits ?? 0} hits)`) && + ok; const sample = coolify.hits?.[0]; - ok = - reportLine( - Boolean(sample?.text?.length), - `markdown records include chunked text content`, - ) && ok; + ok = reportLine(Boolean(sample?.text?.length), `markdown records include chunked text content`) && ok; return ok; } async function main() { - console.log('Verifying Algolia DocSearch + markdown indices...\n'); + console.log("Verifying Algolia DocSearch + markdown indices...\n"); const docsearch = await resolveDocsearchIndex(); console.log(`Using DocSearch index: ${docsearch.index}\n`); - const docsearchOk = await verifyDocsearchIndex( - docsearch.index, - docsearch.hitCount, - ); + const docsearchOk = await verifyDocsearchIndex(docsearch.index, docsearch.hitCount); - console.log(''); + console.log(""); const markdown = await resolveMarkdownIndex(); console.log(`Using markdown index: ${markdown.index}\n`); - const markdownOk = await verifyMarkdownIndex( - markdown.index, - markdown.hitCount, - ); + const markdownOk = await verifyMarkdownIndex(markdown.index, markdown.hitCount); const allOk = docsearchOk && markdownOk; - console.log(''); + console.log(""); console.log( allOk - ? 'All checks passed.' - : 'Some checks failed — ensure the crawler config in docsearch.config.js is applied and a full recrawl has finished.', + ? "All checks passed." + : "Some checks failed — ensure the crawler config in docsearch.config.js is applied and a full recrawl has finished.", ); process.exit(allOk ? 0 : 1); } diff --git a/apps/docs/src/components/custom-jsx-component-reference.module.css b/apps/docs/src/components/custom-jsx-component-reference.module.css new file mode 100644 index 000000000..66fe6bff0 --- /dev/null +++ b/apps/docs/src/components/custom-jsx-component-reference.module.css @@ -0,0 +1,451 @@ +.explorer { + --catalog-border: color-mix(in srgb, var(--ifm-color-emphasis-500) 42%, transparent); + --catalog-surface: color-mix(in srgb, var(--ifm-background-surface-color) 90%, var(--ifm-color-primary) 10%); + border: 1px solid var(--catalog-border); + border-radius: 18px; + margin: 1.5rem 0 2rem; + overflow: hidden; +} + +.header { + align-items: flex-start; + background: linear-gradient(135deg, color-mix(in srgb, var(--ifm-color-primary) 13%, transparent), transparent 65%); + display: flex; + gap: 1.5rem; + justify-content: space-between; + padding: 1.4rem; +} + +.eyebrow { + color: var(--ifm-color-primary); + font-size: 0.72rem; + font-weight: 750; + letter-spacing: 0.09em; + margin: 0 0 0.35rem; + text-transform: uppercase; +} + +.title { + font-size: clamp(1.25rem, 3vw, 1.65rem); + margin: 0; +} + +.summary { + color: var(--ifm-color-emphasis-700); + margin: 0.45rem 0 0; + max-width: 68ch; +} + +.rawLink, +.expandButton, +.showMoreButton, +.resetButton { + align-items: center; + border-radius: 9px; + cursor: pointer; + display: inline-flex; + font: inherit; + font-weight: 650; + justify-content: center; +} + +.rawLink, +.expandButton, +.showMoreButton { + background: var(--ifm-color-primary); + border: 1px solid var(--ifm-color-primary); + color: var(--ifm-color-white); + padding: 0.58rem 0.85rem; + text-decoration: none; +} + +.rawLink { + flex: 0 0 auto; + white-space: nowrap; +} + +.rawLink:hover, +.expandButton:hover, +.showMoreButton:hover { + background: var(--ifm-color-primary-dark); + color: var(--ifm-color-white); + text-decoration: none; +} + +.versions { + border-bottom: 1px solid var(--catalog-border); + border-top: 1px solid var(--catalog-border); + display: grid; + grid-template-columns: repeat(4, minmax(0, 1fr)); + margin: 0; +} + +.globalProps { + align-items: center; + border-bottom: 1px solid var(--catalog-border); + display: grid; + gap: 1rem; + grid-template-columns: minmax(0, 1fr) auto; + padding: 1rem 1.4rem; + scroll-margin-top: calc(var(--ifm-navbar-height) + 1rem); +} + +.globalProps h4, +.globalProps p { + margin: 0; +} + +.globalProps p { + color: var(--ifm-color-emphasis-700); + font-size: 0.86rem; + margin-top: 0.2rem; +} + +.globalPropsTable { + grid-column: 1 / -1; +} + +.versions div { + padding: 0.75rem 1.4rem; +} + +.versions div + div { + border-left: 1px solid var(--catalog-border); +} + +.versions dt { + color: var(--ifm-color-emphasis-700); + font-size: 0.72rem; + font-weight: 650; + text-transform: uppercase; +} + +.versions dd { + font-family: var(--ifm-font-family-monospace); + font-size: 0.86rem; + margin: 0.12rem 0 0; +} + +.filters { + align-items: end; + background: var(--catalog-surface); + display: grid; + gap: 0.8rem; + grid-template-columns: minmax(220px, 2fr) repeat(3, minmax(130px, 1fr)); + padding: 1.15rem 1.4rem; +} + +.filters label:not(.checkboxField) { + display: grid; + gap: 0.3rem; +} + +.filters label > span { + color: var(--ifm-color-emphasis-700); + font-size: 0.76rem; + font-weight: 700; +} + +.filters input[type="search"], +.filters select { + background: var(--ifm-background-color); + border: 1px solid var(--catalog-border); + border-radius: 9px; + color: var(--ifm-font-color-base); + font: inherit; + min-height: 42px; + padding: 0.55rem 0.68rem; + width: 100%; +} + +.filters input:focus-visible, +.filters select:focus-visible, +.expandButton:focus-visible, +.showMoreButton:focus-visible, +.resetButton:focus-visible, +.anchorLink:focus-visible { + outline: 3px solid color-mix(in srgb, var(--ifm-color-primary) 45%, transparent); + outline-offset: 2px; +} + +.checkboxField { + align-items: center; + display: flex; + gap: 0.5rem; + grid-column: 1 / -1; +} + +.checkboxField input { + height: 1rem; + margin: 0; + width: 1rem; +} + +.resultSummary { + align-items: center; + border-bottom: 1px solid var(--catalog-border); + display: flex; + gap: 0.6rem; + min-height: 48px; + padding: 0.7rem 1.4rem; +} + +.resetButton { + background: transparent; + border: 0; + color: var(--ifm-color-primary); + margin-left: auto; + padding: 0.35rem; +} + +.componentList { + display: grid; +} + +.componentCard { + scroll-margin-top: calc(var(--ifm-navbar-height) + 1rem); +} + +.componentCard + .componentCard { + border-top: 1px solid var(--catalog-border); +} + +.componentHeading { + align-items: center; + display: flex; + gap: 1rem; + justify-content: space-between; + padding: 1rem 1.4rem; +} + +.componentNameRow { + align-items: baseline; + display: flex; + gap: 0.45rem; +} + +.componentNameRow h4 { + font-family: var(--ifm-font-family-monospace); + font-size: 1.05rem; + margin: 0; +} + +.anchorLink { + font-weight: 700; + opacity: 0; + text-decoration: none; +} + +.componentCard:hover .anchorLink, +.anchorLink:focus-visible { + opacity: 1; +} + +.badges { + display: flex; + flex-wrap: wrap; + gap: 0.38rem; + margin-top: 0.45rem; +} + +.badges span { + background: var(--ifm-color-emphasis-200); + border-radius: 999px; + color: var(--ifm-color-emphasis-800); + font-size: 0.7rem; + padding: 0.2rem 0.48rem; +} + +.badges span[data-safety="allowed"] { + background: color-mix(in srgb, #2f9e44 18%, transparent); + color: color-mix(in srgb, #2f9e44 78%, var(--ifm-font-color-base)); +} + +.badges span[data-safety="wrapped"] { + background: color-mix(in srgb, var(--ifm-color-primary) 18%, transparent); + color: var(--ifm-color-primary-darkest); +} + +.badges span[data-safety="denied"] { + background: color-mix(in srgb, #e03131 18%, transparent); + color: color-mix(in srgb, #e03131 78%, var(--ifm-font-color-base)); +} + +.expandButton { + background: transparent; + color: var(--ifm-color-primary); + flex: 0 0 auto; + padding: 0.42rem 0.7rem; +} + +.expandButton:hover { + background: color-mix(in srgb, var(--ifm-color-primary) 12%, transparent); + color: var(--ifm-color-primary-dark); +} + +.description, +.deniedReason { + color: var(--ifm-color-emphasis-700); + margin: -0.45rem 1.4rem 1rem; +} + +.deniedReason { + color: #c92a2a; +} + +.details { + background: var(--catalog-surface); + border-top: 1px solid var(--catalog-border); + padding: 1.25rem 1.4rem; +} + +.details h5 { + font-size: 0.9rem; + margin: 0 0 0.6rem; +} + +.detailsGrid { + display: grid; + gap: 1rem; + grid-template-columns: minmax(0, 1.15fr) minmax(0, 0.85fr); + margin-bottom: 1.2rem; +} + +.detailsGrid > section { + background: var(--ifm-background-color); + border: 1px solid var(--catalog-border); + border-radius: 12px; + min-width: 0; + padding: 0.9rem; +} + +.detailsGrid p:last-of-type { + margin-bottom: 0.6rem; +} + +.a11yList { + font-size: 0.86rem; + margin: 0 0 0.7rem; + padding-left: 1.1rem; +} + +.tableScroll { + border: 1px solid var(--catalog-border); + border-radius: 10px; + max-height: 480px; + overflow: auto; +} + +.propsTable { + display: table; + font-size: 0.78rem; + margin: 0; + width: 100%; +} + +.propsTable th { + background: var(--ifm-background-color); + position: sticky; + top: 0; + z-index: 1; +} + +.propsTable th, +.propsTable td { + min-width: 96px; + padding: 0.58rem; + vertical-align: top; +} + +.propsTable td:nth-child(2) { + max-width: 340px; + min-width: 190px; +} + +.type { + overflow-wrap: anywhere; + white-space: normal; +} + +.muted { + color: var(--ifm-color-emphasis-600); +} + +.rawComponent { + margin-top: 1rem; +} + +.rawComponent summary { + color: var(--ifm-color-primary); + cursor: pointer; + font-weight: 650; +} + +.rawComponent > div { + margin-top: 0.6rem; +} + +.showMoreButton { + display: flex; + margin: 1.1rem auto; +} + +.loading, +.error, +.empty { + background: var(--ifm-background-surface-color); + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: 12px; + margin: 1rem 0; + padding: 1rem; +} + +.empty { + border: 0; + margin: 0; + text-align: center; +} + +.error { + border-color: color-mix(in srgb, #e03131 58%, transparent); +} + +@media (max-width: 996px) { + .filters { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + + .searchField { + grid-column: 1 / -1; + } +} + +@media (max-width: 650px) { + .header, + .componentHeading { + align-items: stretch; + flex-direction: column; + } + + .rawLink, + .expandButton { + align-self: flex-start; + } + + .versions, + .filters, + .detailsGrid, + .globalProps { + grid-template-columns: 1fr; + } + + .versions div + div { + border-left: 0; + border-top: 1px solid var(--catalog-border); + } + + .searchField, + .checkboxField { + grid-column: auto; + } +} diff --git a/apps/docs/src/components/custom-jsx-component-reference.tsx b/apps/docs/src/components/custom-jsx-component-reference.tsx new file mode 100644 index 000000000..23c028787 --- /dev/null +++ b/apps/docs/src/components/custom-jsx-component-reference.tsx @@ -0,0 +1,497 @@ +import BrowserOnly from "@docusaurus/BrowserOnly"; +import useBaseUrl from "@docusaurus/useBaseUrl"; +import { useEffect, useMemo, useState } from "react"; + +import { buildCustomJsxComponentUsageExample } from "@homarr/custom-widgets/catalog-example"; +import type { + CustomJsxAuthoringCatalog, + CustomJsxComponentApi, + CustomJsxPropDescriptor, +} from "@homarr/custom-widgets/catalog"; + +import { CustomWidgetCodeExample } from "./custom-widget-code"; +import styles from "./custom-jsx-component-reference.module.css"; + +type ComponentCatalog = CustomJsxAuthoringCatalog; +type CatalogComponent = CustomJsxComponentApi; +type CatalogProp = CustomJsxPropDescriptor; + +const PAGE_SIZE = 40; + +export function CustomJsxComponentReference() { + return ( + }>{() => } + ); +} + +function ComponentReferenceFallback() { + return ( +
    + Loading the Custom JSX component catalog… +
    + ); +} + +function CustomJsxComponentReferenceClient() { + const catalogUrl = useBaseUrl("/custom-widgets/component-catalog-v1.json"); + const [catalog, setCatalog] = useState(null); + const [loadError, setLoadError] = useState(null); + const [query, setQuery] = useState(""); + const [packageFilter, setPackageFilter] = useState("all"); + const [categoryFilter, setCategoryFilter] = useState("all"); + const [safetyFilter, setSafetyFilter] = useState("available"); + const [bindableOnly, setBindableOnly] = useState(false); + const [visibleCount, setVisibleCount] = useState(PAGE_SIZE); + const [expanded, setExpanded] = useState>(() => new Set()); + const [showGlobalProps, setShowGlobalProps] = useState(false); + + useEffect(() => { + const controller = new AbortController(); + setLoadError(null); + + void fetch(catalogUrl, { signal: controller.signal }) + .then(async (response) => { + if (!response.ok) throw new Error(`The catalog request returned HTTP ${response.status}.`); + return (await response.json()) as ComponentCatalog; + }) + .then((value) => { + if (!Array.isArray(value.components) || !Array.isArray(value.types) || !Array.isArray(value.globalProps)) { + throw new Error("The catalog response has an unsupported shape."); + } + setCatalog(value); + }) + .catch((error: unknown) => { + if (controller.signal.aborted) return; + setLoadError(error instanceof Error ? error.message : "The component catalog could not be loaded."); + }); + + return () => controller.abort(); + }, [catalogUrl]); + + const categories = useMemo( + () => [...new Set(catalog?.components.map((component) => component.category) ?? [])].sort(), + [catalog], + ); + const packages = useMemo( + () => [...new Set(catalog?.components.map((component) => component.package) ?? [])].sort(), + [catalog], + ); + const filteredComponents = useMemo(() => { + if (!catalog) return []; + const normalizedQuery = query.trim().toLocaleLowerCase(); + return catalog.components.filter((component) => { + if (packageFilter !== "all" && component.package !== packageFilter) return false; + if (categoryFilter !== "all" && component.category !== categoryFilter) return false; + if (safetyFilter === "available" && component.safety === "denied") return false; + if (safetyFilter !== "all" && safetyFilter !== "available" && component.safety !== safetyFilter) return false; + if (bindableOnly && !component.bind) return false; + if (!normalizedQuery) return true; + + return [ + component.name, + component.package, + component.category, + component.description, + component.deniedReason, + ...component.subcomponents, + ...component.props.map((prop) => prop.name), + ].some((value) => value?.toLocaleLowerCase().includes(normalizedQuery)); + }); + }, [bindableOnly, catalog, categoryFilter, packageFilter, query, safetyFilter]); + const visibleComponents = filteredComponents.slice(0, visibleCount); + + useEffect(() => { + setVisibleCount(PAGE_SIZE); + }, [bindableOnly, categoryFilter, packageFilter, query, safetyFilter]); + + useEffect(() => { + if (!catalog) return; + + const revealHashTarget = () => { + const hash = decodeLocationHash(window.location.hash); + const component = catalog.components.find((entry) => componentAnchor(entry.name) === hash); + if (!component) return; + + if (!document.getElementById(hash)) { + setQuery(component.name); + setPackageFilter("all"); + setCategoryFilter("all"); + setSafetyFilter(component.safety === "denied" ? "all" : "available"); + setBindableOnly(false); + setVisibleCount(PAGE_SIZE); + } + setExpanded((current) => new Set([...current, component.name])); + window.requestAnimationFrame(() => { + window.requestAnimationFrame(() => document.getElementById(hash)?.scrollIntoView({ block: "start" })); + }); + }; + + revealHashTarget(); + window.addEventListener("hashchange", revealHashTarget); + return () => window.removeEventListener("hashchange", revealHashTarget); + }, [catalog]); + + if (loadError) { + return ( +
    + Component catalog unavailable. {loadError} Open the raw catalog to + inspect the generated data directly. +
    + ); + } + + if (!catalog) return ; + + return ( +
    +
    +
    +

    Release-matched static catalog

    +

    Explore {catalog.components.length} Custom JSX components

    +

    + This browser reads the same versioned JSON artifact used by offline authoring. It never imports or executes + the listed component objects. +

    +
    + + Open raw JSON + +
    + +
    +
    +
    Catalog schema
    +
    v{catalog.schemaVersion}
    +
    +
    +
    Custom Widget
    +
    {catalog.customWidgetVersion}
    +
    +
    +
    Mantine
    +
    {catalog.mantineVersion}
    +
    +
    +
    Blocked capabilities
    +
    {catalog.blockedCapabilities.length}
    +
    +
    + +
    +
    +

    Shared serializable props

    +

    + Every available component also receives these {catalog.globalProps.length} generated global, ARIA, data, and + safe style props. Component cards below list only their component-specific additions. +

    +
    + + {showGlobalProps && ( +
    + +
    + )} +
    + +
    + + + + + +
    + +
    + {filteredComponents.length} matching component{filteredComponents.length === 1 ? "" : "s"} + {(query || + packageFilter !== "all" || + categoryFilter !== "all" || + safetyFilter !== "available" || + bindableOnly) && ( + + )} +
    + + {filteredComponents.length === 0 ? ( +
    No component matches these filters.
    + ) : ( +
    + {visibleComponents.map((component) => { + const isExpanded = expanded.has(component.name); + return ( +
    +
    +
    +
    +

    {component.name}

    + + # + +
    +
    + {component.package} + {humanize(component.category)} + {component.safety} + {component.bind && bind: {component.bind.type}} +
    +
    + +
    + {(component.description || component.deniedReason) && ( +

    + {component.deniedReason ?? component.description} +

    + )} + + {isExpanded && ( + + )} +
    + ); + })} +
    + )} + + {visibleCount < filteredComponents.length && ( + + )} +
    + ); +} + +function decodeLocationHash(hash: string) { + const value = hash.slice(1); + try { + return decodeURIComponent(value); + } catch { + return value; + } +} + +function ComponentDetails({ id, component, types }: { id: string; component: CatalogComponent; types: string[] }) { + return ( +
    +
    +
    + +
    + +
    +
    Component contract
    + {component.bind ? ( +

    + bind stores a temporary {component.bind.type} input. Initialize it with{" "} + {component.bind.initialProp}. +

    + ) : ( +

    This component does not expose a temporary-input adapter.

    + )} + {component.subcomponents.length > 0 && ( +

    + Subcomponents:{" "} + {component.subcomponents.map((name, index) => ( + + {index > 0 && ", "} + {name} + + ))} +

    + )} + {component.blockedProps.length > 0 && ( +
      + {component.blockedProps.map((prop) => ( +
    • + {prop.name} is blocked: {prop.reason} +
      • + ))} +
    + )} + {component.accessibilityRequirements.length > 0 && ( +
      + {component.accessibilityRequirements.map((requirement) => ( +
    • {requirement}
      • + ))} +
    + )} + + Open upstream documentation + +
    +
    + +
    +
    + Component props ({component.props.length}) +
    + {component.props.length === 0 ? ( +

    No component-specific props are exposed.

    + ) : ( + + )} +
    + +
    + Raw component JSON + +
    +
    + ); +} + +function PropTable({ props, types }: { props: CatalogProp[]; types: string[] }) { + return ( +
    + + + + + + + + + + + + {props.map((prop) => ( + + + + + + + + ))} + +
    PropTypeRequiredKnown valuesDescription
    + {prop.name} + + {types[prop.typeRef] ?? "unknown"} + {prop.required ? Yes : "No"} + {prop.literalValues?.length ? ( + {prop.literalValues.map(formatLiteral).join(" | ")} + ) : ( + — + )} + {prop.description ?? —}
    +
    + ); +} + +function componentAnchor(name: string) { + return `custom-jsx-component-${name + .replaceAll(".", "-") + .replace(/([a-z0-9])([A-Z])/g, "$1-$2") + .toLowerCase()}`; +} + +function humanize(value: string) { + return value.replaceAll("-", " ").replace(/\b\w/g, (character) => character.toUpperCase()); +} + +function formatLiteral(value: string | number | boolean | null) { + return typeof value === "string" ? JSON.stringify(value) : String(value); +} diff --git a/apps/docs/src/components/custom-widget-code-client.tsx b/apps/docs/src/components/custom-widget-code-client.tsx new file mode 100644 index 000000000..90712bb81 --- /dev/null +++ b/apps/docs/src/components/custom-widget-code-client.tsx @@ -0,0 +1,120 @@ +import { useState } from "react"; +import { MantineProvider, Select, Stack, Text } from "@mantine/core"; +/* oxlint-disable import/no-unassigned-import -- Mantine component styles intentionally load for side effects. */ +import "@mantine/core/styles/Badge.css"; +import "@mantine/core/styles/Button.css"; +import "@mantine/core/styles/Combobox.css"; +import "@mantine/core/styles/Group.css"; +import "@mantine/core/styles/Input.css"; +import "@mantine/core/styles/Loader.css"; +import "@mantine/core/styles/Pill.css"; +import "@mantine/core/styles/PillsInput.css"; +import "@mantine/core/styles/Popover.css"; +import "@mantine/core/styles/ScrollArea.css"; +import "@mantine/core/styles/Stack.css"; +import "@mantine/core/styles/Text.css"; +import "@mantine/core/styles/UnstyledButton.css"; +/* oxlint-enable import/no-unassigned-import */ + +import { + BUNDLED_CUSTOM_WIDGETS, + CUSTOM_WIDGET_OPTIONS_EXAMPLES, + CUSTOM_WIDGET_REQUEST_EXAMPLES, +} from "@homarr/custom-widgets/core"; +import type { CustomWidgetEditorMessages } from "@homarr/custom-widgets/workbench"; +import { ReadOnlyCustomWidgetCode } from "@homarr/custom-widgets/workbench"; + +import type { CanonicalCustomWidgetExampleProps, CustomWidgetCodeExampleProps } from "./custom-widget-code"; + +const messages: CustomWidgetEditorMessages = { + languageJsx: "JSX", + languageJson: "JSON", + undo: "Undo", + redo: "Redo", + components: "Components", + componentSearch: "Search components", + componentEmpty: "No matching components", + componentCount: (count) => `${count} components`, + insertStarter: "Insert starter", + format: "Format", + copy: "Copy", + copied: "Copied", + schema: "Schema", + schemaTab: "JSON Schema", + minimalTab: "Minimal example", + fullTab: "Full example", + errors: (count) => `${count} errors`, + warnings: (count) => `${count} warnings`, + ready: "Read-only example", + position: ({ line, column }) => `Ln ${line}, Col ${column}`, + characters: (count, limit) => (limit ? `${count} / ${limit}` : `${count} characters`), + diagnosticsTitle: "Diagnostics", + diagnostic: (diagnostic) => diagnostic.value ?? diagnostic.code, +}; + +export function CanonicalCustomWidgetExampleClient({ id, label, example, height }: CanonicalCustomWidgetExampleProps) { + const value = example === "requests" ? CUSTOM_WIDGET_REQUEST_EXAMPLES.full : CUSTOM_WIDGET_OPTIONS_EXAMPLES.full; + + return ; +} + +export function CustomWidgetCodeExampleClient(props: CustomWidgetCodeExampleProps) { + return ( + + + + ); +} + +export function BundledCustomWidgetGalleryClient() { + const [selectedId, setSelectedId] = useState(BUNDLED_CUSTOM_WIDGETS[0]?.id ?? null); + const selected = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === selectedId) ?? BUNDLED_CUSTOM_WIDGETS[0]; + if (!selected) return null; + const manifest = { ...selected.widget, template: "__HOMARR_TEMPLATE__" }; + + return ( + + + setEditTitle(event.target.value)} /> + +