feat(docs): migrate documentation site into monorepo (#5912)
This commit is contained in:
Thomas authored and 
GitHub committed
1 parent
3e464a76f2
commit
9e421c67bd
605 files changed
+26764
-219
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Advanced",
|
||||
"collapsed": true,
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"title": "Advanced Concepts or features"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"collapsed": true,
|
||||
"label": "Command line interface"
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
@@ -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.
|
||||
|
||||
|
||||
BIN
Binary file not shown.
|
After Width: | Height: | Size: 195 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 393 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 348 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 414 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
@@ -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 
|
||||
2. Select Containers in the menu bar on the left 
|
||||
3. Select your Homarr Container 
|
||||
4. Click "Execute" in the top right of the Window. 
|
||||
5. Select /bin/bash and click Execute 
|
||||
6. Run the Homarr command and press enter (eg. homarr reset-owner-password) 
|
||||
@@ -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
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.8 KiB |
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 757 KiB |
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Developer guides",
|
||||
"position": 6,
|
||||
"collapsed": true,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
@@ -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.
|
||||
@@ -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 |
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 289 KiB |
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
|
||||
:::
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
@@ -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:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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;
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user