chore: reconcile v2 after stack rebase

This commit is contained in:
ajnart committed 2026-08-13 19:59:46 +02:00
1 parent 5dc4dbeaef
commit 0482c040ec
215 files changed
+12297 -17452

No files matched your search

+4 -4
View File
@@ -24,10 +24,10 @@ 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 contains the complete database. It includes Custom Widgets and all other Homarr configuration.
@@ -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/).
You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/).
@@ -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).
For some integrations, you can find a guide on how to retrieve the certificate [here](../certificates/#obtaining-certificates).
+2 -1
View File
@@ -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)
![](./img/screenshot.png)
@@ -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
@@ -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.
+35 -6
View File
@@ -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:
@@ -163,9 +187,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.
@@ -174,6 +200,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)
@@ -184,14 +211,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)
@@ -199,6 +227,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)