chore: reconcile v2 after stack rebase
This commit is contained in:
ajnart committed
1 parent
5dc4dbeaef
commit
0482c040ec
215 files changed
+12297
-17452
No files matched your search
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"collapsed": true,
|
||||
"label": "Command line interface"
|
||||
}
|
||||
}
|
||||
@@ -14,4 +14,4 @@ homarr fix-usernames
|
||||
|
||||
This will convert all credential usernames to lowercase and update the database accordingly.
|
||||
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
Please note that the CLI is an _emergency tool_, not an API tool.
|
||||
|
||||
:::caution
|
||||
|
||||
@@ -12,10 +12,10 @@ 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).
|
||||
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
|
||||
|
||||
|
||||
@@ -7,6 +7,7 @@ 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
|
||||
|
||||
@@ -43,7 +44,7 @@ Flags:
|
||||
## Delete Integration
|
||||
|
||||
- Requires a database connection
|
||||
- Requires one parameter: ``id`` or ``name``
|
||||
- Requires one parameter: `id` or `name`
|
||||
- Deletes an integration permanently from the database
|
||||
|
||||
```bash
|
||||
@@ -57,4 +58,4 @@ Flags:
|
||||
-n, --name string Name of the integration
|
||||
-h, --help help for integrations delete
|
||||
-v, --version version for homarr-cli
|
||||
```
|
||||
```
|
||||
@@ -12,8 +12,8 @@ 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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
@@ -7,6 +7,7 @@ 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
|
||||
|
||||
@@ -42,7 +43,7 @@ yj52ek5cyb6du4bp4osbkjry admin xxxx@example.com
|
||||
## Delete User
|
||||
|
||||
- Requires a database connection
|
||||
- Requires one parameter: ``id`` or ``username``
|
||||
- Requires one parameter: `id` or `username`
|
||||
|
||||
```bash
|
||||
Delete a user by id or username
|
||||
@@ -76,4 +77,4 @@ Flags:
|
||||
-p, --password New password
|
||||
-h, --help help for users update-password
|
||||
-v, --version version for homarr-cli
|
||||
```
|
||||
```
|
||||
@@ -1,9 +1,8 @@
|
||||
{
|
||||
"label": "Developer guides",
|
||||
"position": 6,
|
||||
"collapsed": true,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
"label": "Developer guides",
|
||||
"position": 6,
|
||||
"collapsed": true,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
|
||||
}
|
||||
@@ -12,12 +12,12 @@ sidebar_position: 1
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 24.18 or newer
|
||||
- Corepack (the root `package.json` selects the supported pnpm version)
|
||||
- Git
|
||||
- Docker with Docker Compose
|
||||
- Go 1.25+ for the developer Docker CLI
|
||||
- GitHub CLI for pull-request image features
|
||||
- **Node.js 24.18 or newer**: You can download it from the [official website](https://nodejs.org/).
|
||||
- **Corepack**: Run `corepack enable` so the repository selects its pinned pnpm 11 version.
|
||||
- **Git**: You can download it from the [official website](https://git-scm.com/).
|
||||
- **Docker or Docker Desktop**: Required for the Redis service and the developer Docker CLI.
|
||||
- **Go 1.25+**: Required only for the developer Docker CLI. You can download it from the [official website](https://go.dev/).
|
||||
- **GitHub CLI**: Required only for pull-request image features. Install it from the [official website](https://cli.github.com/), then authenticate with `gh auth login`.
|
||||
|
||||
The versions in the root `package.json` are the supported baseline. Let Corepack select the repository version instead
|
||||
of installing an unrelated global pnpm:
|
||||
@@ -54,6 +54,8 @@ pnpm dev
|
||||
|
||||
The infrastructure command remains in the foreground. Open `http://127.0.0.1:3000`; the first user created through
|
||||
Homarr becomes the instance administrator.
|
||||
Use `pnpm docker:dev:up` instead when you only need Redis in the background. Running the migration also seeds the
|
||||
default data; use `pnpm db:seed` to seed it explicitly later.
|
||||
|
||||
### Run PocketBase and documentation
|
||||
|
||||
@@ -103,17 +105,18 @@ pnpm dev:docs
|
||||
### Useful commands
|
||||
|
||||
- `pnpm dev` — Next.js on port 3000.
|
||||
- `pnpm dev:benchmark` — run the authenticated-board development benchmark.
|
||||
- `pnpm dev:cli -- dev` — browse local images and remote pull-request images.
|
||||
- `pnpm dev:benchmark` — authenticated-board benchmark; readiness-only `--smoke` runs are not performance claims.
|
||||
- `pnpm dev:cli -- dev` — browse and run local images and remote pull-request images.
|
||||
- `pnpm dev:cli -- build <name>` — build the current checkout as `homarr:<name>`.
|
||||
- `pnpm dev:cli -- build --pr <number>` — build a pull request from a temporary checkout.
|
||||
- `pnpm dev:cli:install` — install the developer CLI as a `homarr` binary.
|
||||
- `pnpm dev:cli -- rebuild <name>` — rebuild an image from its recorded checkout or pull request.
|
||||
- `pnpm dev:cli:install` — optionally install the developer CLI as a `homarr` binary.
|
||||
- `pnpm dev:docs` — Docusaurus only on port 3003.
|
||||
- `pnpm docker:dev:up` — start Redis in the background.
|
||||
- `pnpm docker:workshop` — local PocketBase through Docker Compose.
|
||||
- `pnpm docker:dev:up` — Redis development service in the background.
|
||||
- `pnpm cli` — Homarr operations CLI.
|
||||
- `pnpm db:migration:sqlite:run` — create or update a SQLite database.
|
||||
- `pnpm db:seed` — seed the default database data.
|
||||
- `pnpm db:seed` — seed the default database data explicitly.
|
||||
- `pnpm db:studio` — inspect the database.
|
||||
- `pnpm format` / `pnpm format:fix` — check or apply oxfmt.
|
||||
- `pnpm lint` / `pnpm lint:fix` — check or apply oxlint.
|
||||
@@ -121,3 +124,5 @@ pnpm dev:docs
|
||||
- `pnpm test` — unit and contract suites.
|
||||
- `pnpm test:workshop` — disposable Workshop integration suite.
|
||||
- `pnpm build` — production monorepo build.
|
||||
- `docker build -t homarr .` — build a production Docker image.
|
||||
- `docker run -p 7575:7575 -e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' homarr:<name>` — run it.
|
||||
@@ -132,4 +132,4 @@ 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.
|
||||
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.
|
||||
@@ -6,11 +6,11 @@ tags:
|
||||
|
||||
Homarr has the following keyboard shortcuts:
|
||||
|
||||
| Shortcut | Description |
|
||||
| -------- | ----------- |
|
||||
| Shortcut | Description |
|
||||
| ----------- | -------------------- |
|
||||
| `MOD` + `K` | Opens the search bar |
|
||||
| `MOD` + `J` | Toggles Dark Mode |
|
||||
| `MOD` + `E` | Toggles Edit Mode |
|
||||
| `MOD` + `J` | Toggles Dark Mode |
|
||||
| `MOD` + `E` | Toggles Edit Mode |
|
||||
|
||||
:::tip
|
||||
|
||||
|
||||
@@ -9,16 +9,17 @@ tags:
|
||||
- Security
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
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``.
|
||||
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.
|
||||
|
||||
:::
|
||||
@@ -28,8 +29,9 @@ To allow self-signed certificates, you can configure them on the certificates ma
|
||||
## 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'
|
||||
version: "3"
|
||||
services:
|
||||
homarr:
|
||||
container_name: homarr
|
||||
@@ -53,11 +55,12 @@ networks:
|
||||
external: true
|
||||
```
|
||||
|
||||
<br/>
|
||||
<br />
|
||||
|
||||
A sample Traefik docker-compose.yml using Cloudflare for certificate generation that works with the configuration above would be:
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
version: "3"
|
||||
|
||||
apps:
|
||||
traefik:
|
||||
@@ -103,7 +106,6 @@ networks:
|
||||
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.
|
||||
:::
|
||||
@@ -114,7 +116,6 @@ If you are using Caddy as the reverse proxy for your setup, your `docker-compose
|
||||
|
||||
```yaml
|
||||
services:
|
||||
|
||||
# <-- [Homarr installation]
|
||||
|
||||
caddy:
|
||||
@@ -140,14 +141,17 @@ 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:
|
||||
|
||||
@@ -8,7 +8,7 @@ tags:
|
||||
- PUID
|
||||
---
|
||||
|
||||
By default the container is running with user `root` and group `root`.
|
||||
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.
|
||||
|
||||
@@ -32,11 +32,11 @@ services:
|
||||
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
|
||||
- SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
ports:
|
||||
- '7575:7575'
|
||||
- "7575:7575"
|
||||
```
|
||||
|
||||
After that you'll need to create the appdata directory and set the correct permissions:
|
||||
@@ -76,11 +76,11 @@ services:
|
||||
- /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
|
||||
- SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
|
||||
- PUID=1000
|
||||
- PGID=999
|
||||
ports:
|
||||
- '7575:7575'
|
||||
- "7575:7575"
|
||||
```
|
||||
|
||||
And set the permissions for the mounted directories:
|
||||
@@ -90,4 +90,4 @@ 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.
|
||||
Important here is that the group ID is set to `999` as we created the `docker` group with this ID.
|
||||
@@ -10,20 +10,21 @@ tags:
|
||||
- Active Directory
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
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" |
|
||||
| AUTH_COOKIE_PREFIX | Prefix used for all authentication cookies (session, csrf, callback, pkce, state, nonce). Change this if you run another Auth.js/NextAuth app on the same hostname as Homarr (browsers scope cookies by host, not by port) to avoid cookie name collisions. Only letters, numbers, hyphens and underscores are allowed. | `homarr` |
|
||||
|
||||
| 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" |
|
||||
| AUTH_COOKIE_PREFIX | Prefix used for all authentication cookies (session, csrf, callback, pkce, state, nonce). Change this if you run another Auth.js/NextAuth app on the same hostname as Homarr (browsers scope cookies by host, not by port) to avoid cookie name collisions. Only letters, numbers, hyphens and underscores are allowed. | `homarr` |
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="credentials" label="Credentials Provider" default>
|
||||
|
||||
@@ -19,12 +19,14 @@ Homarr uses https://mantine.dev/ under the hood. You can change the look & feel
|
||||
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>**:
|
||||
|
||||
@@ -33,21 +35,23 @@ Although CSS can improve the design & feel of the page, it **<ins>cannot do any
|
||||
- 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 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.
|
||||
|
||||
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.
|
||||
- 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.
|
||||
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
|
||||
@@ -55,17 +59,19 @@ which element to apply the styles to. If you accidentally broke something or wan
|
||||
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.
|
||||
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
|
||||
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``.
|
||||
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:
|
||||
|
||||
|
||||
@@ -73,6 +79,7 @@ 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:
|
||||
|
||||
@@ -84,11 +91,12 @@ Here you can enter your CSS code, which will be applied on the respective board
|
||||
|
||||
|
||||
## 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;
|
||||
--mantine-primary-color-filled: #ffbb00;
|
||||
}
|
||||
```
|
||||
```
|
||||
Reference in new issue
Block a user