feat(docs): migrate documentation site into monorepo (#5912)

2026-06-11 18:48:39 +02:00
1 parent 3e464a76f2
commit 9e421c67bd
@@ -0,0 +1,9 @@
+{
+  "label": "Management",
+  "collapsed": true,
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "title": "Management pages"
+  }
+}
@@ -0,0 +1,84 @@
+---
+title: API
+tags:
+  - API
+  - Development
+  - Interface
+---
+
+import { ApiReferenceReact } from "@scalar/api-reference-react"
+
+Using the Homarr API, you can interface with the application with your own code and business logic.
+It enables you to trigger almost all actions that you can perform from the Homarr UI.
+With the API, you can build resilient systems that automatically update Homarr with data - for example syncing it with
+your deployments in a cluster or dynamically adding integrations depending on how many replicas you run.
+
+This page is language-neutral, and you must implement the API on your own in your desired language.
+It requires you to know your programming language well and have a basic understanding of HTTP, JSON and networking.
+You can test out API endpoints using any OpenAPI client - for example [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/) or [Hoppscotch](https://hoppscotch.io/).
+
+## Opening the API specification
+The specification is implemented according to the OpenAPI standard.
+To access the documentation, you'll need to spin up an instance of Homarr.
+Navigate to ``Management`` > ``Tools`` > ``API``.
+You can copy the JSON url into your OpenAPI client or try out the endpoints directly from your browser.
+
+## Authentication
+Many endpoints will require you to authenticate. At the top of the API reference, you'll find a button to authenticate yourself with an API key.
+You can obtain API keys from the "Authentication" tab at the top of the page.
+API keys will not expire and can be used indefinitely.
+
+### API Key Format
+API keys are provided in the format `<id>.<token>`. When making requests, include the key in the `ApiKey` header:
+
+```
+ApiKey: abc123def456.xyz789tokenvalue...
+```
+
+### Supported Endpoints
+API key authentication works with both endpoint types:
+
+| Endpoint Type | Path Pattern | API Key Support |
+|--------------|--------------|-----------------|
+| OpenAPI | `/api/...` | ✅ Supported |
+| tRPC | `/api/trpc/...` | ✅ Supported |
+
+If no API key is provided, Homarr falls back to session cookie authentication (for browser-based access).
+
+### Usage Examples
+
+**OpenAPI endpoint:**
+```bash
+curl -H 'ApiKey: <id>.<token>' http://localhost:7575/api/health/live
+```
+
+**tRPC endpoint:**
+```bash
+curl -H 'ApiKey: <id>.<token>' http://localhost:7575/api/trpc/app.all
+```
+
+### Use Cases
+API key authentication enables programmatic access for:
+- Automation scripts and CI/CD pipelines
+- Third-party integrations
+- Custom dashboards and monitoring tools
+- Container orchestration systems that need to sync app definitions
+
+## Specification
+
+:::info
+
+This section is automatically being updated hourly.
+Last update:
+``TEST`` <!-- OPEN_API_SPEC_LAST_UPDATED -->
+
+:::
+
+<ApiReferenceReact
+  configuration={{
+    url: "/api/open-api-schema.json",
+    theme: "kepler",
+    hideModels: false,
+    hideDownloadButton: false,
+  }}
+/>
@@ -0,0 +1,53 @@
+---
+title: Apps
+tags:
+  - Management
+  - Apps
+  - Bookmarks
+  - 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 used in the bookmark and app widget.
+
+## Create an app
+
+To create an app you can click on the button on the top right of the apps management page:
+
+![New app button](./img/new-app-button.png)
+
+Next, you'll need to fill out the required fields to configure the app:
+
+![New app form](./img/new-app-form.png)
+
+### Name
+
+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. 
+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)
+
+### Description
+
+An optional description that can be shown as tooltip on the app widget.
+
+### URL
+
+The URL to the website you want to link to. Clicking on the app widget or bookmark will open this URL.
+
+### Ping URL
+
+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.
+
+## List of apps
+
+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)
@@ -0,0 +1,258 @@
+---
+title: Boards
+tags:
+  - Management
+  - Boards
+  - Customization
+  - Edit mode
+  - Responsive
+  - 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'
+
+Each dashboard is called a "board".
+You can create as many boards as you want.
+Boards can be restricted to user groups.
+A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/board).
+Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) or via the management pages.
+
+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)
+
+Alternatively, you can also navigate from the board page itself using the cog icon at the top right:
+
+![](./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)
+
+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:
+
+![](./img/meta-title.png)
+
+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.
+
+### Layout
+
+In this section you can configure the different responsive layouts. Depending on your screens width the layout will change.
+
+![](./img/layout-settings.png)
+
+On each element the position and size of items can be changed seperately.
+When adding a new layout the position and sizes will automatically be generated depending on the column count.
+When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position.
+
+#### Name
+
+The name of the layout can be choosen freely. It is only used for the management and will not be visible on the board.
+
+#### Column count
+
+Amount of columns for this layout. Defines how many items can be placed in a row. When changed it will automatically adjust the position and size of the items.
+
+#### Breakpoint
+
+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
+
+<img src={layoutSmallImage}  height={256} />
+<img src={layoutMediumImage}  height={256} />
+<img src={layoutLargeImage}  height={256} />
+
+### 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.
+
+<img src={iconColorImage}  height={100} />
+
+#### Item radius
+Change the radius of your items / categories.
+
+<img src={itemRadiusImage}  height={100} />
+
+
+### Custom CSS
+This is the field where you can enter custom CSS.
+The styling will only be applied on the respective board page.
+
+[See this guide on how to work with custom CSS](/docs/advanced/styling/).
+
+### 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                        |
+
+The permission level can only be changed after adding the user / group:
+
+![](./img/change-user-permission-level.png)
+
+If the board is private and the user is not added in any of the three tabs, they cannot access the board.
+They also do not see the board on the start page nor do they have access to any links for the board.
+
+Groups that have high permissions (e.g. administrator or all board permissions) will be shown as "inherited".
+They are permitted implicitly due to their permissions.
+
+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:
+
+- Navigate to the settings of your board, open the "Danger zone" dropdown and click on the "delete this board" button.
+- Navigate to the list of boards in the management pages, click the three dots and click on "delete permanently".
+
+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 
+nor the integrations the user does not have access to.
+:::
+
+Duplicating a board will create a new board with the same settings and layout as the original board.
+You can duplicate a board by clicking on the three dots in the list of boards and selecting "Duplicate board".
+
+![](./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``
+
+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``.
+
+### For other users
+
+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)
+
+### 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)
+
+### 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)
+
+:::note
+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)
@@ -0,0 +1,65 @@
+---
+tags:
+  - Administration
+  - Self signed
+  - Certificates
+  - Integration
+---
+
+# 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. 
+The color of the icon indicates how long it is valid.
+
+![](./img/screenshot.png)
+
+| 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 |
+
+
+## Opening the certificates page
+Navigate to ``Management`` > ``Tools`` > ``Certificates``.
+
+## Add a certificate
+To add a certificate click on the "Add certificate" button.
+
+![](./img/add-button.png)
+
+Then select the certificate file you want to add.
+
+![](./img/add-modal.png)
+
+And click the "Add" button.
+
+## Delete a certificate
+
+To delete a certificate you can click on the trash icon in the certificate card.
+
+![](./img/card.png)
+
+Then confirm the deletion.
+
+## Managing it through file system
+
+The certificates are stored in the `/appdata/trusted-certificates` directory which is mounted through `/appdata`.
+This means you can automate the update of the certificates by simply replacing or adding a new file in the directory.
+
+## Obtaining certificates
+
+Every integration has its own way of obtaining certificates.
+Generally it is recommended to search for the documentation of the integration you are using.
+Most of the time you can find the certificate in the file system of the integration.
+Below you can find instructions for some of the integrations.
+
+### Pi-hole (v6)
+
+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/).
@@ -0,0 +1,98 @@
+---
+tags:
+  - Integrations
+  - Data sources
+  - Connections
+---
+
+# 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)
+
+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.
+To improve security, they will never be passed to the client and requests to the integrations are performed from the host where Homarr is running on.
+
+### Linking applications
+
+During the creation of an integration you can choose to add / link an application to the integration.
+If you want to add one, you can simply specify the app url which will be used for opening the application from Homarr.
+The linked application will also be used for any links the integration widget contains.
+If you already have an application created, you can also link it to the integration by selecting it from the dropdown.
+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.
+
+## Managing permissions
+
+On the edit page of an integration, you can manage which users / groups can
+
+- **Select the integration in items:** Allows users to select the integration and showing data on their board.
+- **Interact with the integration:** Allows users to perform actions on the integration, such as pausing a download.
+- **Full control over the integration:** Allows users to modify the integration properties, including the URL and secrets.
+
+![](./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:
+
+1. Check whether you are using the correct URL and secrets.
+   - The URL must be the base URL of the application, **without any paths**.
+   - 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.
+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.
+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``
+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.
+
+If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub.
+
+### Certificate issues
+
+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).
@@ -0,0 +1,13 @@
+---
+tags:
+  - Administration
+  - Media
+  - Uploads
+  - Icons
+---
+
+# 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)
@@ -0,0 +1,62 @@
+---
+tags:
+  - Search engines
+  - Google
+  - Search
+---
+
+# 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)
+
+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).
+
+### 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.
+
+##### 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``
+
+## Media request search
+
+Jellyseerr, Overseerr, and Seerr integrations have a dedicated **Spotlight mode** for searching and requesting media.
+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
+- **Requested** — requested but not yet available
+
+### Requesting TV show seasons
+
+For partially available TV shows, you can request additional seasons.
+The request modal shows which seasons are already requested (marked with a status badge and not selectable), so you can select only the missing seasons.
@@ -0,0 +1,105 @@
+---
+tags:
+  - Settings
+  - SEO
+  - Analytics
+  - Security
+  - Server
+  - Administration
+---
+
+# 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.
+The main server software can be found [here](https://github.com/umami-software/umami) and [this node library](https://github.com/umami-software/node) to perform server side calls to the API.
+
+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.
+
+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.
+If you use Homarr as a public website and want it to be searchable on these search engines, you can disable these settings.
+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.
+You can ask the crawlers to not allow searches by enabling this setting.
+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. 
+It will also be used for anonymous users.
+Note that the board must be public to be used as a global home board.
+
+### Global mobile board
+
+You can set a global mobile board. It will be shown instead of the global home board on mobile devices that can be detected by Homarr. (Using the User-Agent header).
+It will similar to the global home board be as fallback for normal users and for any anonymous users.
+It also has to be public.
+
+### App status
+
+#### Enable status by default
+
+You can decide if the app status should be enabled by default when adding a new app to the board.
+
+#### Force disable status
+
+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.
@@ -0,0 +1,43 @@
+---
+tags:
+  - Background
+  - Jobs
+  - Tasks
+---
+
+# Tasks
+
+Homarr has background jobs for various tasks, most of them are for realtime widget updates.
+The tasks page allows you to run background jobs manually and configure them.
+
+![Tasks page](./img/tasks.png)
+
+## Opening the tasks page
+
+Navigate to `Management` > `Tools` > `Tasks`.
+The page is only accessible to users with admin permission.
+
+## Changing interval
+
+In the column `Schedule interval` you can change the interval in which the task runs.
+Different intervals are available, such as `1 minute`, `5 minutes`, `10 minutes`, `30 minutes`, and `1 hour`.
+All intervals are cron expressions, which means it will run the next time the cron expression matches the current time.
+
+## Actions
+
+You can find different actions for each task on the right side of a task item.
+
+### Run Manually
+
+To run a task manually, click the "Play" button, which will execute the task immediately.
+During the exection the badge will show `Running`.
+
+### Disabling / Enabling
+
+You can disable a task by clicking the "Power" button, which will change it to a "Power-Off" button.
+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.
+
+
+
@@ -0,0 +1,202 @@
+---
+title: Users
+tags:
+  - Users
+  - Roles
+  - Permissions
+  - Groups
+---
+
+# Users
+
+Each person accessing Homarr is a user. Using the users management you can configure who has access to certain resources.
+A user may have multiple sessions on different devices and can log in from multiple locations at the same time.
+A user can be assigned to multiple groups.
+
+:::tip
+
+Homarr supports [single sign on for easier and seamless authentication](/docs/advanced/single-sign-on) (e.g. Authelia).
+
+:::
+
+## 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: \
+![](./img/button-create-user.png)
+
+You'll be guided through the process using a wizard: \
+![](./img/create-wizard.png)
+
+The username and Email must be unique. A username is required.
+When creating a password, you must meet the password requirements: \
+![](./img/password-requirements.png)
+
+After you completed all steps, you can start over to create another user or choose to go back to the list: \
+![](./img/wizard-complete.png)
+
+## Editing a user
+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.
+
+#### Search
+
+Options to configure default search engine of user and whether to open search results in a new tab.
+
+#### First day of the week
+
+Choose the first day of the week for the user. This will affect the calendar widget.
+
+#### Accessibility
+
+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.
+
+### 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.
+You must take care of sending the new password to the user.
+This functionality can also be useful to lock out a bad actor without tampering with any data (except the password hash).
+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. 
+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.
+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)
+
+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:
+
+- Boards
+  - **Create boards**: Allow members to create boards
+  - **View all boards**: Allow members to view all boards
+  - **Modify all boards**: Allow members to modify all boards (Does not include access control and danger zone)
+  - **Full board access**: Allow members to view, modify, and delete all boards (Including access control and danger zone)
+- Integrations
+  - **Create integrations**: Allow members to create integrations
+  - **Use all integrations**: Allows members to add any integrations to their boards
+  - **Interact with any integration**: Allow members to interact with any integration
+  - **Full integration access**: Allow members to manage, use and interact with any integration
+- **Administrator**: Members with this permission have full access to all features and settings
+
+When you changed permissions, you must confirm your changes by clicking the banner at the bottom:
+
+![](./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.
+
+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)
+
+Next, define the expiration time for this invitation. They will expire after some time and will no longer be valid.
+It must be at least 1 hour in the future and at max 6 months in the future.
+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:
+
+![](./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.
+
+### Self-onboarding
+Clicking the invitation link will bring up a form with fields for the username and password:
+
+![](./img/invitation-self-onboarding.png)
+
+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)
+
+The link will become invalid.
+If the invitation expires, the link will also expire.