initial commit
This commit is contained in:
ray
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: homarr-dashboard-setup
|
||||
description: >-
|
||||
Deploy, configure, and populate a Homarr dashboard — Docker setup, user
|
||||
management, bulk-adding services via direct SQLite manipulation, layout
|
||||
planning, and troubleshooting.
|
||||
tags: [homarr, dashboard, self-hosted, homelab, sqlite, docker]
|
||||
---
|
||||
|
||||
# Homarr Dashboard Setup
|
||||
|
||||
Populate a Homarr dashboard with all self-hosted services. Homarr stores everything in SQLite -- apps, items (widgets), layout positions. For bulk operations, direct database manipulation is faster than the web UI.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Path | Value |
|
||||
|------|-------|
|
||||
| Container | `homarr` |
|
||||
| Image | `ghcr.io/homarr-labs/homarr:latest` |
|
||||
| Port | `8080:7575` |
|
||||
| Config dir | `./appdata` (bind mount to `/appdata`) |
|
||||
| DB location | `<config>/db/db.sqlite` |
|
||||
| CLI tool | `docker exec homarr homarr <command>` |
|
||||
|
||||
## User management
|
||||
|
||||
### Create first admin (no users exist)
|
||||
```bash
|
||||
docker exec homarr homarr recreate-admin --username ray
|
||||
# Shows a generated password
|
||||
```
|
||||
|
||||
### Set a specific password
|
||||
```bash
|
||||
docker exec homarr homarr users update-password \
|
||||
--username ray \
|
||||
--password 'your-password-here'
|
||||
```
|
||||
|
||||
### Reset password to random (all sessions terminated)
|
||||
```bash
|
||||
docker exec homarr homarr reset-password --username ray
|
||||
```
|
||||
|
||||
### List users
|
||||
```bash
|
||||
docker exec homarr homarr users list
|
||||
```
|
||||
|
||||
## Database schema (key tables)
|
||||
|
||||
### `app` -- service definitions
|
||||
```
|
||||
id TEXT PRIMARY KEY -- 25-char alphanumeric ID
|
||||
name TEXT -- display name
|
||||
description TEXT -- optional tooltip
|
||||
icon_url TEXT -- URL to icon
|
||||
href TEXT -- click target URL
|
||||
ping_url TEXT -- optional separate status-check URL
|
||||
```
|
||||
|
||||
### `item` -- widgets on the board
|
||||
```
|
||||
id TEXT PRIMARY KEY
|
||||
board_id TEXT -- FK to board.id
|
||||
kind TEXT -- 'app' for app widgets, 'clock', 'weather', etc.
|
||||
options TEXT -- JSON: {"json":{"appId":"<app_id>","openInNewTab":true,"showTitle":true}}
|
||||
advanced_options TEXT -- usually {"json":{}}
|
||||
```
|
||||
|
||||
### `item_layout` -- position/size on the grid
|
||||
```
|
||||
item_id TEXT -- FK to item.id
|
||||
section_id TEXT -- FK to section.id
|
||||
layout_id TEXT -- FK to layout.id
|
||||
x_offset INTEGER
|
||||
y_offset INTEGER
|
||||
width INTEGER
|
||||
height INTEGER
|
||||
```
|
||||
|
||||
### `board` -- the dashboard page
|
||||
```
|
||||
id TEXT PRIMARY KEY
|
||||
name TEXT -- unique name
|
||||
```
|
||||
|
||||
### `section` -- a column/grid area on a board
|
||||
```
|
||||
id TEXT PRIMARY KEY
|
||||
board_id TEXT -- FK to board.id
|
||||
```
|
||||
|
||||
### `section_layout` -- which layout template a section uses
|
||||
```
|
||||
id TEXT PRIMARY KEY
|
||||
section_id TEXT -- FK to section.id
|
||||
```
|
||||
|
||||
## Bulk-adding services via SQLite
|
||||
|
||||
When adding 10+ services, direct SQLite inserts beat the UI. Steps:
|
||||
|
||||
### 1. Discover running services and their ports
|
||||
```bash
|
||||
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}\t{{.Status}}'
|
||||
ss -tlnp | grep LISTEN
|
||||
```
|
||||
|
||||
### 2. Get board/section/layout IDs
|
||||
```sql
|
||||
SELECT id, name FROM board;
|
||||
SELECT id, board_id FROM section;
|
||||
SELECT id, section_id FROM section_layout;
|
||||
```
|
||||
|
||||
### 3. Icon URLs
|
||||
|
||||
Use the Homarr dashboard-icons repository:
|
||||
```
|
||||
https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/<name>.png
|
||||
https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons@master/svg/<name>.svg
|
||||
```
|
||||
|
||||
Common icons: `immich.png`, `home-assistant.png`, `paperless-ngx.png`, `plex.png`,
|
||||
`audiobookshelf.png`, `mealie.png`, `qbittorrent.png`, `pihole.png`,
|
||||
`portainer.png`, `uptime-kuma.png`, `scrutiny.png`, `vaultwarden.png`,
|
||||
`pocketbase.png`, `glitchtip.png`, `searxng.png`, `sunshine.png`
|
||||
|
||||
For missing icons, fall back to `chrome-beta.png` or another generic icon.
|
||||
|
||||
### 4. Generate IDs
|
||||
|
||||
Homarr uses ~25-char alphanumeric IDs. Generate them in Python:
|
||||
```python
|
||||
import secrets
|
||||
def gen_id():
|
||||
return secrets.token_urlsafe(16)[:25].replace('-','0').replace('_','1')
|
||||
```
|
||||
|
||||
### 5. Insert apps
|
||||
```sql
|
||||
INSERT INTO app (id, name, icon_url, href) VALUES
|
||||
('<id>', '<Name>', '<icon_url>', '<href>');
|
||||
```
|
||||
|
||||
### 6. Insert items (one per app)
|
||||
```sql
|
||||
INSERT INTO item (id, board_id, kind, options, advanced_options) VALUES
|
||||
('<item_id>', '<board_id>', 'app',
|
||||
'{"json":{"appId":"<app_id>","openInNewTab":true,"showTitle":true}}',
|
||||
'{"json":{}}');
|
||||
```
|
||||
|
||||
### 7. Insert layout records
|
||||
```sql
|
||||
INSERT INTO item_layout (item_id, section_id, layout_id, x_offset, y_offset, width, height) VALUES
|
||||
('<item_id>', '<section_id>', '<layout_id>', 0, 0, 1, 1);
|
||||
```
|
||||
|
||||
### 8. Restart container
|
||||
```bash
|
||||
docker restart homarr
|
||||
```
|
||||
|
||||
### 9. Verify
|
||||
```bash
|
||||
sqlite3 <db_path> \
|
||||
"SELECT l.x_offset, l.y_offset, l.width, l.height, a.name
|
||||
FROM item_layout l
|
||||
JOIN item i ON l.item_id = i.id
|
||||
LEFT JOIN app a ON json_extract(i.options, '$.json.appId') = a.id
|
||||
ORDER BY l.y_offset, l.x_offset;"
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **DB owned by root**: The SQLite file is created by the Docker container and owned by `root:root`. Use `sudo` or `docker exec` for DB access.
|
||||
- **Duplicate apps**: Homarr auto-discovers Docker containers and inserts into the `app` table. You may see duplicate entries -- e.g. the auto-discovered `homarr` + your manually created `Homarr`. Clean up old items/layouts if needed.
|
||||
- **Layout columns are `x_offset`, `y_offset`**: Not `x`/`y`. Forgetting this causes silent misplacement.
|
||||
- **IDs must be unique across `item` and `app` tables**: The random generator collisions are astronomically unlikely but verify if you suspect overlap.
|
||||
- **Restart required**: Direct DB writes are not live-reloaded. Always `docker restart homarr` after inserts.
|
||||
- **Container restarts reset uncommitted changes**: The DB is on a bind mount, but if your insert script hasn't committed before the container exits, changes are lost. Use explicit `connection.commit()`.
|
||||
- **json_extract in joins**: When joining `item` to `app`, use `json_extract(i.options, '$.json.appId')` to extract the app reference from the item's JSON options field.
|
||||
- **Nginx proxy vs direct access**: For services behind nginx on the same host, use `127.0.0.1:<port>`. For services reaching other hosts or directly exposed, use `192.168.50.98:<port>`.
|
||||
Reference in New Issue
Block a user