Digitalboard/digitalboard.core
6
2
Fork 0
Code Pull requests 1 Releases Packages Activity Actions

chore(homarr): added readme and removed test env contents

Browse source
This commit is contained in:
Tobias Wüst 2026-05-13 15:24:51 +02:00
parent 308bf50122
commit 2aa1df8614
Signed by: Tobias-Wuest
GPG key ID: 2D8992B0F4CA97E8
2 changed files with 193 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

206
roles/homarr/README.md
View file

@ -1,38 +1,196 @@
Role Name
=========
# homarr
A brief description of the role goes here.
Deploy [Homarr](https://github.com/homarr-labs/homarr) as a self-contained
Docker Compose stack behind Traefik, with seeded admin user, OIDC group
and customizable application tiles.
Requirements
------------
## What this role does
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
- Deploys the official Homarr container with Traefik labels
- Seeds the SQLite database with:
- server settings (locale, analytics, crawling, default board)
- a default board with the three layouts (desktop/tablet/mobile)
- a local admin user with bcrypt-hashed password
- OIDC and credentials admin groups with full permissions
- application tiles defined in `homarr_apps`, auto-laid-out across all
three screen sizes
- Skips the onboarding wizard so the instance is usable right after deploy
- Restarts the container via handler when the seed or compose file changes
Role Variables
--------------
## What this role does NOT do
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
- Does not configure OIDC end-to-end — set `homarr_oidc_*` variables and
configure the corresponding client in your identity provider
- Does not migrate existing Homarr databases — only seeds empty ones
- Does not create users beyond the single local admin (OIDC users are
provisioned on first login)
Dependencies
------------
## Required variables
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
Provide via OpenBao, Ansible Vault, or extra-vars. **Never commit real
secrets to version control.**
Example Playbook
----------------
| Variable | Format | Generate with |
|---|---|---|
| `homarr_secret_encryption_key` | 64-char hex string | `openssl rand -hex 32` |
| `homarr_admin_password` | strong password | `openssl rand -base64 24` |
| `homarr_oidc_client_secret` | from your identity provider | — |
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
The `assert` task at the top of the role will fail fast if the encryption
key is missing or malformed.
- hosts: servers
roles:
- { role: username.rolename, x: 42 }
## Configurable variables
License
-------
See `defaults/main.yml` for the full list. Most useful overrides:
BSD
| Variable | Default | Purpose |
|---|---|---|
| `homarr_domain` | `homarr.local.test` | Traefik Host rule |
| `homarr_base_url` | `https://home.local.test` | NEXTAUTH_URL / BASE_URL |
| `homarr_auth_providers` | `credentials` | `credentials`, `oidc`, or both |
| `homarr_oidc_issuer` | empty | Identity provider issuer URL |
| `homarr_oidc_client_id` | empty | OIDC client id |
| `homarr_oidc_admin_group` | `homarr-admins` | Group granting admin role |
| `homarr_apps` | `[]` | List of application tiles, see below |
Author Information
------------------
## Application tiles
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
`homarr_apps` is a list of tile definitions that are seeded into the
default board. Each entry needs:
| Field | Required | Description |
|---|---|---|
| `id` | yes | Unique slug, used as `app-<id>` and `item-<id>` |
| `name` | yes | Display name |
| `icon` | yes | Icon URL |
| `href` | yes | Click target |
| `width` | yes | Tile width in grid cells (1–10) |
| `description` | no | Tooltip / subtitle |
| `height` | no | Tile height (default `1`) |
The role validates that all `id` values are unique.
### Auto-layout
Tiles are packed left-to-right into three layouts:
- **Desktop**: 10 columns
- **Tablet**: 6 columns
- **Mobile**: 2 columns
When a tile does not fit the remaining width of a row, it wraps to the
next row. Tile width is clamped to the grid width (a tile with
`width: 8` becomes `width: 6` on tablet and `width: 2` on mobile).
### Example
```yaml
homarr_apps:
- id: nextcloud
name: Nextcloud
description: Cloud Storage & Collaboration
icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/nextcloud.png
href: https://cloud.example.com
width: 2
- id: keycloak
name: Keycloak
description: Identity & Access Management
icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/keycloak.png
href: https://auth.example.com
width: 2
```
## First login
After the role completes, log in at `{{ homarr_base_url }}` with:
- Username: value of `homarr_admin_username` (default `admin`)
- Password: value of `homarr_admin_password`
OIDC users are provisioned on first login if their identity provider
group matches `homarr_oidc_admin_group`. They receive admin permissions
automatically through the seeded `group-oidc-admins` group.
## Example playbook
```yaml
- name: Deploy Homarr service
hosts: homarr_servers
become: true
roles:
- digitalboard.core.homarr
```
With inventory variables:
```yaml
# inventories/<env>/group_vars/homarr_servers.yml
homarr_domain: home.digitalboard.ch
homarr_base_url: "https://home.digitalboard.ch"
homarr_auth_providers: "credentials,oidc"
homarr_oidc_issuer: "https://auth.digitalboard.ch/realms/Digitalboard"
homarr_oidc_client_id: "homarr-digitalboard"
homarr_oidc_client_name: "Digitalboard"
homarr_secret_encryption_key: >-
{{ lookup('community.hashi_vault.vault_kv2_get',
'digitalboard/homarr',
mount_point='kv').data.data.encryption_key }}
homarr_admin_password: >-
{{ lookup('community.hashi_vault.vault_kv2_get',
'digitalboard/homarr',
mount_point='kv').data.data.admin_password }}
homarr_oidc_client_secret: >-
{{ lookup('community.hashi_vault.vault_kv2_get',
'digitalboard/homarr',
mount_point='kv').data.data.oidc_client_secret }}
homarr_apps:
- id: nextcloud
name: Nextcloud
description: Cloud Storage
icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/nextcloud.png
href: https://cloud.digitalboard.ch
width: 2
- id: keycloak
name: Keycloak
description: Identity & Access Management
icon: https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/keycloak.png
href: https://auth.digitalboard.ch
width: 2
```
## Re-running the role
The role is idempotent for the typical re-run case:
- The seed only runs when no local admin user exists in the database
- The compose file and seed template are deployed via `template`,
which only changes content when the inputs change
- The restart handler only fires when one of those templates changes
If you need to re-seed an existing database (for example after deleting
the database file to apply schema changes), the role will detect the
fresh database and seed it again on the next run.
## Troubleshooting
**Login fails after deploy.** Verify that the bcrypt hash was written
correctly:
```bash
sqlite3 /srv/data/homarr/homarr/appdata/db/db.sqlite \
"SELECT id, name, email, length(password), provider FROM user;"
```
Expected: one row with `user-local-admin`, password length 60,
provider `credentials`.
**Encryption key validation fails.** The key must be exactly 64
characters and contain only hex digits (`[a-fA-F0-9]`). Both upper-
and lowercase are accepted.
**App tiles overlap.** Check `homarr_apps` for duplicate `id` values.
The role validates this, but if you bypass the check, the seed will
still run and Homarr will display only one of the duplicates.

21
roles/homarr/defaults/main.yml
View file

@ -1,3 +1,4 @@
homarr_apps: [ ]
#SPDX-License-Identifier: MIT-0
---
# defaults file for homarr
@ -23,21 +24,21 @@ homarr_use_docker: false
# Generate with: openssl rand -hex 32
# Provide via OpenBao lookup, Ansible Vault, or extra-vars.
# Never commit a real key to version control.
homarr_secret_encryption_key: "9981080f7eb054b90c7be80622608c3b63ba58408171ef3fbcdce9ba9c0554dc"
homarr_secret_encryption_key: ""
# URL — used for BASE_URL, NEXTAUTH_URL and the completion message
homarr_base_url: "https://home.local.test"
# Auth providers (comma-separated): credentials, oidc, ldap
homarr_auth_providers: "credentials,oidc"
homarr_auth_providers: "credentials"
# OIDC configuration
homarr_oidc_issuer: "https://auth.digitalboard.ch/realms/Digitalboard"
homarr_oidc_client_id: "homarr-digitalboard"
homarr_oidc_client_name: "Digitalboard"
# OIDC configuration (only used when 'oidc' is in homarr_auth_providers)
homarr_oidc_issuer: ""
homarr_oidc_client_id: ""
homarr_oidc_client_name: ""
homarr_oidc_scopes: "openid profile email groups"
homarr_oidc_groups_attribute: "groups"
homarr_oidc_client_secret: "a91c9ec370f75fe34f7df20f50a70ff2d761ebd74c336a3f9e4640b49521cee2"
homarr_oidc_client_secret: ""
homarr_oidc_auto_login: "false"
# OIDC admin group (must exist in the identity provider)
@ -51,9 +52,9 @@ homarr_default_board_public: true
homarr_traefik_network: "proxy"
homarr_use_ssl: true
# Local admin
# Local admin (override in inventory or via vault)
homarr_admin_username: "admin"
homarr_admin_email: "admin@digitalboard.ch"
homarr_admin_email: "admin@example.com"
homarr_admin_password: "ChangeMe123!"
# Applications shown on the default board.
@ -71,4 +72,4 @@ homarr_admin_password: "ChangeMe123!"
# href: https://cloud.example.com
# width: 2
# height: 1
homarr_apps: [ ]
homarr_apps: []