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

apps/docs/docs/advanced/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Advanced",
+  "collapsed": true,
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "title": "Advanced Concepts or features"
+  }
+}

apps/docs/docs/advanced/command-line/_category_.json

@@ -0,0 +1,4 @@
+{
+  "collapsed": true,
+  "label": "Command line interface"
+}

apps/docs/docs/advanced/command-line/fix-usernames/index.mdx

@@ -0,0 +1,17 @@
+# Fix usernames
+
+:::info
+
+This guide requires that you understand [how to access the CLI](../).
+
+:::
+
+If you somehow get into a situation where you have users with usernames that contain uppercase characters and you are no longer able to log in, you can use the following command to fix the usernames.
+
+```bash
+homarr fix-usernames
+```
+
+This will convert all credential usernames to lowercase and update the database accordingly.
+
+![](./img/screenshot-cli.png)

apps/docs/docs/advanced/command-line/index.mdx

@@ -0,0 +1,27 @@
+# Command line interface
+
+The Homarr image ships with a built-in recovery tool. This can be useful, if you do not have access to Homarr or if something is not working.
+Please note that the CLI is an *emergency tool*, not an API tool.
+
+:::caution
+
+Using the recovery CLi tool can cause problems when requests are being sent to Homarr while the tool is running. \
+You should also create a backup of the database, in case you break something.
+
+:::
+
+## Execute CLI with Docker
+
+1. Execute ``docker ps | grep homarr`` on the root system with Docker to find the container ID of your Homarr container.
+2. Run ``docker exec -it <container-id> /bin/bash homarr <your-command-goes-here>``. \
+Replace ``<container-id>`` with your container ID from step 1. \
+Replace ``<your-command-goes-here>`` with the command you want to execute (see sub-pages).
+
+## Execute CLI with QNAP
+
+1. Open Container Station in the QNAP Web Interface ![](img/334116069-e7ec4726-3df7-4dc6-a3e0-b745e7eef17f.png)
+2. Select Containers in the menu bar on the left ![](img/334116205-aa09ce40-0701-4f7d-b9f9-b431b9d207c5.png)
+3. Select your Homarr Container ![](img/334116303-714b5e07-b9de-4ec0-a2bc-def7ee38750f.png)
+4. Click "Execute" in the top right of the Window. ![](img/334116411-df1482f9-3aa9-4686-b77f-e0dca09e60b2.png)
+5. Select /bin/bash and click Execute ![](img/334116518-e1ddb515-99c7-4159-81bf-76e889d1e808.png)
+6. Run the Homarr command and press enter (eg. homarr reset-owner-password) ![](img/334116642-08c4f204-5cd0-4e4e-a785-0142e1b279ca.png)

apps/docs/docs/advanced/command-line/integrations/index.mdx

@@ -0,0 +1,60 @@
+# Integrations
+
+:::info
+
+This guide requires that you understand [how to access the CLI](../).
+
+:::
+
+Using these commands, you can manage the integrations from the CLI:
+```bash
+Group of commands to manage integrations
+
+Usage:
+  homarr integrations [command]
+
+Available Commands:
+  list     List all integrations (id and name)
+  delete   Delete an integration by id or name
+
+Flags:
+  -h, --help      help for integrations
+  -v, --version   version for homarr-cli
+
+Use "homarr integrations [command] --help" for more information about a command.
+```
+
+## List Integrations
+
+- Requires a database connection
+- Lists all configured integrations
+
+```bash
+List all integrations (id and name)
+
+Usage:
+  homarr integrations list [flags]
+
+Flags:
+  -h, --help      help for integrations list
+  -v, --version   version for homarr-cli
+```
+
+## Delete Integration
+
+- Requires a database connection
+- Requires one parameter: ``id`` or ``name``
+- Deletes an integration permanently from the database
+
+```bash
+Delete an integration by id or name
+
+Usage:
+  homarr integrations delete [flags]
+
+Flags:
+  -i, --id string     ID of the integration
+  -n, --name string   Name of the integration
+  -h, --help          help for integrations delete
+  -v, --version       version for homarr-cli
+```

apps/docs/docs/advanced/command-line/password-recovery/index.mdx

@@ -0,0 +1,19 @@
+# Password Recovery
+
+:::info
+
+This guide requires that you understand [how to access the CLI](../).
+
+:::
+
+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)
+
+Using the ``--username`` parameter, you can specify who you want to reset the password for.
+Executing the command will create a new random password, update the database and display the new password.
+All sessions for this user will be terminated and they must re-login.
+
+![](./img/screenshot-cli-result.png)

apps/docs/docs/advanced/command-line/users/index.mdx

@@ -0,0 +1,79 @@
+# Users
+
+:::info
+
+This guide requires that you understand [how to access the CLI](../).
+
+:::
+
+Using these commands, you can manage the users from the CLI:
+```bash
+Group of commands to manage users
+
+Usage:
+  homarr users [command]
+
+Available Commands:
+  list              List all users (id, username, email)
+  delete            Delete a user by id or username
+  update-password   Update the password for a user (credentials provider only)
+
+Flags:
+  -h, --help      help for users
+  -v, --version   version for homarr-cli
+
+Use "homarr users [command] --help" for more information about a command.
+```
+
+## List Users
+
+- Requires a database connection
+
+```bash
+ID                              Username        Email
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+yj52ek5cyb6du4bp4osbkjry        admin           xxxx@example.com
+```
+
+## Delete User
+
+- Requires a database connection
+- Requires one parameter: ``id`` or ``username``
+
+```bash
+Delete a user by id or username
+
+Usage:
+  homarr users delete [flags]
+
+Flags:
+  -i, --id string         ID of the user
+  -u, --username string   Name of the user
+  -h, --help              help for users delete
+  -v, --version           version for homarr-cli
+```
+
+## Update Password
+
+- Updates the password of an user
+- Requires database connection
+- Requires either a username or id
+- Requires a password (which will be encrypted by Homarr)
+
+```bash
+Update the password for a user (credentials provider only)
+
+Usage:
+  homarr users update-password [flags]
+
+Flags:
+  -i, --id string         ID of the user
+  -u, --username string   Name of the user
+  -p, --password          New password
+  -h, --help              help for users update-password
+  -v, --version           version for homarr-cli
+```

apps/docs/docs/advanced/development/_category_.json

@@ -0,0 +1,9 @@
+{
+    "label": "Developer guides",
+    "position": 6,
+    "collapsed": true,
+    "link": {
+      "type": "generated-index"
+    }
+  }
+  

apps/docs/docs/advanced/development/getting-started.mdx

@@ -0,0 +1,68 @@
+---
+title: Getting started
+tags:
+  - Developer
+  - Technical documentation
+  - Code
+  - Programming
+sidebar_position: 1
+---
+
+## Setting up your development environment
+
+This guide will help you set up your development environment to start contributing to homarr.
+
+### Prerequisites
+
+- **Node.js (lts)**: You can download it from the [official website](https://nodejs.org/).
+- **pnpm (latest)**: You can install it by running `npm install -g pnpm`.
+- **Git**: You can download it from the [official website](https://git-scm.com/).
+- **Docker or Docker Desktop**: You can download it from the [official website](https://www.docker.com/).
+- **A GitHub account**: You can create one on the [official website](https://github.com/).
+
+### Setting up the project
+
+1. Fork the repository by clicking on the "Fork" button on the top right corner of the repository page.
+
+![Fork button](./img/fork.png)
+
+2. Clone the repository to your local machine with `git clone`. You can find the url to use by clicking on the "Code" button on the top right corner of your forks repository page.
+
+![Clone button](./img/clone.png)
+
+3. Change directory to the project folder with `cd homarr`.
+
+4. Install the dependencies with `pnpm install`.
+
+5. Start redis by running `pnpm run docker:dev`. This will run a docker-compose file with a redis service.
+
+6. Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite database file. For example `DB_URL='C:\\Dev\\homarr\\packages\\db\\db.sqlite'`
+
+7. Run the migrations to create the sqlite db file with `pnpm run db:migration:sqlite:run`.
+
+8. Start the development server with `pnpm dev` and wait for a message that says `✓ Ready in 10.7s`
+
+9. Open your browser and navigate to [http://localhost:3000](http://localhost:3000). (Loading the page might take up to 2 minutes the first time)
+
+### Useful npm scripts
+
+#### During development
+
+- `pnpm dev`: Start the development server.
+- `pnpm cli`: Run cli commands.
+- `pnpm db:migration:sqlite:run`: Run the migrations to create or update the sqlite db file.
+- `pnpm db:migration:sqlite:generate`: Generate a new migration file for the sqlite db. Also works with `mysql`.
+- `pnpm db:studio`: Open a visual studio for the database.
+- `pnpm package:new`: Create a new package in the monorepo.
+
+#### Checking code quality
+
+- `pnpm lint`: Run the linter to check for code quality issues.
+- `pnpm format:fix`: Run the formatter to fix code style issues.
+- `pnpm test`: Run the tests. You can also use `pnpm test:ui` to get a UI for the tests.
+- `pnpm typecheck`: Run the typescript type checker.
+
+#### Building the project
+- `pnpm build`: Build the project for production.
+- `docker build -t homarr .`: Build a docker image for the project.
+- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:latest`: Run the created docker image.

apps/docs/docs/advanced/development/kubernetes.mdx

@@ -0,0 +1,135 @@
+---
+title: Kubernetes
+tags:
+  - Developer
+  - Technical documentation
+  - Code
+  - Programming
+sidebar_position: 1
+---
+
+This guide provides step-by-step instructions for setting up a Kubernetes cluster using kind, configuring multiple nodes, and installing the Metrics Server.
+
+## Prerequisites
+
+Ensure you have the following installed:
+
+- [Docker](https://docs.docker.com/get-started/get-docker/) (required for running `kind` clusters).
+- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) (Kubernetes in Docker).
+- [Kubectl](https://kubernetes.io/docs/tasks/tools/) (Kubernetes command-line tool).
+
+Additionally, ensure that Kubernetes tools are enabled in your environment by setting the following variable in your `.env` file:
+
+```bash
+# Enable Kubernetes tool
+ENABLE_KUBERNETES=true
+```
+
+### 1. Creating a Kubernetes Cluster with Multiple Nodes
+
+We will create a Kubernetes cluster using `kind` with one control plane node and two worker nodes.
+
+#### Define the Cluster Configuration
+
+Create a configuration file named `kind-config.yaml` with the following content:
+
+```bash
+cat > kind-config.yaml <<EOF
+# three node (two workers) cluster config
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+    - |
+      kind: KubeletConfiguration
+      apiVersion: kubelet.config.k8s.io/v1beta1
+      kubeReserved:
+        cpu: "250m"
+        memory: "256Mi"
+      systemReserved:
+        cpu: "500m"
+        memory: "512Mi"
+      evictionHard:
+        memory.available: "200Mi"
+- role: worker
+- role: worker
+EOF
+```
+
+#### Create the Cluster
+
+Run the following command to create the Kubernetes cluster:
+
+```bash
+kind create cluster --name k8s-playground --config kind-config.yaml
+```
+
+This will provision a cluster named `k8s-playground` with the specified node configuration.
+
+### 2. Installing the Metrics Server
+
+The Metrics Server is required for gathering resource utilization metrics like CPU and memory usage. It is essential for features such as Horizontal Pod Autoscaling.
+
+#### Deploy the Metrics Server
+
+Run the following command to install the Metrics Server:
+
+```bash
+kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.7.2/components.yaml
+```
+
+#### Disable TLS Verification (For Local Development)
+
+In local environments, Kubernetes nodes might not have valid certificates. To disable TLS verification, patch the deployment:
+
+```bash
+kubectl patch -n kube-system deployment metrics-server --type=json \
+  -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'
+```
+
+This allows the Metrics Server to communicate with kubelets that use self-signed certificates.
+
+### 3. Verifying the Setup
+
+After completing the setup, verify that the cluster is running correctly:
+
+#### Check the Cluster Nodes
+
+```bash
+kubectl get nodes
+```
+
+Expected output:
+
+```bash
+NAME                           STATUS   ROLES           AGE     VERSION
+k8s-playground-control-plane   Ready    control-plane   Xs      vX.Y.Z
+k8s-playground-worker          Ready    worker          Xs      vX.Y.Z
+k8s-playground-worker2         Ready    worker          Xs      vX.Y.Z
+```
+
+#### Check Metrics Server Status
+
+```bash
+kubectl get deployment -n kube-system metrics-server
+```
+
+Expected output:
+
+```bash
+NAME             READY   UP-TO-DATE   AVAILABLE   AGE
+metrics-server   1/1     1            1           Xs
+```
+
+#### Get Node Resource Metrics
+
+```bash
+kubectl top nodes
+```
+
+This command should return CPU and memory usage statistics for each node.
+
+## Conclusion
+
+You have successfully set up a multi-node Kubernetes cluster using kind and installed the Metrics Server for monitoring resource usage. This setup is useful for local development and testing Kubernetes workloads before deploying them to a production environment.

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -0,0 +1,114 @@
+---
+title: Environment variables
+tags:
+  - Configuration
+  - Docker
+  - Advanced
+  - Env
+  - Environment variables
+  - Variables
+  - Database
+  - Redis
+  - Secrets
+---
+
+Homarr offers a few environment variables, which can be used to configure the container.
+
+:::info
+With docker you can add the `_FILE` suffix to any environment variable, which will read the value from a file.
+This is especially useful for [docker secrets](https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose).
+:::
+
+## General
+
+:::warning
+Using the `PUID` and `PGID` will require you to set the correct permissions on the mounted volumes and if used the docker socket. See more in the [Running as a different user](/docs/advanced/running-as-different-user) documentation.
+:::
+
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| ``PUID``                 | User ID to run the container as | Any valid user ID | ``0`` |
+| ``PGID``                 | Group ID to run the container as | Any valid group ID | ``0`` |
+| ``LOG_LEVEL``           | Log level to use | ``debug`` / ``info`` / ``warn`` / ``error`` | ``info`` |
+| ``NO_EXTERNAL_CONNECTION`` | Disables some requests that need internet connection | `true` or `false` | `false` |
+| ``ENABLE_DNS_CACHING`` | Enables dns caching. Enabled by default, but if you experience issues with IPv6 or static IPs, see [#4006](https://github.com/homarr-labs/homarr/issues/4006) or disable this flag | `true` or `false` | `true` |
+
+
+
+## Authentication
+
+See [Single Sign-On](/docs/advanced/single-sign-on) for more informations.
+
+## Security
+
+The `SECRET_ENCRYPTION_KEY` is required. If none is specified before starting the container, a random key will be shown in the error message and the container will exit.
+
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| ``SECRET_ENCRYPTION_KEY``  | Secret used to encrypt secrets in database. | 64 character hex string | - |
+
+:::info
+A random secret can be generated by using the following command: `openssl rand -hex 32`
+:::
+
+## Docker
+
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| ``DOCKER_HOSTNAMES``          | Comma seperated list of hostnames to connect to | For example `localhost,docker.example.com` | - |
+| ``DOCKER_PORTS``             | Comma seperated list of ports to connect to | For example `2375,2376` | - |
+| ``DOCKER_SOCKET_PATHS``             | Comma seperated list of paths to sockets | For example `/var/run/docker.sock,/run/user/1000/podman/podman.sock` | - |
+
+## Database
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| ``DB_DRIVER``            | Database driver to use. Currently `better-sqlite3` is used for sqlite, `mysql2` for mysql and `node-postgres` for postgresql | ``better-sqlite3`` / ``mysql2`` /  ``node-postgres`` | ``better-sqlite3`` |
+| ``DB_DIALECT``           | Database dialect to use. | ``sqlite`` / ``mysql`` / ``postgresql``  | ``sqlite`` |
+| ``DB_URL`` | Database URL to connect to. | Any valid database URL | ``/appdata/db/db.sqlite`` | 
+| ``DB_HOST`` | Database host to connect to. | Any valid database host | - |
+| ``DB_PORT`` | Database port to connect to. | Any valid database port | - |
+| ``DB_NAME`` | Database name to connect to. | Any valid database name | - |
+| ``DB_USER`` | Database user to connect with. | Any valid database user | - |
+| ``DB_PASSWORD`` | Database password to connect with. | Any valid database password | - |
+
+You can either use the url or host, port, name and credentials combined. The URL will be prioritized over the other values.
+
+
+## Redis
+
+By default Redis is running within the installation. (for example in Docker).
+However for example for K8s it can be useful to use an external Redis instance.
+
+:::note
+External redis is currently not supported with Proxmox Community Scripts
+:::
+
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| `REDIS_IS_EXTERNAL`     | Whether Redis is running externally. | `true` / `false` | `false` |
+| `REDIS_HOST`            | Hostname of the Redis instance. | Any valid hostname | - |
+| `REDIS_PORT`            | Port of the Redis instance. | Any valid port | `6379` |
+| `REDIS_USERNAME`        | Username to connect to the Redis instance. | Any valid username | - |
+| `REDIS_PASSWORD`        | Password to connect to the Redis instance. | Any valid password | - |
+| `REDIS_DATABASE_INDEX`  | Select which database of your redis instance should be used. | Any numeric index | - |
+| `REDIS_TLS_CA`         | CA certificate for Redis TLS connections. If a certificate is specified the connection will use TLS. | Any valid CA certificate | - |
+
+
+## Proxy
+
+| Environment Variable     | Description | Possible values | Default |
+| ------------------------ | ----------- | --------------- | ------- |
+| ``HTTP_PROXY``           | HTTP proxy to use | Any valid HTTP proxy URL | - |
+| ``HTTPS_PROXY``          | HTTPS proxy to use | Any valid HTTPS proxy URL | - |
+| ``NO_PROXY``             | Comma separated list of hosts that should be excluded from proxying | Any valid hostnames | - |
+
+
+## Advanced deployments
+
+:::warning
+The advanced deployments environment variables should only be used if you know what you are doing.
+:::
+
+| Environment Variable     | Description |
+| ------------------------ | ----------- |
+| ``DB_MIGRATIONS_DISABLED`` | Disable db migrations. For example for helm charts |

apps/docs/docs/advanced/icons/index.mdx

@@ -0,0 +1,34 @@
+---
+title: Icons
+tags:
+  - Configuration
+  - Customization
+  - Icons
+  - Icon picker
+  - Icon repositories
+---
+
+## Icon picker
+Icons in Homarr are automatically requested from multiple sources:
+  - [Dashboard Icons](https://dashboardicons.com/) - Our recommended source with over 1888+ curated, high-quality icons
+  - [selfh.st icons](https://github.com/selfhst/icons)
+  - [Simple icons](https://github.com/simple-icons/simple-icons)
+  - [Tabler icons](https://tabler-icons.io/)
+  - [Papirus icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme)
+  - [Homelab Svg assets](https://github.com/loganmarchione/homelab-svg-assets)
+  - **Local icons**: automatically fetched from the [medias feature](/docs/management/media/)
+
+Using these icon sources, Homarr provides a total collection of over 11,000 icons at your fingertips.
+The icon picker is a fast searcher that helps you to find your desired icon simply by entering a search term.
+
+### Finding Missing Icons
+
+If you can't find the icon you're looking for in Homarr's built-in picker, we strongly recommend checking [Dashboard Icons](https://dashboardicons.com/). It offers a modern, user-friendly interface and a curated collection of high-quality icons specifically designed for dashboards and app directories.
+
+![Icon picker](./img/icon-picker.gif)
+
+Icons that are high quality and printable ([SVG](https://wikipedia.org/wiki/Scalable_Vector_Graphics)) are marked with a red badge "SVG" at the top right.
+
+### Using external icons
+If you don't find the icon you're looking for on Dashboard Icons or wish to use a different source, you can simply enter a URL that points to an icon.
+It is important that the URL directly points to the file without any advertisements or elements around it.

apps/docs/docs/advanced/keyboard-shortcuts/index.mdx

@@ -0,0 +1,27 @@
+---
+title: Keyboard Shortcuts
+tags:
+  - Advanced
+---
+
+Homarr has the following keyboard shortcuts:
+
+| Shortcut | Description |
+| -------- | ----------- |
+| `MOD` + `K` | Opens the search bar |
+| `MOD` + `J` | Toggles Dark Mode |
+| `MOD` + `E` | Toggles Edit Mode |
+
+:::tip
+
+Here `MOD` refers to the modifier key, which is `Ctrl` on Windows and `Cmd` on macOS.
+
+:::
+
+:::note
+
+The focus of your browser must be set on Homarr. If you click outside of Homarr, you might need to click once somewhere in Homarr to send all keystrokes again to Homarr.
+
+If the shortcuts are not working, ensure that you have selected the correct keyboard layout.
+
+:::

apps/docs/docs/advanced/proxy/index.mdx

@@ -0,0 +1,163 @@
+---
+title: Proxies and Certificates
+tags:
+  - Configuration
+  - Proxy
+  - Advanced
+  - Traefik
+  - Caddy
+  - Security
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Allowing self-signed certificates
+Some users may come across a barrier, where they're unable to receive a 200 response from the Ping widget for some apps, while using self-signed certificates or a local certificate authory.
+
+:::note What's going on?
+
+Homarr is trying to communicate to your apps via the integrations.
+It usually doesn't matter if Homarr is running on ``http`` or ``https``.
+Your apps have a self-signed certificate - Homarr will recognize that the certificate was signed by an unknown authority and requests will be blocked.
+
+:::
+
+To allow self-signed certificates, you can configure them on the certificates management page. You can find more informations on the dedicated page: [Certificates](/docs/management/certificates/)
+
+## Securing Homarr with Traefik
+
+Copying the configuration straight from the docker-compose file won't work if you are running Homarr behind Traefik, such as a Portainer setup, or docker-swarm. In that case, you should use the following slightly modified configuration:
+```yaml
+version: '3'
+services:
+  homarr:
+    container_name: homarr
+    image: ghcr.io/homarr-labs/homarr:latest
+    restart: unless-stopped
+    volumes:
+      - ./homarr/appdata:/appdata
+    environment:
+      - BASE_URL=your.internal.dns.address.here.com
+      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
+    networks:
+      - proxy
+    labels:
+      traefik.enable: true
+      traefik.http.routers.homarr.rule: Host(`your.internal.dns.address.here.com`)
+      traefik.http.routers.homarr.entrypoints: websecure
+      traefik.http.routers.homarr-secure.app: homarr
+      traefik.http.apps.homarr.loadbalancer.server.port: 7575
+
+networks:
+  proxy:
+    external: true
+```
+
+<br/>
+
+A sample Traefik docker-compose.yml using Cloudflare for certificate generation that works with the configuration above would be:
+```yaml
+version: '3'
+
+apps:
+  traefik:
+    image: traefik:latest
+    container_name: traefik
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    networks:
+      - proxy
+    ports:
+      - 80:80
+      - 443:443
+    environment:
+      - CF_API_EMAIL=yourcfemail@here.com
+      - CF_DNS_API_TOKEN=long-token-from-cf
+
+    command:
+      - "--log.level=DEBUG"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--providers.docker.endpoint=unix:///var/run/docker.sock"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
+      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
+      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
+      - "--entrypoints.websecure.address=:443"
+      - "--entrypoints.websecure.http.tls.certResolver=cloudflare"
+      - "--certificatesresolvers.cloudflare.acme.storage=acme.json"
+      - "--certificatesResolvers.cloudflare.acme.email=yourcfemail@here.com"
+      - "--certificatesResolvers.cloudflare.acme.dnsChallenge=true"
+      - "--certificatesResolvers.cloudflare.acme.dnschallenge.provider=cloudflare"
+      - "--certificatesResolvers.cloudflare.acme.dnschallenge.resolvers=1.1.1.1:53,1.0.0.1:53"
+      - "--serversTransport.insecureSkipVerify=true" # Or proxmox gives an error 500 due to its own self-signed cert
+
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./data/acme.json:/acme.json
+
+networks:
+  proxy:
+    external: true
+```
+
+
+:::tip
+Of particular note here is that both configurations explicitly define which network they are using, in this case "proxy", but it can be named anything. It just has to be the same across all apps for which Traefik is serving as a proxy. These are marked as external because the proxy network was manually created by running: `docker network create proxy` but this might be unnecessary depending on HOW exactly you are running Traefik. For example, if running [Traefik with Portainer](https://docs.portainer.io/advanced/reverse-proxy/traefik#deploying-in-a-docker-standalone-scenario), you can follow their official docs on how to set up Traefik and Portainer together, and you can just focus on the Homarr docker labels instead.
+:::
+
+## Securing Homarr with Caddy
+
+If you are using Caddy as the reverse proxy for your setup, your `docker-compose.yml` should look something like this:
+
+```yaml
+services:
+  
+  # <-- [Homarr installation]
+
+  caddy:
+    container_name: caddy
+    image: caddy:2
+    restart: unless-stopped
+    ports:
+      - 80:80
+      - 443:443
+      - 443:443/udp
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy_data:/data
+      - caddy_config:/config
+    networks:
+      - proxy
+
+volumes:
+  caddy_data:
+  caddy_config:
+
+networks:
+  proxy:
+    external: true
+```
+:::important
+Homarr needs to be on the same network so you will need to add the following property to your homarr install:
+```yaml
+homarr:
+  ...
+  networks:
+    - proxy
+```
+:::
+
+Next, create a file named `Caddyfile` at the same level as your `docker-compose.yml` file with the following content:
+
+```
+homarr.mydomain.com {
+	reverse_proxy homarr:7575
+}
+```
+
+If you want more information about working with Caddy and Docker Compose, refer to the official documentation:
+https://caddyserver.com/docs/running#docker-compose

apps/docs/docs/advanced/running-as-different-user/index.mdx

@@ -0,0 +1,93 @@
+---
+title: Running as a different user
+tags:
+  - Configuration
+  - Docker
+  - Advanced
+  - PGID
+  - PUID
+---
+
+By default the container is running with user `root` and group `root`. 
+You can change the user and group by using the `PUID` and `PGID` environment variables.
+Important to note is, that you'll also need to change the permissions for the mounted directories accordingly.
+
+:::info
+When starting up an updated version of the container it will have about **10 seconds longer to start** as it has to change the permissions of the app directories
+:::
+
+## Without mounted Docker socket
+
+To run your container as a different user, you can use the `PUID` and `PGID` environment variables:
+
+```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:latest
+    restart: unless-stopped
+    volumes:
+      - ./homarr/appdata:/appdata
+    environment:
+        - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
+        - PUID=1000
+        - PGID=1000
+    ports:
+      - '7575:7575'
+```
+
+After that you'll need to create the appdata directory and set the correct permissions:
+
+```bash title="On host"
+mkdir -p ./homarr/appdata
+chown -R 1000:1000 ./homarr/appdata
+```
+
+## With mounted Docker socket
+
+If you want to use the Docker integration, you'll need to set the correct permissions for the Docker socket as well, most of the times it will have the owner group set to docker group.
+In any way, it is recommended to create this group and set it's permissions to it, if it doesn't exist yet:
+
+```bash title="On host"
+groupadd -g 999 docker
+```
+
+Then you can set the permissions for the Docker socket:
+
+```bash title="On host"
+chown root:docker /var/run/docker.sock
+```
+
+After that you can set the `PUID` and `PGID` environment variables in your `docker-compose.yml` file:
+
+```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:latest
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./homarr/appdata:/appdata
+    environment:
+        - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
+        - PUID=1000
+        - PGID=999
+    ports:
+      - '7575:7575'
+```
+
+And set the permissions for the mounted directories:
+
+```bash title="On host"
+mkdir -p ./homarr/appdata
+chown -R 1000:999 ./homarr/appdata
+```
+
+Important here is that the group ID is set to `999` as we created the `docker` group with this ID.

apps/docs/docs/advanced/single-sign-on/index.mdx

@@ -0,0 +1,360 @@
+---
+title: Single Sign On
+tags:
+  - Management
+  - Users
+  - Docker
+  - SSO
+  - LDAP
+  - OIDC
+  - Active Directory
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Single Sign On
+
+Homarr supports multiple authentication options, from internal userbase (credentials), to LDAP (with Active directory support), and OIDC.
+
+### Auth configuration common variables
+| Environment Variable      | Description | Default Value |
+|---------------------------|-------------|---------------|
+| AUTH_PROVIDERS             | Select Which provider to use between *credentials*, *ldap* and *oidc*. <br /> Multiple providers can be enabled with by separating them with `,`, (ex. `AUTH_PROVIDERS=credentials,oidc`, it is highly recommended to just enable one provider).  |  credentials  |
+| AUTH_LOGOUT_REDIRECT_URL  | URL to redirect to after clicking logging out.  | --- |
+| AUTH_SESSION_EXPIRY_TIME  | Time for the session to time out. Can be set as pure number, which will automatically be used in seconds, or followed by s, m, h or d for seconds, minutes, hours or days. (ex: "30m") | "30d"  |
+
+<Tabs>
+  <TabItem value="credentials" label="Credentials Provider" default>
+
+    This is the default provider.
+
+    First user is created using the onboarding process and the rest can be created by this user (see [user management](/docs/management/users))
+
+  </TabItem>
+  <TabItem value="ldap" label="LDAP provider">
+
+    This provider authenticates against an LDAP server.
+
+    Any user in LDAP server that signs in gets created in Homarr database.
+
+    Roles are fetched from LDAP groups. Groups with the same name of Homarr will be used to synchronize them.
+
+
+
+
+    <details>
+      <summary>
+        Example Setup
+      </summary>
+      <div>
+
+        In this setup we are using [lldap](https://github.com/lldap/lldap). Install your server using docker or [as a service](https://github.com/lldap/lldap/blob/main/example_configs/lldap.service).
+
+        Minimal configuration requires 4 env variables, LDAP URI, base, user and password for querying data.
+
+        There's more variables, but all have defaults corresponding to lldap defaults. These might need to be changed if you have different LDAP provider.
+        ```
+        docker run ...
+        AUTH_PROVIDERS="ldap"
+        AUTH_LDAP_URI="ldap://example.com:3890"
+        AUTH_LDAP_BASE="dc=example,dc=com" // Same as LLDAP_LDAP_BASE_DN
+        AUTH_LDAP_BIND_DN="uid=admin,ou=People,dc=example,dc=com"
+        AUTH_LDAP_BIND_PASSWORD="adminpass" // Same as LLDAP_LDAP_USER_PASS
+        ```
+        ```
+        #Docker compose
+        version: x
+        services:
+          homarr:
+            environment:
+              AUTH_PROVIDERS: ldap
+              AUTH_LDAP_URI: ldap://example.com:3890
+              AUTH_LDAP_BASE: dc=example,dc=com #Same as LLDAP_LDAP_BASE_DN
+              AUTH_LDAP_BIND_DN: uid=admin,ou=People,dc=example,dc=com
+              AUTH_LDAP_BIND_PASSWORD: adminpass #Same as LLDAP_LDAP_USER_PASS
+        ```
+
+        In lldap, create a user and admin group, assign this user to the external admin group configured during onboarding. You can log in using this user and he will be in the group.
+
+        Here is another example for Active Directory:
+
+        ```
+        AUTH_LDAP_URI="ldap://ldap.abc.xyz:389
+        AUTH_LDAP_BASE="DC=abc,DC=xyz"
+        AUTH_LDAP_BIND_DN="CN=Administrator,CN=Users,DC=abc,DC=xyz"
+        AUTH_LDAP_BIND_PASSWORD="YourAdministratorPassword"
+        AUTH_LDAP_USERNAME_ATTRIBUTE="sAMAccountName"
+        AUTH_LDAP_USER_MAIL_ATTRIBUTE="userPrincipalName"
+        AUTH_LDAP_GROUP_CLASS="group"
+        AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE="member"
+        AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE="dn"
+        AUTH_LDAP_SEARCH_SCOPE="sub"
+        AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG="(sAMAccountType=805306368)"
+        ```
+        User mail attribute is set to userPrincipalName as it follows the right schema, but it is recommended to use real emails and the default 'mail' value.
+
+      </div>
+    </details>
+
+
+    ### Configuration
+
+    | Environment Variable                      | Description                                               | Default value       |
+    |-------------------------------------------|-----------------------------------------------------------|---------------------|
+    | ``AUTH_LDAP_URI``                         | URI of your LDAP server                                   | ---                 |
+    | ``AUTH_LDAP_BASE``                        | Base dn of your LDAP server                               | ---                 |
+    | ``AUTH_LDAP_BIND_DN``                     | User used for finding users and groups                    | ---                 |
+    | ``AUTH_LDAP_BIND_PASSWORD``               | Password for bind user                                    | ---                 |
+    | ``AUTH_LDAP_USERNAME_ATTRIBUTE``          | Attribute used for username                               | uid                 |
+    | ``AUTH_LDAP_USER_MAIL_ATTRIBUTE``         | Attribute used for mail field                             | mail                |
+    | ``AUTH_LDAP_GROUP_CLASS``                 | Class used for querying groups                            | groupOfUniqueNames  |
+    | ``AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE``      | Attribute used for querying group member                  | member              |
+    | ``AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE`` | User attribute used for comparing with group member       | dn                  |
+    | ``AUTH_LDAP_SEARCH_SCOPE``                | Serach scopes between base, one and sub                   | base                |
+    | ``AUTH_LDAP_USERNAME_FILTER_EXTRA_ARG``   | Extra arguments for user search filter (& based)          | ---                 |
+    | ``AUTH_LDAP_GROUP_FILTER_EXTRA_ARG``      | Extra arguments for user's groups search filter (& based) | ---                 |
+
+  </TabItem>
+  <TabItem value="oidc" label="OIDC provider">
+
+    This provider authenticates using OIDC protocol.
+
+    Users signed in using OIDC are created in Homarr.
+
+    Roles are fetched from group claims. This can also be changed to roles for example added to a azure app registration by using the `AUTH_OIDC_GROUPS_ATTRIBUTE`.
+
+    <details>
+      <summary>
+        Example Setup
+      </summary>
+      <div>
+
+        In this example we will be using [Authelia](https://github.com/authelia/authelia).
+
+        You can use any setup, but the simplest is [local](https://github.com/authelia/authelia/blob/master/examples/compose/local/authelia/configuration.yml).
+
+        You also have to [enable OIDC in Authelia](https://www.authelia.com/configuration/identity-providers/open-id-connect/).
+
+        Create a client for homarr. To generate client secret you can [use authelia](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-client-secrets). This is an example config:
+
+        ```yaml
+        identity_providers:
+        oidc:
+        ...
+        clients:
+        - id: homarr
+        secret: <secret_hash>
+        public: false
+        authorization_policy: one_factor
+        redirect_uris:
+        - https://example.com/api/auth/callback/oidc
+        - http://localhost:3000/api/auth/callback/oidc
+        scopes:
+        - openid
+        - groups
+        - profile
+        - email
+        userinfo_signing_algorithm: none
+        consent_mode: implicit # self hosted
+        ```
+
+        In Homarr use following env variables.
+
+        ```
+        AUTH_PROVIDERS="oidc"
+        AUTH_OIDC_ISSUER="https://auth.example.com"
+        AUTH_OIDC_CLIENT_SECRET="client_secret"
+        AUTH_OIDC_CLIENT_ID="homarr"
+        AUTH_OIDC_CLIENT_NAME="Authelia"
+        AUTH_OIDC_FORCE_USERINFO="true" --> from v4.39 of authelia and above this is required
+        ```
+
+        For an azure app registration the setup could look like this:
+
+        ```
+        AUTH_PROVIDERS="oidc"
+        AUTH_OIDC_ISSUER="https://login.microsoftonline.com/<teanant-id>/v2.0"
+        AUTH_OIDC_CLIENT_SECRET="<client-secret>"
+        AUTH_OIDC_CLIENT_ID="<client-id>"
+        AUTH_OIDC_CLIENT_NAME="Azure"
+        AUTH_OIDC_SCOPE_OVERWRITE="openid email profile" # Groups scope does not exist in azure
+        AUTH_OIDC_GROUPS_ATTRIBUTE="roles" # We use the roles of the app registration so that we don't need to use uuids as our groups
+        ```
+
+      </div>
+    </details>
+
+
+    ### Configuration
+
+    | Environment Variable        | Description                                                | Default value |
+    |-----------------------------|------------------------------------------------------------|---------------|
+    | ``AUTH_OIDC_ISSUER``        | Issuer URI of OIDC provider. This has generally to be **without trailing slash** except for **Authentik** | ---           |
+    | ``AUTH_OIDC_CLIENT_ID``     | ID of OIDC client (application)                            | ---           |
+    | ``AUTH_OIDC_CLIENT_SECRET`` | Secret of OIDC client (application)                        | ---           |
+    | ``AUTH_OIDC_CLIENT_NAME``   | Display name of provider (in login screen)                 | OIDC          |
+    | ``AUTH_OIDC_AUTO_LOGIN``    | Automatically redirect to OIDC login                       | false         |
+    | ``AUTH_OIDC_SCOPE_OVERWRITE`` | Overwrite default scopes (openid, profile, email)        | openid email profile groups           |
+    | ``AUTH_OIDC_GROUPS_ATTRIBUTE`` | Attribute used for groups (roles) claim                  | groups        |
+    | ``AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE`` | Overwrite name attribute. By default it will use preferred_username if it does not contain a `@` and otherwise name. | ---          |
+    | ``AUTH_OIDC_FORCE_USERINFO`` | Force userinfo endpoint to be used for user information.    | false         |
+    | ``AUTH_OIDC_ENABLE_DANGEROUS_ACCOUNT_LINKING`` | Enable account linking for OIDC provider. This will link the OIDC accounts by email. Be sure that you have verified emails to prevent stealing accounts. | false |
+    | ``AUTH_OIDC_TOKEN_ENDPOINT_AUTH_METHOD`` | Override method for the token endpoint authentication. Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt` and `none`. | client_secret_basic |
+
+    ### Permission System
+
+    To give a user special permissions, first create a new group in homarr and assign the permission desired.
+    For example if the group on homarr is called `homarr-admins` a new group on the oidc provider, for example authentik needs to be created with the same name, that would be `homarr-admins`.
+    After assigning the group on the oidc provider to the user, and logging again into homarr, the user should automatically get placed in that group and inherit the permissions defined.
+
+  </TabItem>
+</Tabs>
+
+## Example setups
+
+<Tabs>
+  <TabItem value="authentik" label="Authentik (OIDC) Example" default>
+
+    This example demonstrates how to use [Authentik](https://goauthentik.io/) as an OIDC provider for Homarr.
+
+    User and group management is handled within Authentik. Homarr synchronizes group memberships based on OIDC claims provided by Authentik. To grant administrative privileges, create a group in Authentik (e.g., `homarr-admins`) and add the relevant users. Then add the group with the same name in Homarr and assign the desired permissions to it.
+
+    <details>
+      <summary>
+        Example Setup
+      </summary>
+      <div>
+
+        **1. Configure Authentik:**
+
+        - Create an OIDC application in Authentik for Homarr.
+        - Set the redirect URIs to:
+          - `https://<your-homarr-domain>/api/auth/callback/oidc`
+          - `http://localhost:3000/api/auth/callback/oidc` (for local development)
+        - Record the client ID, client secret, and application slug.
+        - Create a group (e.g., `homarr-admins`) and assign users who require admin access.
+
+        **2. Example .env file:**
+        ```env
+        OIDC_CLIENT_ID=identificationid #OIDC client ID
+        OIDC_CLIENT_SECRET=secretsecretsecret #OIDC client secret
+        OIDC_SLUG=homarr #Application slug in Authentik
+        AUTH_DOMAIN=auth.example.com #Authentik FQDN
+        ADMIN_GROUP=homarr-admins #Authentik group for Homarr admins
+        HOMARR_FQDN=homarr.example.com #Homarr FQDN
+        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        ```
+
+        **3. Example Docker Compose configuration:**
+        ```yaml {14-26}
+        services:
+          homarr:
+            image: ghcr.io/homarr-labs/homarr:latest
+            container_name: homarr
+            restart: unless-stopped
+            ports:
+              - '7575:7575'
+            volumes:
+              - ./homarr:/appdata
+              - /var/run/docker.sock:/var/run/docker.sock:ro
+            environment:
+              - TZ=America/Los_Angeles
+              - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
+              - BASE_URL=https://${HOMARR_FQDN}
+              - NEXTAUTH_URL=https://${HOMARR_FQDN}
+              - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
+              - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
+              - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
+              - AUTH_OIDC_ISSUER=https://${AUTH_DOMAIN}/application/o/${OIDC_SLUG}/
+              - AUTH_OIDC_URI=https://${AUTH_DOMAIN}/application/o/authorize
+              - AUTH_OIDC_CLIENT_NAME=authentik
+              - AUTH_OIDC_SCOPE_OVERWRITE=openid email profile groups
+              - AUTH_OIDC_GROUPS_ATTRIBUTE=groups
+              - AUTH_LOGOUT_REDIRECT_URL=https://${AUTH_DOMAIN}/application/o/${OIDC_SLUG}/end-session/
+              - AUTH_OIDC_AUTO_LOGIN=true #To sign in with Authentik automatically
+            networks:
+              - my-network
+        networks:
+          my-network:
+            external: true
+        ```
+
+        **4. Additional Notes:**
+        - Ensure both Authentik and Homarr are accessible via the specified FQDNs.
+        - The `AUTH_OIDC_GROUPS_ATTRIBUTE` should correspond to the claim in Authentik that contains group names (typically `groups`).
+        - Your user will automatically be placed in groups that have the same name as those of authentik. So simply create them in Homarr and give them the permissions you want.
+        - For further information, refer to the [Authentik OIDC documentation](https://goauthentik.io/docs/providers/oauth2/).
+
+      </div>
+    </details>
+
+    Additional OIDC configuration options are described in the OIDC tab above.
+
+  </TabItem>
+  <TabItem value="google" label="Google (OIDC) Example" default>
+
+    This example demonstrates how to use [Google Auth Platform](https://console.cloud.google.com/auth/overview) as an OIDC provider for Homarr.
+
+    Unfortunately Google does not support synchronization of group membership. See https://issuetracker.google.com/issues/133774835?pli=1.
+
+    <details>
+      <summary>
+        Example Setup
+      </summary>
+      <div>
+
+        **1. Setup (Google):**
+
+        - Create a Project in [Google Cloud Console](https://console.cloud.google.com/) for Homarr  and switch to that Project.
+        - Configure [Authorized Domains](https://console.cloud.google.com/auth/branding) and set it to `<your-homarr-domain>`.
+        - Create a new [OAuth Client](https://console.cloud.google.com/auth/clients):
+          - Select Application Type `Web`
+          - Set the redirect URI to `https://<your-homarr-domain>/api/auth/callback/oidc`
+        - Record the `Client-ID` and `Client Key` (secret).
+
+        **2. Example .env file (Homarr):**
+        ```env
+        OIDC_CLIENT_ID=identificationid #Google Client-ID
+        OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret)
+        HOMARR_FQDN=homarr.example.com #Homarr FQDN
+        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        ```
+
+        **3. Example Docker Compose configuration (Homarr):**
+        ```yaml {16-22}
+        services:
+          homarr:
+            image: ghcr.io/homarr-labs/homarr:latest
+            container_name: homarr
+            restart: unless-stopped
+            ports:
+              - '7575:7575'
+            volumes:
+              - ./homarr:/appdata
+              - /var/run/docker.sock:/var/run/docker.sock:ro
+            environment:
+              - TZ=Europe/Berlin
+              - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
+              - BASE_URL=https://${HOMARR_FQDN}
+              - NEXTAUTH_URL=https://${HOMARR_FQDN}
+              - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
+              - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
+              - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
+              - AUTH_OIDC_ISSUER=https://accounts.google.com
+              - AUTH_OIDC_CLIENT_NAME=Google
+              - AUTH_OIDC_SCOPE_OVERWRITE=openid email profile
+              - AUTH_OIDC_NAME_ATTRIBUTE_OVERWRITE=name
+            networks:
+              - my-network
+        networks:
+          my-network:
+            external: true
+        ```
+      </div>
+    </details>
+
+    Additional OIDC configuration options are described in the OIDC tab above.
+
+  </TabItem>
+</Tabs>

apps/docs/docs/advanced/styling/index.mdx

@@ -0,0 +1,94 @@
+# Styling
+
+:::tip
+
+This page is directed at more experienced users with knowledge about CSS and browsers.
+We recommend you to [look into the board customizations instead](/docs/management/boards#appearance),
+if you do not have experience with writing custom styles or CSS.
+
+:::
+
+:::warning
+
+Our support specifically excludes custom CSS, and we will not help you to write CSS.
+However, we may help you by adding new CSS classes if required.
+
+:::
+
+Homarr uses https://mantine.dev/ under the hood. You can change the look & feel of Homarr
+using custom CSS, that extends or overwrites the styles from Mantine.
+
+## Getting into CSS
+If you don't have any experience with CSS,
+we strongly recommend you to go through the courses here: https://www.w3schools.com/css/.
+Due to the infinite scenarios and setups possible with custom CSS,
+our support team will not provide any support with your own written CSS.
+
+## Limitations and dangers
+When using custom CSS, you can break the page or certain functionalities.
+Although CSS can improve the design & feel of the page, it **<ins>cannot do any of the following</ins>**:
+
+- Implement new features, widgets or integrations
+- Securely hide elements you don't want users to interact / have permission to
+- Completely revamp the design of the page, only smaller changes are possible
+
+Here are some dangers of using custom CSS:
+- Updates may contain breaking changes in the structure, built-in styling or how styling is processed. Therefore,
+custom CSS may break unexpectedly without any warning
+- Custom CSS may make certain elements invisible or not possible to click / interact with
+- Custom CSS could make readability and accessibility worse for impaired people
+
+## How to inspect the page
+When styling the page, you can use the ``Inspector`` to inspect elements on the page and try out styles.
+This may vary depending on your browser and operating system, but the workflow usually goes like this:
+
+- Open the Homarr page
+- Press ``Ctrl`` + ``Shift`` + ``I`` at the same time.
+Alternatively, right-click on the page and choose ``Inspect`` or ``Inspect element``.
+- Open the tab ``Elements`` if it isn't open yet.
+- Search the element you want to change in the DOM tree or use the element picker (usually at the top left)
+to select it by clicking on the page.
+- Experiment by changing the CSS code on the right side
+
+When writing custom CSS, it is important to also remember or create a selector, which tells the browser
+which element to apply the styles to. If you accidentally broke something or want to revert your changes in the inspector,
+simply reload the page.
+
+## Using Homarr's classes
+Homarr's elements will already have a lot of classes and styles pre-applied.
+You can reuse those classes to apply additional styles or overwrite them.
+When overwriting, remember to add the ``!important`` flag  to your CSS property to tell the browser to use our instruction instead.
+
+Classes with random number suffixes, such as ``mantine-Card-x2fske``, should be avoided, since those are dynamic
+CSS classes that will change with every build. This means, every time you update Homarr,
+your styles will no longer apply to them
+
+## Defining custom classes for widgets
+If you want to apply the styles only for one widget, you can define custom class names only for that widget.
+To do that, enter edit mode on your board, click the three dots of your widget, click ``Edit item`` and click ``Advanced options``.
+Then, you can enter as many custom classes as you'd like:
+
+![](./img/widget-custom-classes.png)
+
+To save them, click `Save changes` on both modals and exit edit mode.
+
+## Where to enter custom CSS
+After you wrote your custom CSS, it is time to permanently save it, so you don't need to use the inspector anymore.
+To do this, enter the board settings:
+
+![](./img/enter-board-settings.png)
+
+Scroll down a bit and click on custom CSS.
+Here you can enter your CSS code, which will be applied on the respective board page.
+
+![](./img/custom-css-setting.png)
+
+## Using variables
+You can also change the values of the theme variables, which are located here: https://mantine.dev/styles/css-variables-list/.
+To do this, see the following example CSS:
+
+```css
+:root {
+    --mantine-primary-color-filled: #ffbb00;
+}
+```

apps/docs/docs/community/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Community",
+  "position": 5,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index"
+  }
+}

apps/docs/docs/community/donate.mdx

@@ -0,0 +1,25 @@
+---
+title: Donate
+tags:
+  - Community
+  - Donation
+  - OpenCollective
+---
+
+# Donate
+## Why to donate
+Our team of 4 developers is working on Homarr in their free time.
+Homarr has become a big part of our daily things we work on - and therefore we invest a lot of time into maintaining Homarr,
+providing support and implementing new features.
+We also incur monetary costs while developing Homarr for the tools that we need.
+A few examples include:
+- Renting for a Cloud VPS for our cloud services (status page, monitoring, email, analytics, [demo instance](https://demo.homarr.dev/), ...)
+- Paying for (IDE-) licenses
+
+Using a donation, you help us to cover these expenses and enable the development of Homarr.
+Homarr is completely free to use. We'd highly appreciate if you consider donating, especially if you use Homarr in a commercial environment.
+
+## Where to donate
+We accept donations on our official [OpenCollective](https://opencollective.com/homarr).
+You may also sponsor us directly by providing a useful service / product to us other means.
+You can get into contact with us [here](./get-in-touch).

apps/docs/docs/community/faq.mdx

@@ -0,0 +1,90 @@
+---
+title: Frequently Asked Questions
+tags:
+  - Community
+  - Help
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+### Can I install Homarr on a Raspberry Pi?
+Yes, Homarr is compatible with the architecture of the Raspberry Pi. Have a look in our <a href="/docs/category/installation-1">installation guide</a> on how to do so.
+
+### I have a suggestion / idea for improvement or want to report a bug
+You can report issues, suggestions, or ideas for improvements <a href="https://github.com/homarr-labs/homarr/issues/new/choose">here</a>.
+
+### Can I use my own custom icons for apps?
+Yes, check out our guide on <a href="/docs/advanced/customizations/icons">how to add your custom icons</a>.
+
+### Some of my online icons are not working (anymore)
+It seems the `cdn.jsdelivr.net` database of icon sometimes appear in the lists for DNS-Holes (PiHole, AdGuard Home...). <br />
+So make sure to manually whitelist this address.
+
+### Can I add my own widgets? Do I need programming skills?
+We have decided, not to support custom widgets, until Homarr is in a stable and highly polished state.
+Enabling users to write their own widgets is easy at the first glance, but there are some major issues with it:
+
+- There are mainly two options for adding plugins or custom widgets to Homarr. The first option is, to allow and inject custom code in Homarr. Apps like Nextcloud can do this easily, because they use the Runtime to render all components of the application (In reality, the process is still a bit more complicated). In contrast, Homarr is using Next.js - a framework that needs to be compiled in production. That means, that each time you would modify a custom widget or plugin, the app would have to be restarted. There are options to avoid this, but they are quite flakey and bring disadvantages in our experience. The second option is, to write widgets declaratively instead of imperatively. This way, we would be able to render and modify widgets without any restarting at all. However, we'd have to write our own interpreter for said declarative schema. This is totally possible, but requires a lot of planning and architecture design to function properly. The required work to implement either option is therefore quite substantial.
+- Custom widgets would need to be able to request data, so they work properly. We use tRPC for this. Many APIs use different formats and we'd have to convert and read those.
+- Using custom widgets, one could easily create harmful widgets, leak your personal data (potentially including your tokens) and trick your users. A proper implementation (eg. official plugin store, where we can ban harmful widgets from) would resolve this problem to a certain extent, but again requires additional work and time to be put in.
+
+If you still want to add a widget, please consider to contribute it directly to Homarr. For that, basic programming skills are required. Our [Developer Guides](/docs/advanced/development/getting-started) explain this even more detailed.
+
+### Is it secure to expose Homarr to the web?
+
+Yes, since v0.14.0, we are confident that Homarr is secure enough to be exposed to the web. 
+Make sure to enable the "allow anonymous access" [option in the settings](/docs/management/boards#access-control), if you want to allow people without an account to be able to see your dashboard (not edit)
+
+### How do I open the console / log?
+There are two different sources of information:
+- console: This is your client (browser). It can tell us, if there is an issue on the client (crash, bug, ...).
+- log: This is your server. It will tell us, if there are issues with connections for the integrations, crashes and errors.
+
+Both variants *can* contain personal data. It's recommended, that you don't post them publicly or remove personal data from it.
+
+<Tabs>
+  <TabItem value="apple" label="Read console" default>
+
+> Note: This will not work on most mobile browsers.
+
+Open your browser and ensure, that Homarr is your current tab.
+Press ``CTRL`` + ``SHIFT`` + ``I`` on your keyboard. If this shortcut doesn't work, please use one of the alternatives: https://developer.chrome.com/docs/devtools/open/.
+Click on ``Console`` in the new window, that opened. There, you should see white, orange and sometimes red messages. You can use the Windows Snip & Sketch tool (or your respective tool on Linux / MacOS) to screenshot those messages.
+
+> Please never execute any commands in the console. Scammers are using the console to let you execute harmful commands. If you want to resolve an issue in Homarr, **you'll never have to execute any commands here**
+
+  </TabItem>
+  <TabItem value="orange" label="Read log">
+
+This depends on your installation method. If you use Unraid, you can simply click on the App and on ``Log``. If you have a bare Docker install, use ``docker container logs homarr``. If you used a different name than ``homarr`` for your container, you need to replace said argument. Here is some additional information about the command: https://geekflare.com/check-docker-logs/.
+
+  </TabItem>
+</Tabs>
+
+### How do I post logs?
+Please check [the section above](#how-do-i-open-the-console--log), on how to obtain logs. Logs should always be posted to https://pastebin.com/ or https://rentry.co/.
+
+### Can I use Homarr at my company?
+Yes, you can! But please consider a donation, if our work has been useful to you.
+
+### I think I found a bug. What can I do?
+If you think, that you found a bug, please create an issue <a href="https://github.com/homarr-labs/homarr/issues/new/choose">here</a>.
+
+### Why can't I use my custom icons?
+You need to restart the Homarr Docker container after adding icons.
+
+### Why can't homarr see/ping containers running locally behind GluetunVPN?
+This is because GluetunVPN, and many other docker VPN services, secure their VPN connections with strict firewalls. These firewalls often block access to local containers, even on the same docker network. The workaround for <a href="https://github.com/qdm12/gluetun-wiki/blob/main/setup/options/firewall.md">GluetunVPN</a> is to add "- FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24" into the environmental variables of the docker compose file. If you are using a firewall on your system, you will need to add a rule that allows requests from ip's in the range of 192.168.xxx.xxx . If you are using UFW the command would be "sudo ufw allow from 192.168.0.0/16".
+Tip: If you are running your torrent client behind a VPN, and running Sonarr (or something similar) normally, make sure to open your torrent client's port in your firewall. If you don't, Sonarr will not be able to see it. Furthermore, use your machines IP (192.168.x.x) rather then 127.0.0.1 or localhost.
+
+### Can I get in touch with you?
+Yes, go <a href="/docs/community/get-in-touch">here</a> to get with us in touch.
+
+<hr/>
+
+:::tip
+
+Haven't found the solution to your problem / question? We are eager to help you on [our Discord](/docs/community/get-in-touch#discord) or in a [GitHub Issue](https://github.com/homarr-labs/homarr/issues/new/choose).
+
+:::

apps/docs/docs/community/get-in-touch.mdx

@@ -0,0 +1,24 @@
+---
+title: Get In Touch
+description: Still have a question? Click here!
+tags:
+  - Help
+  - Community
+---
+
+We're happy to talk with you! Shoot us a message at the following places:
+
+## E-Mail
+We are open to discuss sponsorships, security vulnerabilities and other private requests through our email.
+Please do not report any bugs / feature requests here - they will be ignored and deleted.
+
+[homarr-labs@proton.me](mailto:homarr-labs@proton.me)
+
+## Discord
+We have a Discord Server, where we announce new releases, discuss features and bugs and show off our dashboards.
+There are over 4'000 members and we're happy to answer your questions or concerns.
+You're also open to discuss new / upcoming features and any offtopic selfhosting content.
+
+[_![](https://discordapp.com/api/guilds/972958686051962910/widget.png?style=banner2)_](https://discord.gg/aCsmEV5RgA)
+
+

apps/docs/docs/community/license.mdx

@@ -0,0 +1,233 @@
+---
+title: License
+tags:
+  - Community
+---
+
+Homarr is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+## TL;DR
+| Action         | Allowed |
+| -------------- | ------- |
+| Copy           | ✅      |
+| Modify         | ✅      |
+| Distribution   | ✅      |
+| Commercial Use | ✅      |
+| Private Use    | ✅      |
+| Attribution    | ✅      |
+| Liability      | ❌      |
+| Warranty       | ❌      |
+
+:::note
+
+Please consider [making a donation](/docs/community/donate) to Homarr, if this project has been useful for your needs. Donations help us to keep Homarr up to date, implement new features and help our users with problems and questions.
+
+:::
+
+
+
+## Full License
+
+```txt
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2025 Meier Lukas, Thomas Camlong and Homarr Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+```

apps/docs/docs/community/translations.mdx

@@ -0,0 +1,53 @@
+---
+title: Translations
+tags:
+  - Community
+  - Translations
+---
+
+We want to make Homarr accessible for everyone. 
+But to do that, we need your help. 
+We are running a community program that enables everyone to translate Homarr into their language – no programming required. 
+We are using [Crowdin](https://crowdin.com/) to manage our translations. 
+You can find the translations [here](https://translate.homarr.dev/).
+
+## How to translate
+
+
+### Using crowdin's online platform
+Go to the [Crowdin translations](https://translate.homarr.dev/) and select a language you want to translate. 
+You can then enter the translation mode and start translating. 
+After you've submitted your translations, a Proofreader will review your changes. 
+After a translation has been approved, it will be merged to the language development branch. 
+We merge this one periodically to the development branch. 
+After the next update of Homarr, all changes from the development branch will be merged, including the changes in the translations.
+
+### Using live translate
+You can also help translate homarr directly from the app!
+For this you can simply change your language to "Crowdin (live translations)"
+
+![](./img/crowdin-language-select.png)
+
+Then you'll be prompted to connect to your Crowdin account and choose the language in which you want to transalte. 
+You can then start translating directly from the app by selecting some text on the app.
+If some text cannot be selected to be edited with the live translation tool, you can still translate it inside of the In-Context popup at the Home tab, it will be red if it's not translated yet.
+
+![](./img/crowdin-live-translate.png)
+
+:::caution
+Although you are translating directly from the app, your translations will not be directly be available inside of your language, they will be in the next update of Homarr, because we have to push the new translations to a new docker image.
+
+If you really want to use them you can enable the "preview transaltions" option in the live translate settings, but be aware that this is not recommended for performance reasons.
+:::
+
+:::tip
+
+Do you want to become a proofreader? [Let us know on our Discord](/docs/community/get-in-touch#discord)! We will add you to the proofreader team. You can then review the translations and approve them. **Note:** You must speak the language fluently, have it as your native language or lots of experience with it.
+
+:::
+
+## Guidelines
+1. Translate with context: Some translations can't be translated 1:1 - they need context. Ensure that your translations make sense in the context.
+2. Keep things simple and original - no additional characters are needed.
+3. Don't translate the same thing twice - if you see a translation that is already translated, don't translate it again unless you have a better translation.
+5. Keep your translations as close to the original as possible.

apps/docs/docs/getting-started/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Getting started",
+  "position": 1,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Getting started"
+  }
+}

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -0,0 +1,359 @@
+---
+title: After the installation
+sidebar_position: 3
+tags:
+  - Getting started
+  - Configuration
+---
+
+import imageStartFromScratchStepServerSettings from "./img/onboarding-from-scratch-step-server-settings.png";
+import imageStartFromScratchStepAdminUser from "./img/onboarding-from-scratch-step-admin-user.png";
+import imageStartFromScratchStepExternalAdminGroup from "./img/onboarding-from-scratch-step-external-admin-group.png";
+import imageStartFromScratchStepFinish from "./img/onboarding-from-scratch-step-finish.png";
+import manageBoardHeaderEditMode from "./img/manage-board-header-edit-mode.png";
+import manageBoardHeaderAddItem from "./img/manage-board-header-add-item-menu.png";
+import manageBoardHeaderChooseItem from "./img/manage-board-header-choose-item.png";
+import manageBoardNoApp from "./img/manage-board-no-app.png";
+import manageExportOldHomarr from "./img/old-homarr-export-data.png";
+import manageImportOldHomarrDropzone from "./img/old-homarr-import-dropzone.png";
+import manageImportOldHomarrChooseData from "./img/old-homarr-import-choose-imported-data.png";
+import manageImportDecryptionToken from "./img/old-homarr-import-decryption-token.png";
+
+:::tip
+
+Read our [glossary](./glossary) if you are new to Homarr.
+
+:::
+
+Congratulations on installing Homarr. Now it's time to get yourself familiar with the concepts of Homarr and how to use it.
+
+## Onboarding
+The onboard will show the first time you start Homarr.
+This process will help you with your first steps and adding some initial data, such as the administrator account.
+
+:::note
+
+If you see this screen repeatitly after you restarted the Homarr container, your Docker mounting paths may be missing,
+incorrect or read-only. Read [our installation instructions](/docs/getting-started/installation/docker) again to fix this issue.
+
+:::
+
+You can either import a previous dashboard using the ZIP archive or start from scratch:
+
+![Screenshot of Step 1 onboarding](./img/onboarding-step-1.png)
+
+You may refresh anytime and continue from a different device - the onboarding is saved immediately on the server for your convenience.
+
+### Starting from scratch
+Depending on your auth provider configuration you will either first see the admin user creation form or the external group creation form.
+If credentials provider was selected, you'll be prompted to create an admin user for Homarr.
+This user cannot be deleted and has full control over Homarr and all of it's boards.
+You must choose an username and password (both can later be changed).
+We enforce strict password requirements, when you enter your password, to protect your instance if you accidentially
+expose it to the Internet.
+
+<img src={imageStartFromScratchStepAdminUser} alt={"Screenshot form to create admin user"} width={300} />
+
+If you selected external providers (such as LDAP or OIDC), you'll be prompted to create an admin group.
+This group will be used to synchronize users from your provider to Homarr. 
+When a user is logged in through the provider the groups of him that match groups with any in Homarr will be added to the user.
+The name of the group has to match exactly the name of the group in the provider.
+
+<img src={imageStartFromScratchStepExternalAdminGroup} alt={"Screenshot form to create external admin group"} width={300} />
+
+Next, you can configure some basic settings for Homarr. We recommend to leave all settings at default for most users.
+Here you can also disable analytics. Please note that our analytics are completly anonymous and is fully compliant with GDPR and PECR.
+
+<img src={imageStartFromScratchStepServerSettings} alt={"Screenshot of analytics and indexing settings in the onboarding"} width={300} />
+
+### Setting up integrations
+
+After configuring server settings, the onboarding guides you through setting up your integrations.
+
+#### Docker service discovery
+If Docker is available (socket mounted), Homarr automatically detects running containers and matches them to known integration types.
+Matching integrations are pre-selected in the integration list, saving you from manually picking each one.
+
+#### URL templating
+You can define a base URL template to auto-fill integration URLs in bulk.
+Two modes are supported:
+- **Subdomain mode** — e.g. `{app}.example.com` where `{app}` is replaced with the integration name
+- **Port mode** — e.g. `192.168.1.1:{port}` where `{port}` is replaced with the integration's default port
+
+#### API key helper links
+For integrations that require API keys (such as Sonarr, Radarr, SABnzbd, or Seerr), a helper link opens the relevant settings page in the target application so you can quickly copy your key.
+
+#### Creating apps from Docker containers
+You can optionally auto-create bookmark apps for all discovered Docker containers, making them immediately available on your board.
+
+:::note
+
+Some niche and registry integrations (GitHub, npm, Docker Hub, GitLab, Codeberg, LinuxServer.io, GHCR, Quay, Search.ch) are hidden from the onboarding selection grid but remain available on the manage integrations page.
+
+:::
+
+After this step, you finished the onboarding.
+The onboarding can no longer be started again.
+From here you can click on one of the provided links to continue your journey.
+We recommend you to continue with the section [creating your first board on this page](#creating-your-first-board).
+
+<img src={imageStartFromScratchStepFinish} alt={"Screenshot of the finish onboarding process with links"} width={300} />
+
+### Importing a ZIP from version before 1.0.0
+This is recommended when you used Homarr before and want to re-import your data.
+It is important that you first migrate correctly using [the list of breaking changes for 1.0](/blog/2024/09/23/version-1.0).
+
+<img src={manageExportOldHomarr} alt="Export from old Homarr" style={{ maxWidth: 500 }} />
+
+**How to export and import data**
+1. Navigate to your old Homarr, open your management pages, open the tools submenu and open ``Migrate to 1.0``.
+2. Check the contents that you want to export. We recommend you to export all data.
+3. Click on the export data button
+4. Save the ZIP file, that is being downloaded, on your device. If you selected "integrations" or "users", you also get an encryption / decryption key.
+Copy it and do not loose it!
+5. Go to your new >1.0.0 Homarr instance and start the onboarding. Choose ``Import from Homarr before 1.0``
+6. Drag and drop your previously downloaded ZIP archive into the file upload: <br/><img src={manageImportOldHomarrDropzone} style={{ maxWidth: 500 }} />
+7. Next, choose the data that you want to import and how to import it. Since screen sizes were removed in 1.0, we create a new board for every screen size by default. We recommend you to only keep the best layout and adjust it later in 1.0.0 - but you can also import all of them and pick later.<br/><img src={manageImportOldHomarrChooseData} style={{ maxWidth: 500 }} />
+8. If you previously exported integrations or users, you will be asked to decrypt the data safely using your obtained encryption token. Paste into the modal and confirm your action.<br/><img src={manageImportDecryptionToken} style={{ maxWidth: 500 }} />
+9. Next, you can [follow the same setup as when starting from scratch](#starting-from-scratch). After you completed the onboarding, all of your data will be migrated and available.
+
+## Creating your first board
+In Homarr, you organize your apps and widgets on boards.
+Boards can be organized using the interactive drag and drop.
+Let's create your first board by navigating here: ``Manage`` > ``Boards`` > ``New board``:
+![](./img/manage-create-board-button.png)
+
+A board must always have a name and can either be public or private.
+Public boards are also accessible for users, that are not logged in ([see access control for boards](/docs/management/boards/#access-control)).
+
+![](./img/manage-create-board-modal.png)
+
+Congratulations - you've just created your first board. You can see boards, that you have access to, on this page:
+
+![](./img/manage-view-board.png)
+
+## Add your first app to Homarr
+To add links to your dashboard, you must first add them as an "app".
+Navigate to this page to add an app:
+
+![](./img/manage-navigate-apps.png)
+
+Next, click on the ``New app`` button. You'll need to provide a name and an icon to create an app.
+The name must be at least one character long but you can provide any image URL for the icon.
+Homarr ships with over 11K icons - so you can just search by entering a search text instead.
+
+![](./img/manage-add-app-form.png)
+
+After you created the app, you'll see in on the apps page:
+
+![](./img/manage-created-app.png)
+
+## Arrange and organize your board
+Let's add your freshly created app, from the previous step, to the board.
+To do this, edit your previously created board by clicking on the big ``Open board`` button:
+
+![](./img/manage-view-board.png)
+
+Here you have the following options in the header:
+
+![](./img/manage-board-header.png)
+
+- **Search**: Here you can search for data. You can search for integrations, boards, actions, sites and much more. Some actions may be context dependent (eg. will only show when certain widgets are on your page)
+- **Edit mode**: Clicking this button will toggle the edit mode. In this mode you can edit the contents of your board.
+- **Settings**: Clicking this button will redirect you to a settings page where you can adjust the board settings (page title, colors, ...).
+- **Profile**: This avatar will be visible on every page. Clicking it will show a menu with actions.
+
+When entering the edit mode, you'll get some additional buttons to work with:
+
+<img src={manageBoardHeaderEditMode} alt={"Screenshot of buttons in the edit mode"} width={200} />
+
+- **Add item**: Click this button to add new elements to your page.
+- **Exit edit mode**: Click this btuton to save your changes and exit edit mode.
+
+To continue, click the option "New Item":
+
+<img src={manageBoardHeaderAddItem} alt={"Screenshot of the add item menu"} width={200} />
+
+Next, you can choose what item you'd like to add.
+We will discuss the other options in the following sections - for now choose "App" to continue.
+
+<img src={manageBoardHeaderChooseItem} alt={"Screenshot of choosing the app item in the modal"} width={300} />
+
+As soon as you chose the app, the modal will close and you'll get the following item on your board:
+
+<img src={manageBoardNoApp} alt="Screenshot of the No app element on the board" />
+
+This is expected, because you haven't told Homarr what app it should show in this item.
+To configure this, click on the small 3 dots at the top of the item in the edit mode and choose "Edit item" in the menu.
+
+![](./img/manage-board-edit-app.gif)
+
+In the modal you can edit the app that you want to display:
+
+![](./img/manage-board-choose-app.png)
+
+As soon as you save your changes, the tile on the board will refresh and display your app.
+Using the small bidirectional arrow at the bottom right you can resize the element.
+Start pressing with your mouse button down, move your mouse to resize and release your finger as soon your you're happy with the size.
+
+![](./img/resize-item.gif)
+
+To move your item to a different position on the board, simply hold the mouse button anywhere on the item and move with the mouse to the desired position.
+As soon as you release your finger, the item will snap in place in the grid.
+
+![](./img/move-item.gif)
+
+:::note
+
+You cannot move items freely on the vertical axis.
+We always align all items to the top of the page to simply organization.
+To move items to the bottom, you must add more items or resize items.
+
+:::
+
+:::tip
+
+We recommend you to experiment for a few minutes, before you start building your actual dashboard.
+This helps you to explore the capabilities of Homarr before you build your board in a suboptimal way.
+
+:::
+
+Users on touch or mobile devices may not be able to drag and drop or move items.
+They can use the "Move / resize item" option in the edit menu of items instead:
+
+![](./img/manage-board-move-resize-item-menu.png)
+
+Be sure to save your changes by exiting edit mode!
+
+![](./img/exit-edit-mode.png)
+
+## Adding your first integration
+Now it's time to integrate some basic data into your board.
+To do this, we first need to create an integration.
+An integration is a connection between Homarr and a third party application - usually something that you run and deploy yourself.
+
+Navigate to ``Manage`` > ``Integrations`` (for example via your user menu).
+As an example, we are going to use the public demo instance of **Dash.** - a popular application to monitor CPU / hardware usage.
+Choose the **Dash.** integration from the list of available integrations:
+
+![](./img/choose-integration.gif)
+
+Next, choose a name (or leave it at default), enter ``https://dash.mauz.dev/`` as the URL in the form and click on ``Test connection and create``.
+Pressing the save button will perform a test request to the integration, to confirm that the networking setup is working as expected.
+Sometimes invalid configurations, firewalls and other mistakes can lead to connectivity problems - [follow this guide here](/docs/management/integrations/#troubleshooting-connection) if you experience issues.
+
+If connection was successful, you will be redirect back to the list of integrations.
+Now let's embed it to your board (see next section).
+
+:::note
+
+Some integrations may require additional configuration, such as a username, password or API tokens.
+Depending on your networking setup and applications, the connection from Homarr might also get blocked by firewalls,
+the target application or your router.
+
+:::
+
+## Embed integration data using widgets
+Let's add your integration, that you have configured in the section above, as a widget to your board.
+First, navigate back to your board that you want to add it to.
+Next, enter edit mode again and add another item to your board:
+
+![](./img/manage-board-header-add-item-menu.png)
+
+Instead of choosing an app, let's choose ``System Health Monitoring`` this time.
+Click on "Add to board":
+
+![](./img/manage-board-header-choose-system-health.png)
+
+Resize the item slightly and then edit it using the three dots menu at the top:
+
+![](./img/edit-system-health-widget.gif)
+
+Next, choose your newly created Dash. integration in the integrations dropdown:
+
+![](./img/manage-board-edit-system-health.png)
+
+:::note
+
+Some widgets may support multiple integrations at the same time.
+If they do not support multiple integrations, you will be unable to select more than one.
+
+:::
+
+Confirm your changes by pressing save.
+Editing a widget will trigger a data update and data will soon appear:
+
+![](./img/widget-system-health.png)
+
+As with every change, don't forget to save your changes using the exit edit mode button:
+
+![](./img/exit-edit-mode.png)
+
+## Grouping your items
+As the last step, let's organize your freshly created items using two different options.
+You can choose either or both of them on your boards.
+
+### Using dynamic sections
+Dynamic sections are a simple, resizable visual group to group items.
+
+![](./img/create-dynamic-section.png)
+
+After adding a dynamic section, you can simply drag and drop items into the section:
+
+![](./img/dynamic-section.gif)
+
+### Using categories
+Categories are more advanced and complicated than dynamic sections.
+To create a category, open the add item modal and choose "new category":
+
+![](./img/add-category.png)
+
+Every category must have a name. After you click "Add category", you will get a new item on your board:
+
+![](./img/category.gif)
+
+You can drag and drop items in to this category in the edit mode.
+Categories will have a big space before and after them in the edit mode to
+enable you to drag and drop items outside the category.
+You can also collapse or open categories in edit mode to facilitate your editing process.
+
+:::note
+
+A current limitation of categories is, that they will always have a width of 100%.
+You cannot reduce their horizontal width.
+
+:::
+
+## Guided tours
+
+After completing the onboarding, Homarr provides interactive guided tours to help you discover key features.
+
+### Management tour
+When you first visit the management area (`/manage`), Homarr walks you through the main pages: boards, apps, integrations, and users (admin only).
+Each page highlights the list view and the create action so you know where to find and add things.
+
+### Board tour
+When you first open a board, a tour highlights the board header elements: search, edit mode, settings, board switcher, and user menu.
+
+### Tour controls
+- Press **Enter** (or click **Next**) to advance through tour steps
+- Tours auto-start on first visit and do not repeat once completed
+- Tours are skipped on mobile screens (below `sm` breakpoint)
+- You can **reset tours** from the user settings page under **Manage > Users > [Your user] > General**
+
+## Next steps
+You're done with the basic setup 🔥. Now it's time to organize and customize even more.
+We highly recommend you to experiment with different options, styles and configurations.
+See these curated pages for your next steps:
+- Create new apps using the [apps management](../management/apps/)
+- Customize your board or add more boards using the [boards management](../management/boards/)
+- Integrate software that you use using the [integrations management](../management/integrations)
+- Choose from our beautiful and interactive [widgets](/docs/category/widgets)
+- See [all supported integrations](/docs/category/integrations)
+- Integrate with Homarr with your own application using [the API](../management/api/)
+
+:::danger
+
+The Homarr Team will never ask for your credentials. Do not send people your credentials, as they manage the access to your applications and can cause harm to your device if they are abused.
+
+:::

apps/docs/docs/getting-started/glossary.mdx

@@ -0,0 +1,12 @@
+# Glossary
+In the glossary, you'll learn the different components and their names of Homarr.
+
+| Term            | Definition                                                                                                     |
+|-----------------|----------------------------------------------------------------------------------------------------------------|
+| Apps            | An piece of software that you or a third party hosts (eg. Google)                                              |
+| Integration     | A connection to a service outside of Homarr                                                                    |
+| Dynamic section | Resizeable area where items on your board can be placed and grouped                                            |
+| Widget          | A tile that uses your integrations to display data or enables you to interact with with them                   |
+| Edit mode       | Temporary state that you can enter where you can drag and drop, edit or customize your board                   |
+| Board           | Customizable page which can be edited using the edit mode. This is where apps, sections and widgets are placed |
+| Tasks           | Workloads that are performed in the background - even if there is no user present                              |

apps/docs/docs/getting-started/index.mdx

@@ -0,0 +1,44 @@
+---
+title: Prerequisites
+sidebar_position: 1
+tags:
+  - Getting Started
+  - Installation
+  - Docker
+  - Unraid
+---
+
+import Link from '@docusaurus/Link';
+import { IconArrowRight } from '@tabler/icons-react';
+
+Before you try to install Homarr, please review if your device meets the requirements.
+Installing on an unsupported device may lead to unstable behaviour and no support will be provided.
+
+## Hardware
+- At least 500MB RAM
+- At least 600MB of free disk space for the Docker image. SSD is preferred.
+- Single or dual core CPU
+- Stable network connection, Wi-Fi use is not recommended
+
+## Architecture
+
+We build Homarr for a bunch of different architectures, including ARM. Please ensure that your device architecture is supported by Homarr. We won't be able to provide support for unusual or outdated architectures.
+
+| Architecture | Supported       |
+|--------------|-----------------|
+| linux/amd64  | ✅ Supported     |
+| linux/arm64  | ✅ Supported     |
+| linux/arm/v7 | ❌ Not supported |
+
+## Getting started with installation
+
+<Link
+  data-attr="Go to installation"
+  className={'button button--secondary button--lg rounded-3xl dark:border-zinc-600 dark:bg-zinc-800'}
+  to="/docs/category/installation-1"
+>
+  <div className={'flex items-center gap-3'}>
+    <span className={"dark:text-gray-200"}>Go to Installation</span>
+    <IconArrowRight className={"dark:text-gray-200"} size={20} />
+  </div>
+</Link>

apps/docs/docs/getting-started/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Installation",
+  "position": 1,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "title": "Getting started"
+  }
+}

apps/docs/docs/getting-started/installation/docker.mdx

@@ -0,0 +1,105 @@
+import { DockerInstallSnippet } from '@site/src/components/pages/installation/docker/dynamic-docker-install'
+
+# Docker
+Docker is our recommended installation method for beginners and professionals.
+It is easy to use, ships with all dependencies inside a single container and is easy to use and maintain.
+It requires at least some basic knowledge of [Docker](https://www.docker.com/).
+We recommend [NetworkChuck's Docker Containers 101](https://www.youtube.com/watch?v=eGz9DS-aIeY) as a good start for complete beginners.
+
+## Docker compose
+### Prerequisites
+
+- A Linux or Windows based system that meets the [hardware prerequisites](/docs/getting-started/#hardware) and [architecture prerequisites](/docs/getting-started/#architecture).
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Compose](https://docs.docker.com/compose/install/) - *preinstalled on many systems nowadays*
+
+### Installation
+
+<DockerInstallSnippet data-visual-test="blackout"/>
+Finally, run ``docker compose up -d`` in the same directory. This will start the Homarr container in the background.
+
+:::caution
+
+Docker compose creates a network by default. Some integrations may not work (specifically Dash.) when the network internal hostname is used since clients do not know this name. It is recommended that you either use a local network wide hostname or the IP directly. An alternative is to create a DNS record with the same internal compose stack hostname for all clients outside.
+
+:::
+
+### Updating
+
+To update, navigate to the directory with the ``docker-compose.yaml`` located.
+
+- Stop Homarr using ``docker compose down``
+- Pull the newest image of Homarr using ``docker compose pull``
+- Start Homarr again using ``docker compose up -d`` (``-d`` for detached mode - start in background)
+- Delete the old image using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*)
+
+You can automate this process using [Watchtower](https://containrrr.dev/watchtower/).
+
+### Uninstalling
+
+To uninstall, navigate to the directory with the ``docker-compose.yaml`` located.
+
+- Stop Homarr using ``docker compose down``
+- Delete the created directories & files on your root file system (check ``docker-compose.yaml`` file for your specific locations)
+- Delete compose file using ``rm docker-compose.yaml``
+- Prune unused Docker images using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*)
+- (Optional): Prune any network or volumes if you use any.
+- (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any.
+
+
+## Docker standalone
+
+:::caution
+
+[Docker Compose](#docker-compose) is easier and recommended for beginners. Consider using compose instead.
+
+:::
+
+### Prerequisites
+
+- A Linux or Windows based system that meets the [hardware prerequisites](/docs/getting-started/#hardware) and [architecture prerequisites](/docs/getting-started/#architecture).
+- [Docker](https://docs.docker.com/get-docker/)
+
+### Installation
+
+To install Homarr using Docker, simply run the following command.
+
+```bash
+docker run  \
+  --name homarr \
+  --restart unless-stopped \
+  -p 7575:7575 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v <your-path>/homarr/appdata:/appdata \
+  -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' \
+  -d ghcr.io/homarr-labs/homarr:latest
+```
+
+:::note
+
+Docker will mount the configuration files and icons to your host machine. Please make sure to replace ``<your-path>`` from the docker run command with your desired storage location. The path must be absolute.
+
+:::
+
+### Updating
+To update Homarr, you must remove your container first. Make sure that you've mounted your data and that you have access to it, so your configuration doesn't get lost.
+
+1. Run ``docker rm homarr`` to remove the container.
+2. Pull the latest Homarr image ``docker pull ghcr.io/homarr-labs/homarr:latest``.
+3. Re-run the command you used to install Homarr.
+
+This process can get tideous, if you update frequently. Thus, we recommend [using docker-compose](#docker-compose)
+
+:::tip
+
+Want to update all your containers automatically? Checkout [Watchtower](https://containrrr.dev/watchtower/) a service which will automatically update your containers on a set interval.
+
+:::
+
+### Uninstalling
+
+1. Obtain the container ID of your Homarr container using ``docker ps | grep homarr``.
+2. Delete the container using ``docker rm <your-container-id>``
+3. Prune unused Docker images using ``docker image prune`` (*Warning: this also removes you other unused images - not just Homarr*)
+4. (Optional): Prune any network or volumes if you use any.
+5. (Optional): Remove Homarr from your reverse proxy, VPNs or tunnels if you use any.

apps/docs/docs/getting-started/installation/easy-panel.mdx

@@ -0,0 +1,9 @@
+# EasyPanel
+
+:::caution
+Easypanel has not updated to 1.0 yet. There template is still on 0.15.4.
+:::
+
+Easypanel is a modern server control panel. If you [run Easypanel](https://easypanel.io/docs) on your server, you can deploy Homarr with 1 click on it.
+
+[![Deploy to Easypanel](https://easypanel.io/img/deploy-on-easypanel-40.svg)](https://easypanel.io/docs/templates/homarr)