Currently an apiKey has the same permissions as the user who created it, however you can only create an apiKey with admin permissions. This means we have to do some extra steps to create a user with only the permissions we need for Argus.

Create a group​

In a first step we have to create a group which will allow us to restrict the permissions of the user we will create later.

1. Go to Management > Users > Groups
2. Click on Create group
3. Enter a name for the group, e.g. Argus
4. Click on Create group
5. Click on the newly created group to edit it
6. In the Permissions tab, select the admin permission and save the changes

Create a user​

Now we can create a user which will be used by Argus to access the /api/info endpoint.

1. Go to Management > Users > Manage
2. Click on Create new user
3. Enter a username, e.g. argus, click next
4. Enter a password for the user, click next
5. Add previously created group Argus to the user, click next
6. Click on next to confirm the user creation

Create an apiKey​

Now we want to create therefore we have to log in with the user we just created.

1. Log out of Homarr
2. Log in with the user we just created
3. Go to Management > Tools > API Keys
4. Click on Create API Key
5. Copy the generated API key and save it somewhere, you will not be able to see it again
6. Logout of Homarr

Reduce permissions of the user​

Now we can reduce the permissions of the user to only allow access to general authenticated, but not permission restricted endpoints.

1. Log in with your admin user
2. Go to Management > Users > Groups
3. Click on the Argus group
4. In the Permissions tab, remove all permissions
5. Save the changes

Configure Argus​

Now you can configure Argus to use the user and apiKey we created.

Replace the <secret> with the apiKey you created and the deployed version url with the url of your Homarr instance.

Export your data​

As 1.0 is a complete rewrite of Homarr and therefor not compatible with the old docker mounts, we need to export your data first. For this you can navigate to the Migrate to 1.0 page which you can find under Management > Tools > Migrate to 1.0. Here you can select which things you want to export and download the zip file. It will also show you a secret key which you will need to import the secret data like user password hashes, salts and integration secrets.

Create a parallel installation​

We highly recommend to create a parallel installation of Homarr 1.0.0. So if something with for example the import does not quite work, the data in the old installation is still available. To do this you can follow the appropriate installation guide for your system. Please note that if you are using docker you need to specify a diffrent external port for the new installation as the old one had the same port. So in your compose file the ports would be 7576:7575 instead of 7575:7575.

Import your data​

Once the installation is completed you can access the new installation. During the onboarding you'll need to select Import from Homarr before 1.0.

After that you can upload the zip file you downloaded in the first step.

After that you'll get a list with all your boards that can be imported. You can configure how it should be imported and can select which screensizes it should import.

Once you have selected everything you can click on Confirm import and continue which will open the encryption key input dialog where you can input the secret key you got during the export.

After that you can continue the onboarding and you should see all your boards and data in the new installation.

See After the installation for more information.

Remove the old installation​

After you are happy with the new installation and everything is working as expected you can remove the old installation. Please make sure to backup the data before you remove the old installation. Also once the port 7575 is free again you can change the port mapping of the new installation to 7575:7575 if you want to.

How to use the beta with docker​

To use the beta with docker you can use the following docker-compose.yml configuration:

#---------------------------------------------------------------------#
#     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
    environment:
      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
    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

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

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.

Breaking changes​

• 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
  • New required env variable SECRET_ENCRYPTION_KEY used for encryption of secrets in the database
  • 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
  • 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 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 as a real time messaging bus
• Development (relevant for contributors):
  • Migrated to pnpm
  • Migrated to a mono-repository
  • All source code has been migrated to the homarr-labs GitHub organization
• 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

A few highlights include:

• Updated navigation bar for much easier navigation
• Improvements to the landing page
• Completely revamped about us page.
• Bug fixes for image zoom
• Added documentation for management pages and new CLI tool

Please let us know is something is not working as expected.

Highlights at a glance​

• 🚀 Completly overhauled authentication system with user management
• ✨ Improved UI for boards (renamed dashboards to boards).
• 💻 Server side preferences -> Dark mode and language are not synced accross all your devices
• 🔗 Invitation links to easily onboard new users
• 👥 Overhauled board management with easy control if anonymous users can view your board
• 🧠 AI assistant on the documentation to answer your questions: https://homarr.dev/
• 📝 Overhauled notepad widget with a complex graphical editor that enables easy editing right from your browser.
• 🌐 Live Translation on Crowdin that enable you to directly translate using images to see what exactly you're translating

Breaking changes​

• Removed PASSWORD environment variable
• Removed DISABLE_EDIT_MODE environment variable
• 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 which collects anonymous data exclusively and protects your personal data rights. You can disable this using the environment variable DISABLE_ANALYTICS.

Changes in detail​

Management pages​

One of the most requested features ever has been authentication. We've completely removed the PASSWORD, DISABLE_EDIT_MODE and EDIT_MODE_PASSWORD and replaced it by a secure authentication system that enables you to manage multiple users easily. We will allow for more detailed permission and user management soon. LDAP and OIDC integrations are currently also in progress and will arrive in a future version.

New dashboard layout​

We've updated the dashboard user interface slightly to an updated design.

Server side preferences page​

Previously, preferences were stored per dashboard and applied to all users. In this release, we moved this page to a separate link and store this on the server. This means that regardless what device your on - your preferences will stay the same when you're logged in.

Invitations for new users​

Tired of creating user accounts by yourself? With the new "invites" feature you can invite new users by simply sending them a link. This link is valid only once and must have an expiration date - more info on that in our documentation.

Additionally, you can deny users, that are not logged into an account, to access your board with a simple toggle:

New "boards" page​

Previously, dashboards were managed in an ugly and hard to control popup. We've moved this now to the new management pages as well and it's now much easier to control:

Read-only for non-administrators and guests​

Yes, managing access to your dashboard is now much easier! Guests and non-administrators cannot edit your dashboard in any way (edit is hidden):

This is not an definite solution and will be significantly improved in an upcoming update.

We are aware that this update has many breaking changes and may confuse some users. For that reason, we updated our documentation and will enhance it further within the next few weeks. We've also added this small button at the bottom of the page were you can ask your questions to an AI assistant:

It's finally here! You can decorate your dashboard now with as many widgets as you want. This applies to all widgets, but in the case of the IFrame widget, it enables you to:

• Integrate as many websites as you want
• Integrate monitoring tools like Grafana, Splunk or Elasticsearch
• Integrate your services (for example Sonarr, Radarr and Overseerr) directly into Homarr

Edit mode password​

We've added a setting to disable editing completely. This will allow you to restrict edit access without password-protection. use the EDIT_MODE_PASSWORD ENV variable to set a password for edit mode. turn on DISABLE_EDIT_MODE=TRUE to disable edit mode on startup.

😎 Blazingly fast​

We've implemented a new caching system, that will cache all data in your browser, meaning that Homarr will load within milliseconds, as if it was powered by rust and blazingly fast !!!

Media request widgets (Overseerr & Jellyseerr)​

We've implemented a new widget, that displays a history of all requests. You can't approve from the widget yet, but we plan to add this in the future.

Multiple RSS feeds​

You can now consume multiple RSS feeds at the same time:

Tab refresh / close confirmation​

Since some have lost their changes, by refreshing the page in the edit mode. We've added a popup that will ask you to confirm you want to reload the page :

Environment variable for default theme​

You can now set the default color scheme using environment variables:

DEFAULT_COLOR_SCHEME = [dark, light]

Global error catching for widgets​

Previously, widgets were able to crash your entire dashboard and just a blank page would be displayed. Now, users will still be able to use their dashboard and an information message will be displayed instead.

Migration to Mantine V6​

We've migrated Mantine to version 6. This will bring some upstream changes for responsiveness and usability.

Fix width and height in the calendar​

In 0.11.5 and previous versions, the calendar scaled poorly if the widget was resized. Now, the calendar will fill out the entire available space and scale nicely with your dashboard.

Performance improvements​

We now use several methods to improve performance and reduce network requests. Homarr will load now within milliseconds and cache data in your browser.

Docker Socket via TCP​

Previously, it was not possible to mount sockets via TCP (eg. tcp://traefik-docker-socket-proxy:2375). Now, you can use the following environment variables to configure this:

• DOCKER_HOST
• DOCKER_PORT

Full Changelog: https://github.com/ajnart/homarr/compare/v0.11.5...v0.12.0

• Integration of Gridstack for much more complex dashboard configuration and drag and drop
• Added icon picker with smart search and automatic icons
• Complete overhaul of the module system
• Added an edit mode for making changes easier
• Form validation for better user experience
• Better security with new built-in credentials system
• Huge design and usability improvements to older components to Homarr
• Better handeling of exceptions and unexpected issues

Complete implementation of highly customizable drag and drop library "Gridstack"​

In 0.11, we have replaced our quite limited drag and drop system with Gridstack. Gridstack enables you to create much more complex and advanced dashboards while keeping everything organized.

We've also introduced more advanced categories this time:

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 completely recoded. This fixes some of the bugs a few users have previously experienced and improves overall customization.

Fancy icon picker for speeding up your creation process​

We've also added a new fancy icon picker, you can use to get access to any icons much faster. We will add more icon sources in the future, as we made this icon picker very modular, and we plan to make local icons accessible via this picker very soon.

Design and documentation improvements to homarr.dev​

https://homarr.dev has been overhauled with better design, updated documentation, more images and better explanations.

Download Homarr now!​

Homarr is completly free, even for commercial usage!

We need your help​

Yes, we need YOU! We want to make Homarr accessible to as many people as possible. Thus, we need to translate all content into many different languages. We need your help for that! You can help us now to translate Homarr into as many languages as possible.

About global translations / translations per user​

We are aware that many people would like to configure translations globally or configure language per user. Currently, translations are stored in the Cookies, which will expire after some time (currently, it's set to 30 days). We will implement more granular language settings in future versions of Homarr, since it requires major changes to Homarr. Stay tuned! 😎

We are still figuring things out and highly depend on your feedback.

Why we migrated​

The default GitHub Wiki feature is decent - but very confusing to read. Our possibilites for searching the documentation in the Wiki are highly limited. Additionally, Users are unable to contribute to the documentation if they have not sufficient permissions.

We could not review any chanegs made to the documentation. This is why we migrated to Docusaurus.

How you can contribute​

The documentation will soon be merged into the master branch of Homarr. You'll find a doc/ directory in the root of Homarr. We'll obviously not include this in our Docker images. In the future, everyone may modify the documentation by creating a pull request. After we've reviewed your changes, we'll merge your PR and this documentation will automatically update.

TL;DR​

The documentation on GitHub Wiki will soon disappear. It will be replaced with this Docusaurus-powered website. You'll find much more information here with higher detail and searchability.