Squashed commit of the following:

commit 06aa662 Author: Manuel <[email protected]> Date: Tue Dec 17 22:10:42 2024 +0100 docs: update truenas documentation commit 86e0c7d Merge: 36e9773 98dbb48 Author: Manuel <[email protected]> Date: Tue Dec 17 21:49:16 2024 +0100 Merge branch 'docs/version-1.0' of https://github.com/homarr-labs/documentation into docs/version-1.0 commit 36e9773 Author: Manuel <[email protected]> Date: Tue Dec 17 21:49:14 2024 +0100 docs: remove kubernetes docs commit 98dbb48 Merge: 113602f 0b530cc Author: Meier Lukas <[email protected]> Date: Tue Dec 17 21:39:56 2024 +0100 Merge branch 'docs/version-1.0' of https://github.com/homarr-labs/documentation into docs/version-1.0 commit 113602f Author: Meier Lukas <[email protected]> Date: Tue Dec 17 21:39:45 2024 +0100 feat: add blog post about open beta and how to use it commit 0b530cc Author: Manuel <[email protected]> Date: Tue Dec 17 18:30:27 2024 +0100 docs: document 1.0.0 migration commit 663bb20 Author: Manuel <[email protected]> Date: Tue Dec 17 17:39:03 2024 +0100 docs: update helm page commit e18edbd Author: Manuel <[email protected]> Date: Tue Dec 17 17:13:45 2024 +0100 fix: broken links commit cfc90f5 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 17:00:50 2024 +0100 docs: adjust v1 blog post breaking changes commit 37653d9 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 16:43:42 2024 +0100 docs: update env variables commit 06abf77 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 16:25:34 2024 +0100 docs: update single-sign-on documentation commit 6c51da6 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 16:03:26 2024 +0100 fix: wrong default value for 24 hour format of clock widget commit 0c18357 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 16:02:26 2024 +0100 docs: adjust start from and end at calendar configuration description commit 3c9b7d0 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:59:32 2024 +0100 docs: add group permission and transfer ownership descriptions to user management commit db1170b Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:56:25 2024 +0100 docs: add missing server settings commit 960ec5b Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:53:34 2024 +0100 docs: add global home board to board management commit 23c19e2 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:46:46 2024 +0100 fix: typo in after-the-installation commit 44a8205 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:45:10 2024 +0100 docs: add extenal admin group step for onboarding commit 7ce3ae3 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:28:56 2024 +0100 fix: adjust mounts for docker-compose and run with new /appdata commit 8773ac4 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:20:27 2024 +0100 fix: typo in prerequisites commit 8346b2d Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:19:15 2024 +0100 fix: footer license link not working commit 6342354 Author: Meier Lukas <[email protected]> Date: Tue Dec 17 15:16:55 2024 +0100 docs: remove accessibility from home-page features commit a409022 Author: Manuel <[email protected]> Date: Mon Dec 16 22:59:44 2024 +0100 docs: update media management commit a9d4383 Author: Manuel <[email protected]> Date: Mon Dec 16 22:49:58 2024 +0100 fix: broken links commit 2d8e132 Author: Manuel <[email protected]> Date: Mon Dec 16 22:36:01 2024 +0100 docs: update community commit ca74120 Author: Manuel <[email protected]> Date: Mon Dec 16 22:23:39 2024 +0100 docs: update advanced commit b915430 Author: Manuel <[email protected]> Date: Mon Dec 16 22:19:41 2024 +0100 docs: update icon picker commit 2b467cd Author: Manuel <[email protected]> Date: Mon Dec 16 22:03:53 2024 +0100 docs: update command line docs commit 1851192 Author: Manuel <[email protected]> Date: Mon Dec 16 22:00:16 2024 +0100 docs: update video widget commit 35bbe2b Author: Manuel <[email protected]> Date: Mon Dec 16 21:54:58 2024 +0100 docs: update widgets commit 917bb53 Author: Manuel <[email protected]> Date: Mon Dec 16 21:16:06 2024 +0100 docs: update dns hole commit 9f5f96d Author: Manuel <[email protected]> Date: Mon Dec 16 21:04:54 2024 +0100 docs: document calendar widget commit 0ed2dd2 Author: Manuel <[email protected]> Date: Mon Dec 16 20:45:51 2024 +0100 docs: update integrations commit 4874e11 Author: Manuel <[email protected]> Date: Mon Dec 16 17:27:35 2024 +0100 docs: update after-the-installation commit 07566e4 Author: Manuel <[email protected]> Date: Tue Dec 10 20:52:20 2024 +0100 docs: update after-the-installation commit 931714c Author: Meier Lukas <[email protected]> Date: Thu Dec 5 19:37:53 2024 +0100 docs: add seperate developer guide (#138) commit 7ec1aed Author: Meier Lukas <[email protected]> Date: Sat Nov 23 13:27:23 2024 +0100 docs: add apps management documentation commit de4c13c Author: Meier Lukas <[email protected]> Date: Sat Nov 23 13:26:53 2024 +0100 docs: add caution about column count, fix home board urls and adjust inherited permissions commit 6b87692 Author: oussama Dahmaz <[email protected]> Date: Tue Nov 5 20:42:33 2024 +0100 docs(helm): add helm docs (#119) Co-authored-by: oussama Dahmaz <[email protected]> commit 9c8a411 Author: Manuel <[email protected]> Date: Tue Nov 5 14:10:58 2024 +0100 feat: fix announcement bar coloring commit 06d1890 Author: Manuel <[email protected]> Date: Tue Nov 5 13:23:06 2024 +0100 feat: improve design commit 08f28b5 Author: Manuel <[email protected]> Date: Tue Nov 5 10:28:33 2024 +0100 fix: openapi spec path commit 1874b3d Author: Manuel <[email protected]> Date: Tue Nov 5 08:46:40 2024 +0100 feat: add open api doc (#129) fix remove https from url commit 50e4e0d Author: Manuel <[email protected]> Date: Mon Nov 4 20:14:56 2024 +0100 config: add open api doc (#128) commit 7dd37e2 Author: Manuel <[email protected]> Date: Sun Nov 3 21:35:33 2024 +0100 feat: improve design commit ea21eea Author: Meier Lukas <[email protected]> Date: Wed Oct 16 22:16:00 2024 +0200 docs: add notice about everyone group commit 331782c Author: Meier Lukas <[email protected]> Date: Wed Oct 16 21:40:33 2024 +0200 docs: add twitter to community dropdown commit f59e746 Author: Manuel <[email protected]> Date: Mon Oct 7 23:20:20 2024 +0200 feat: improve dataflow design commit 3b21aaf Author: Manuel <[email protected]> Date: Mon Oct 7 23:01:29 2024 +0200 feat: add available integrations showcase commit eb46f1a Author: Manuel <[email protected]> Date: Mon Oct 7 22:33:40 2024 +0200 feat: improve design of dataflow commit 9bf1bcf Author: Manuel <[email protected]> Date: Mon Oct 7 22:26:06 2024 +0200 feat: add drag and drop showcase commit 6ae7a06 Author: Manuel <[email protected]> Date: Sun Oct 6 23:06:58 2024 +0200 feat: improve design of landing pages commit a4c4ed4 Author: Manuel <[email protected]> Date: Sun Oct 6 22:22:19 2024 +0200 fix: docusaurus sidebars commit dc23cf8 Author: Manuel <[email protected]> Date: Sun Oct 6 22:16:34 2024 +0200 docs: add board docs commit 99a06fa Author: Manuel <[email protected]> Date: Sun Oct 6 21:51:52 2024 +0200 fix: build error commit 08933cb Author: Manuel <[email protected]> Date: Sun Oct 6 16:13:53 2024 +0200 docs: update boards docs commit c2c9cb5 Author: Manuel <[email protected]> Date: Sun Oct 6 15:48:00 2024 +0200 docs: update boards docs commit 4549a9e Author: Manuel <[email protected]> Date: Sun Oct 6 15:36:33 2024 +0200 docs: add settings docs commit a8587dc Author: Manuel <[email protected]> Date: Sun Oct 6 15:07:35 2024 +0200 docs: add integrations documentation commit 58b3603 Author: Manuel <[email protected]> Date: Sun Oct 6 14:20:37 2024 +0200 fix: broken links commit 8512db4 Author: Manuel <[email protected]> Date: Sun Oct 6 00:19:07 2024 +0200 docs: add search engine docs commit 59710ba Author: Manuel <[email protected]> Date: Sun Oct 6 00:06:55 2024 +0200 docs: update users documentation commit 357765a Author: Manuel <[email protected]> Date: Fri Oct 4 22:25:35 2024 +0200 refactor: move pages commit c0f45fe Author: Manuel <[email protected]> Date: Fri Oct 4 21:31:02 2024 +0200 refactor: installation pages commit df2aed0 Author: Manuel <[email protected]> Date: Thu Oct 3 20:01:21 2024 +0200 docs: add api docs commit 8cb9444 Author: Manuel <[email protected]> Date: Mon Sep 23 20:48:46 2024 +0200 docs: add breaking changes
homarr-labs · Dec 18, 2024 · 3d05598 · 3d05598
1 parent d9a4dbf
commit 3d05598
Show file tree

Hide file tree

Showing 328 changed files with 3,904 additions and 2,547 deletions.
diff --git a/.github/workflows/dump-api-data.yaml b/.github/workflows/dump-api-data.yaml
@@ -15,6 +15,9 @@ permissions:
 jobs:
   dump:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20]
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v2

diff --git a/.github/workflows/update-homarr-openapi.yaml b/.github/workflows/update-homarr-openapi.yaml
@@ -0,0 +1,83 @@
+name: "Homarr API spec"
+
+on:
+  schedule:
+    - cron: "* */1 * * *" # Every hour
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  start-homarr-and-export-api-spec:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20]
+    steps:
+      - uses: actions/checkout@v4
+        name: "Checkout app source repository"
+        with:
+          repository: homarr-labs/homarr
+      - uses: pnpm/action-setup@v2
+        name: "Install pnpm"
+        with:
+          version: 8
+      - name: "Use Node.js ${{ matrix.node-version }}"
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+      - run: pnpm install
+        name: "Install dependencies"
+      - run: pnpm dev > server.log 2>&1 &
+        working-directory: apps/nextjs
+        env:
+          TURBO_TELEMETRY_DISABLED: 1
+          DISABLE_TELEMETRY: 1
+        name: "Start development server in background"
+      - name: "Wait for server to be ready"
+        run: |
+          for i in {1..30}; do
+            if curl -s http://localhost:3000/api/openapi -o /dev/null; then
+              echo "Server is up!"
+              break
+            fi
+            echo "Waiting for server to start..."
+            sleep 3
+          done
+
+          if [ "$i" -eq 30 ]; then
+            echo "Server failed to start within timeout."
+            cat docker.log
+            exit 1
+          fi
+      - name: "Fetch OpenAPI specification from development server"
+        run: wget http://localhost:3000/api/openapi
+      - name: "Rename OpenAPI spec"
+        run: mv openapi openapi.json
+      - uses: actions/upload-artifact@master
+        with:
+          name: api-specification
+          path: openapi.json
+
+  update-api-spec:
+    runs-on: ubuntu-latest
+    needs: start-homarr-and-export-api-spec
+    steps:
+      - uses: actions/checkout@v4
+        name: "Checkout documentation source repository"
+        with:
+          repository: homarr-labs/documentation
+      - uses: actions/download-artifact@master
+        with:
+          name: api-specification
+          path: openapi.json
+      - name: "Move file to target directory"
+        run: mv openapi.json ./static/api/open-api-schema.json
+      - uses: EndBug/add-and-commit@v9
+        with:
+          add: './static/api/'
+          default_author: github_actor
+          message: 'chore(api-spec): update OpenAPI spec'
+          push: true
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,10 @@
+{
+    "cSpell.words": [
+        "Homarr",
+        "Lidarr",
+        "Nextcloud",
+        "Radarr",
+        "Readarr",
+        "Sonarr"
+    ]
+}
diff --git a/blog/2023/01-11-version0.11/index.mdx b/blog/2023/01-11-version0.11/index.mdx
@@ -46,7 +46,7 @@ We'll continute to improve this system according to your feedback.
 
 ## Modules have been overhauled and renamed to widgets
 
-Widgets are now much snappier and have been completly recoded.
+Widgets are now much snappier and have been completely recoded.
 This fixes some of the bugs a few users have previously experienced and improves overall customization.
 
 ![](../../../docs/widgets/img/choose-widget-in-modal.webp)
@@ -60,7 +60,7 @@ We will add more icon sources in the future, as we made this icon picker very mo
 
 ## Design and documentation improvements to homarr.dev
 
-https://homarr.dev has been overhauled with better design, updated documentation, more images and better explanations. We've also added a few community made resources, such as the [icon cache script](/docs/advanced/customizations/icons#caching-remote-icons) and [Traefik tutorial](/docs/advanced/configuration/proxies-and-certificates#securing-homarr-with-traefik).
+https://homarr.dev has been overhauled with better design, updated documentation, more images and better explanations.
 
 ## Download Homarr now!
 

diff --git a/blog/2023/11-10-authentication/index.mdx b/blog/2023/11-10-authentication/index.mdx
@@ -32,7 +32,7 @@ provide you a viable solution today.
 - Removed ``EDIT_MODE_PASSWORD`` environment variable
 - Added mounting point ``/data`` for your database
 - Require at least one administrator account on your instance. An onboarding process will automatically set this up.
-- We've added analytics to the documentation and Homarr itself. We use [Umami Analytics](https://umami.is/) which collects anonymous data exclusively and protects your personal data rights. You can disable this using the environment variable ``DISABLE_ANALYTICS``. More information [here](/docs/advanced/configuration/environment-variables#anonymous-analytics)
+- We've added analytics to the documentation and Homarr itself. We use [Umami Analytics](https://umami.is/) which collects anonymous data exclusively and protects your personal data rights. You can disable this using the environment variable ``DISABLE_ANALYTICS``.
 
 ## Changes in detail
 

diff --git a/blog/2024/09-23-version-1.0/index.mdx b/blog/2024/09-23-version-1.0/index.mdx
@@ -0,0 +1,87 @@
+---
+authors:
+  - manuel-rw
+---
+
+# Homarr 1.0 - complete rewrite of all systems
+We proudly present to you - Homarr ``1.0``.
+We have started work on this new version back in 2023 and have worked tirelessly for months on this brand-new dashboard.
+
+This isn't our usual update. ``1.0`` doesn't use the same code from previous versions, but has been written from the ground up.
+Therefore, this version contains an unusual amount of breaking changes.
+This will be a one time occurrence and version > ``1.0`` will have less breaking changes.
+This time more important than every; **read the breaking changes** list and **create a backup** before updating.
+Some third party installation methods may take multiple days or weeks to update to the new version.
+
+See [this guide on how to import your previous Homarr dashboard](/docs/getting-started/after-the-installation#importing-a-zip-from-version-before-100)
+
+## Changes at a glance
+- **Asynchronous integrations system**: In versions prior to ``1.0``, we fetched data upon each request synchronously.
+This means that the user had to wait for the requests to finish so any data would appear.
+A page reload will trigger another request - and worse, this will happen for every user accessing your dashboard.
+In ``1.0``, we have implemented a new system that gets rid of this system and scales linearly.
+It will fetch data in background, even if you are not on the page.
+- **Permissions system**: You can now use detailed permissions to allow or prohibit users from certain actions.
+For easier management, you can organize users into groups and manage them all at the same time.
+- **Integration testing**: Starting from ``1.0``, we will require you to test the integration before you can use it.
+This guarantees that you've configured your integration correctly and helps you find errors faster.
+- **Re-imagined widgets**: All widgets have been rewritten & improved. They offer much better performance,
+reliability and scalability compared to < ``1.0``.
+- **Improved performance**: We have upgraded the underlying framework of Homarr and take advantage
+of an in-memory message bus and websockets to deliver data near realtime to you.
+
+<!-- truncate -->
+
+## Breaking changes
+:::warning
+
+Please consult the breaking changes list & upgrade guide if you used third-party installation methods.
+
+:::
+
+- Docker Image
+  - Removed support for ``arm/v7`` -> upgrade to newer architectures as an alternative
+  - Renamed image from ``ghcr.io/ajnart/homarr`` to ``ghcr.io/homarr-labs/homarr``. We now use semantic versioning for our release numbers.
+- Environment Variables
+  - Removed ``DISABLE_ANALYTICS``, can now be configured via UI
+  - Renamed ``AUTH_PROVIDER`` to ``AUTH_PROVIDERS``
+  - Renamed ``DATABASE_URL`` to ``DB_URL`` and made it optional conditionally. If ``DB_HOST`` is set, this is optional - otherwise it's required.
+  - Changed ``DOCKER_HOST`` to two new variables for hostnames (``DOCKER_HOSTNAMES``) and ports (``DOCKER_PORTS``). This allows for multiple docker integrations to be configured.
+  - ``AUTH_LOGOUT_REDIRECT_URL`` must now be a valid Url
+  - Increased minimum length of ``AUTH_OIDC_CLIENT_ID`` to 1
+  - Increased minimum length of ``AUTH_OIDC_CLIENT_SECRET`` to 1
+  - Removed ``AUTH_OIDC_TIMEOUT`` **<ins># TODO: Discuss whether we need to copy this?</ins>**
+  - Removed ``AUTH_LDAP_ADMIN_GROUP``, ``AUTH_LDAP_OWNER_GROUP``, ``AUTH_OIDC_ADMIN_GROUP`` and ``AUTH_OIDC_OWNER_GROUP`` -> groups are now managed without manual env binding
+  - ``CI`` will now also trigger an env validation skip like ``SKIP_ENV_VALIDATION``
+- Mounts
+  - Removed ``/app/data/configs`` -> JSON configs have been removed in favour of relation databases
+  - Removed ``/app/public/icons`` -> Images can not be uploaded via the [media management](/docs/management/media/) in the UI
+  - Moved ``/data`` to ``/appdata`` and restructured contents (not backwards compatible!) -> Create a backup before migration of the entire directory to copy data to new Homarr
+- Widgets:
+  - Calendar:
+    - Removed option ``Use Sonarr v4 API``
+    - Removed option ``Use Sonarr v5 API``
+    - Removed option ``Font Size``
+    - Removed option ``Hide week days``
+  - Download speed: We have removed this widget in favour of the brand new download widget which will also display this data.
+  - Dash. widget: We have removed this widget in favour of the System Health Widget. It will also display all data and some more than the old widget.
+- Database:
+  - Changed schema of the database to a completely new schema. They are not backwards compatible. Please export the data from old Homarr in the UI and import it in ``1.0``
+  - Removed all usage of JSON files to store data. Import JSON files in Homarr ``1.0`` to import your dashboards.
+  - Removed ``schemaVersion`` from JSON and use the drizzle migrations to keep track of schema versions and take care of migrations.
+- Web Server:
+  - Added an internal Nginx proxy to forward requests to two servers inside the container for technical reasons.
+  This could impact edge cases with iframes, cookies and custom setups.
+- Dependencies
+  - We now depend on [Redis](https://redis.io/) as a real time messaging bus
+- Development (relevant for contributors):
+  - Migrated to [pnpm](https://pnpm.io/)
+  - Migrated to a mono-repository
+  - All source code has been migrated to the [homarr-labs GitHub organization](https://github.com/homarr-labs)
+- Platform specific breaking changes:
+  - TrueNAS
+    - The TrueCharts app chart is permanently deprecated and no longer maintained / supported. Please migrate to Electric Eel or a different Kubernetes platform.
+  - Unraid
+    - The Homarr app must be reinstalled. The existing directories on your disk are not compatible with Homarr 1.0. Export your old data in < `` 1.0`` and install using different file system locations.
+  - Kubernetes
+    - The official Helm chart has moved from https://github.com/oben01/charts to https://github.com/homarr-labs/charts
diff --git a/blog/2024/12-17-open-beta-1.0/index.mdx b/blog/2024/12-17-open-beta-1.0/index.mdx
@@ -0,0 +1,37 @@
+---
+authors:
+  - meierschlumpf
+---
+
+# Open Beta 1.0
+
+We are proud to announce the open beta of Homarr 1.0. This is a major milestone for us and we are excited to share it with you.
+The open beta allows us to polish the last rough edges and gather feedback from you.
+We are looking forward to your feedback and hope you enjoy the new features.
+Let us know throgh discord or a [github issues](https://github.com/homarr-labs/homarr/issues/new/choose) if you encounter any issues.
+
+<!-- truncate -->
+
+## How to use the beta with docker
+
+To use the beta with docker you can use the following docker-compose.yml configuration:
+
+```yml title="docker-compose.yml"
+#---------------------------------------------------------------------#
+#     Homarr - A simple, yet powerful dashboard for your server.      #
+#---------------------------------------------------------------------#
+services:
+  homarr:
+    container_name: homarr
+    image: ghcr.io/homarr-labs/homarr:beta
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration
+      - ./homarr/appdata:/appdata
+    ports:
+      - '7575:7575'
+```
+
+Then, run `docker compose up -d` in the same directory. This will start the Homarr container in the background.
+Please note that the mounts have changed and it's not backwards compatible with versions before 1.0.0-beta.1.
+You can find a list of all breaking changes [here](/blog/2024/09/23/version-1.0)
diff --git a/docs/advanced/command-line/_category_.json b/docs/advanced/command-line/_category_.json
@@ -1,4 +1,4 @@
 {
-  "collapsed": false,
+  "collapsed": true,
   "label": "Command line interface"
 }
diff --git a/docs/advanced/command-line/password-recovery/img/screenshot-cli-owner-reset.png b/docs/advanced/command-line/password-recovery/img/screenshot-cli-owner-reset.png
diff --git a/docs/advanced/command-line/password-recovery/index.mdx b/docs/advanced/command-line/password-recovery/index.mdx
@@ -1,23 +1,14 @@
-# 🔑 Password Recovery
+# Password Recovery
 
 :::info
 
 This guide requires that you understand [how to access the CLI](../).
 
 :::
 
-This command can be useful, if you forget the password to your administrator account or you don't have access to the Web UI.
-
-## Reset for the administrator
-
-This command is parameter-less. It will create a random password, update the database and display the new password.
-All sessions for the administrator will be terminated and they must re-login.
-
-![](./img/screenshot-cli-owner-reset.png)
-
-## Reset for a specific user
-
-The syntax of the command is as follows:
+Using this command, you can forcefully reset the password of a user.
+It will be set to a random value and the hash for the user will be updated.
+All sessions for that user will be terminated and the user must re-login.
 
 ![](./img/screenshot-cli.png)
 

diff --git a/docs/advanced/configuration/_category_.json b/docs/advanced/configuration/_category_.json