ray/hermes-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
ray
2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/self-hosting/docker-service-deployment/references/homarr.md
+313
View File
@@ -0,0 +1,313 @@
# Homarr Dashboard
A customizable, widget-based dashboard for managing and monitoring self-hosted services. Supports Docker container status, Plex sessions, download clients, system monitoring, and the Arr stack.
## Deployment (Local, No VPS)
Homarr runs on port 8080 directly — no nginx reverse proxy (it's the landing page for the homelab).
```yaml
# ~/docker/homarr/docker-compose.yml
services:
homarr:
container_name: homarr
image: ghcr.io/homarr-labs/homarr:latest
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock # Docker integration (auto-detect containers)
- ./appdata:/appdata # Config + icons
environment:
- SECRET_ENCRYPTION_KEY=<64-char-hex> # Generated via `openssl rand -hex 32`
ports:
- '8080:7575' # Host 8080 → container 7575
```
## Key Details
- **Container internal port**: 7575 (maps to Next.js on 3000 internally — transparent to the user)
- **Docker socket mount**: Required for Homarr to auto-discover running containers and show their status
- **Data directory**: `~/docker/homarr/appdata/` — contains SQLite DB (`appdata/db/db.sqlite`), icons, and config
- **First run**: Opens setup wizard on first visit to `http://192.168.50.98:8080/`
- **`SECRET_ENCRYPTION_KEY`**: Must be a 64-char hex string. Generate with `openssl rand -hex 32`. If changed after initial setup, existing encrypted data becomes unreadable.
## Replacing an Existing Dashboard (e.g. Heimdall)
To swap Heimdall → Homarr while keeping the same port:
```bash
# 1. Stop and remove old container
docker stop heimdall && docker rm heimdall
# 2. (Optional) Keep old data volume if needed
docker volume ls | grep heimdall
# 3. Deploy Homarr on the same port (8080)
mkdir -p ~/docker/homarr
# write docker-compose.yml as above
cd ~/docker/homarr && docker compose up -d
# 4. Verify
curl -sL -o /dev/null -w "%{http_code}" http://localhost:8080/ # → 200
```
**⚠️ Stale iptables DNAT rule**: If `curl localhost:8080` works but `curl 192.168.50.98:8080` doesn't, the old container likely left a stale DNAT rule. See "Stale iptables DNAT rules after replacing a container on the same port" in the main SKILL.md for diagnosis and fix.
**Docker loopback note**: After fixing the DNAT, localhost works and external clients on the network work, but curling the machine's own external IP from itself may still timeout — this is a known Docker kernel quirk, not a real connectivity problem.
All existing bookmarks to `http://192.168.50.98:8080/` continue working.
---
## Homarr CLI (User & Admin Management)
The Homarr container ships with a built-in CLI accessed via `docker exec homarr homarr <command>`.
### Available Commands
```
homarr users — Group of commands to manage users
homarr integrations — Group of commands to manage integrations
homarr reset-password — Reset password for a user (generates random password)
homarr fix-usernames — Changes all credentials usernames to lowercase
homarr recreate-admin — Recreate credentials admin user if none exists anymore
```
### User Management
**List users:**
```bash
docker exec homarr homarr users list
```
**Create admin (only when no users exist):**
```bash
docker exec homarr homarr recreate-admin --username <username>
# Outputs: generated password and temporary group name
```
**Reset password (generates random password, displayed in terminal):**
```bash
docker exec homarr homarr reset-password --username <user>
```
**Set specific password (needs user to already exist):**
```bash
docker exec homarr homarr users update-password --username <user> --password '<password>'
# Quote the password with single quotes to protect shell special chars ($, ^, \, etc.)
```
**Delete user:**
```bash
docker exec homarr homarr users delete --username <user>
```
### Pitfalls
- **Shell special characters in passwords**: Always quote with single quotes (`'password'`), never double quotes. Double quotes still interpret `$`, `!`, and backticks inside the `docker exec` shell.
- **Password with `$` and Docker Compose escaping**: If setting a password via `docker compose` environment or run command, any `$` must be doubled to `$$` because Docker Compose interprets `$` as variable expansion — regardless of YAML quote style. This is a compose-specific behavior, not bash.
- **`users list` may hang/be interrupted** on some Homarr versions — add `2>&1 | head -30` and a timeout if it hangs.
- **All sessions terminated**: After any password reset or update, all active sessions for that user are invalidated. They must re-login.
- **User must exist first**: `update-password` and `reset-password` require the user to already exist. If the database has no users, use `recreate-admin` first.
---
## Programmatic Dashboard Population (SQLite)
Homarr stores all configuration in a SQLite database at `appdata/db/db.sqlite` inside the container (mapped from `./appdata/db/db.sqlite` on the host). You can add services, place them on boards, and configure the layout by manipulating this database directly — much faster than clicking through the UI for 20+ services.
### Database Schema (Key Tables)
```
app — Service definitions (name, icon, URL, ping URL)
item — Widget placements on boards (refers to app via options JSON)
item_layout — Grid position of each item (x, y, width, height)
board — Board definitions (name, colors, CSS)
section — Board sections (empty/dynamic layouts)
section_layout — Layout of sections on a board
group — User groups
user — Users (id, name, email, password hash)
```
### The `app` Table
Service definitions. Homarr auto-discovers Docker containers via the Docker socket and populates this table.
```sql
CREATE TABLE `app` (
`id` TEXT PRIMARY KEY NOT NULL, -- ~25 char alphanumeric ID
`name` TEXT NOT NULL, -- Display name
`description` TEXT, -- Optional tooltip
`icon_url` TEXT NOT NULL, -- URL to icon image
`href` TEXT, -- URL to open on click
`ping_url` TEXT -- URL for status checks (optional)
);
```
**Insert an app:**
```sql
INSERT INTO app (id, name, description, icon_url, href, ping_url)
VALUES ('<generated-id>', 'Service Name', '', 'https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/<icon>.png', 'http://192.168.50.98:<port>', '');
```
### The `item` Table
Widget placements on a board. The `kind` field determines the widget type.
```sql
CREATE TABLE `item` (
`id` TEXT PRIMARY KEY NOT NULL,
`board_id` TEXT NOT NULL, -- References board.id
`kind` TEXT NOT NULL, -- 'app', 'clock', 'weather', 'bookmarks', etc.
`options` TEXT DEFAULT '{"json": {}}' NOT NULL, -- Widget-specific JSON config
`advanced_options` TEXT DEFAULT '{"json": {}}' NOT NULL
);
```
**Insert an app item:**
```sql
INSERT INTO item (id, board_id, kind, options, advanced_options)
VALUES ('<generated-id>', '<board-id>', 'app',
'{"json":{"appId":"<app-id>","openInNewTab":true,"showTitle":true}}',
'{"json":{}}');
```
**Other widget kinds:**
- `clock`: Simple clock widget — options: `{"json":{}}`
- `weather`: Weather widget — options: `{"json":{"showCity":true,"hasForecast":true,"forecastDayCount":3}}`
- `bookmarks`: Links collection — options: `{"json":{"title":"Name","layout":"grid","openNewTab":true,"items":["<app-id1>","<app-id2>"]}}`
### The `item_layout` Table
Grid position for each item on a section.
```sql
CREATE TABLE `item_layout` (
`id` TEXT PRIMARY KEY NOT NULL,
`section_id` TEXT NOT NULL, -- References section.id
`item_id` TEXT NOT NULL, -- References item.id
`x` INTEGER NOT NULL, -- Column position (0-indexed)
`y` INTEGER NOT NULL, -- Row position (0-indexed)
`width` INTEGER NOT NULL, -- Width in grid units
`height` INTEGER NOT NULL -- Height in grid units
);
```
**Insert a layout position:**
```sql
INSERT INTO item_layout (id, section_id, item_id, x, y, width, height)
VALUES ('<generated-id>', '<section-id>', '<item-id>', <x>, <y>, 1, 1);
```
### Finding IDs for Existing Records
```bash
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT id, name FROM board;"
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT id FROM section LIMIT 5;"
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT lid, section_id FROM section_layout LIMIT 5;"
```
### Icon URLs
Use one of the icon repositories:
```
# Homarr Labs dashboard-icons (PNG - most comprehensive)
https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/<service>.png
https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/<service>.svg
# WalkXcode dashboard-icons (SVG)
https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons@master/svg/<service>.svg
# Logan Marchione homelab-svg-assets
https://cdn.jsdelivr.net/gh/loganmarchione/homelab-svg-assets@latest/assets/<service>.svg
```
Common icon filenames: `immich`, `home-assistant`, `paperless-ngx`, `plex`, `audiobookshelf`, `mealie`, `qbittorrent`, `pihole`, `portainer`, `uptime-kuma`, `scrutiny`, `vaultwarden`, `pocketbase`, `glitchtip`, `searxng`, `sunshine`, `homarr`, `github`, `redis`, `postgres`, `valkey`, `chrome-beta`.
### Complete Population Workflow
```python
import sqlite3
import secrets
import string
import json
DB_PATH = "/home/ray/docker/homarr/appdata/db/db.sqlite"
def gen_id():
"""Generate a ~25 char alphanumeric ID matching Homarr's format."""
alphabet = string.ascii_lowercase + string.digits
return ''.join(secrets.choice(alphabet) for _ in range(25))
def add_service(conn, board_id, section_id, name, icon_name, href, x, y, w=1, h=1):
app_id = gen_id()
item_id = gen_id()
layout_id = gen_id()
# 1. Create app
icon_url = f"https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/{icon_name}.png"
conn.execute("INSERT INTO app (id, name, description, icon_url, href, ping_url) VALUES (?, ?, '', ?, '', '')",
(app_id, name, icon_url, href))
# 2. Create item
options = json.dumps({"json": {"appId": app_id, "openInNewTab": True, "showTitle": True}})
conn.execute("INSERT INTO item (id, board_id, kind, options, advanced_options) VALUES (?, ?, 'app', ?, '{\"json\":{}}')",
(item_id, board_id, options))
# 3. Create layout
conn.execute("INSERT INTO item_layout (id, section_id, item_id, x, y, width, height) VALUES (?, ?, ?, ?, ?, ?, ?)",
(layout_id, section_id, item_id, x, y, w, h))
conn.commit()
print(f" Added {name} at ({x},{y})")
# Usage:
# conn = sqlite3.connect(DB_PATH)
# board_id = "un39cd3f4sj9ik35dkhuvo92" # from SELECT on board table
# section_id = "r6ly519w0mp0ez7mgd8klg3z" # from SELECT on section table
# services = [
# ("Immich", "immich", "http://192.168.50.98:2283", 0, 0, 2, 1),
# ("Home Assistant", "home-assistant", "http://192.168.50.98:8123", 2, 0),
# ...
# ]
# for name, icon, url, x, y, *size in services:
# w, h = size if size else (1, 1)
# add_service(conn, board_id, section_id, name, icon, url, x, y, w, h)
# conn.close()
```
### Restart After Population
After any database modification, restart the container to reload:
```bash
docker restart homarr
```
### Pitfalls
- **IDs must be unique across their respective tables** — generate them with `secrets.token_urlsafe()` or custom alphanumeric generation, never hardcode.
- **Board and section IDs differ per instance** — always query the live database first to discover them.
- **`openInNewTab` is optional but recommended** — set `true` so clicking a service opens it in a new browser tab rather than navigating away from the dashboard.
- **`showTitle` defaults to true** — set `false` for icon-only widgets if the grid is dense.
- **Docker auto-discovery may recreate apps** — if Homarr detects a container name matching an app name, it may overwrite the `href` field. Workaround: edit the `app` entry via the Homarr Web UI after database insertion, or in the `options` JSON reference the Homarr-generated `app.id` instead of creating new `app` rows.
- **Restart required** — Homarr caches the board layout aggressively. SQLite writes alone won't reflect on the page until the container restarts.
- **Backup before bulk edit** — always copy `db.sqlite` before adding many services: `cp /home/ray/docker/homarr/appdata/db/db.sqlite{,.bak}`
### Grid Layout Design
Design a clean grid before inserting. Common patterns:
- **4-column grid** works well for most layouts
- **2-wide for primary services** (Immich, Home Assistant, Plex)
- **1-wide** for standard services
- **Leave gaps for future additions** at the end of each row
Example layout for 16 services:
```
Row 0: Immich (2w), HA (1w), Paperless (1w)
Row 1: Plex (1w), Audiobk (1w), Mealie (1w), qBit (1w)
Row 2: Portainer (1w), Pi-hole (1w), Kuma (1w), Scrutiny (1w)
Row 3: Vaultwrdn (1w), SearXNG (1w), PocketB (1w), HermesDb(1w)
Row 4: HermesUI (1w), Sunshine(1w), Chrome (1w), GlitchT(1w)
```