ray
92 lines
2.8 KiB
Markdown
92 lines
2.8 KiB
Markdown
# Heimdall Dashboard — Direct SQLite Management
|
|
|
|
Adding, updating, and removing tiles by directly editing Heimdall's `app.sqlite` database instead of the web UI. Useful for bulk operations, or when the UI isn't accessible.
|
|
|
|
## Database Location
|
|
|
|
```
|
|
/var/lib/docker/volumes/heimdall_config/_data/www/app.sqlite
|
|
```
|
|
|
|
Access requires sudo (Docker volume data is root-owned).
|
|
|
|
## Table Structure
|
|
|
|
### `items` table — the dashboard tiles
|
|
|
|
Key columns:
|
|
| Column | Type | Notes |
|
|
|--------|------|-------|
|
|
| `id` | INTEGER | Auto-increment PK |
|
|
| `title` | TEXT | Display name on tile |
|
|
| `url` | TEXT | Link target |
|
|
| `colour` | TEXT | Hex color (e.g. `#d48c3c`) |
|
|
| `icon` | TEXT | Empty string for no custom icon |
|
|
| `description` | TEXT | Optional subtitle |
|
|
| `pinned` | INTEGER | 0 = no, 1 = yes |
|
|
| `order` | INTEGER | Sort order — **must be 0** like all other items |
|
|
| `type` | INTEGER | **Must be 0** (not string "0") |
|
|
| `user_id` | INTEGER | Usually 1 |
|
|
| `class` | TEXT | **Must be NULL** for custom items (not a class name) |
|
|
| `appid` | TEXT | NULL for custom items |
|
|
| `deleted_at` | TEXT | NULL = active, timestamp = soft-deleted |
|
|
| `created_at` | TEXT | Can be NULL |
|
|
| `updated_at` | TEXT | Can be NULL |
|
|
|
|
### `item_tag` table — required for visibility
|
|
|
|
**Every item MUST have a corresponding entry in `item_tag`** or it won't appear on the dashboard!
|
|
|
|
```sql
|
|
INSERT INTO item_tag (item_id, tag_id) VALUES (<item_id>, 0);
|
|
```
|
|
|
|
All items use `tag_id=0`.
|
|
|
|
## Adding a Tile
|
|
|
|
```python
|
|
import sqlite3
|
|
db = "/var/lib/docker/volumes/heimdall_config/_data/www/app.sqlite"
|
|
conn = sqlite3.connect(db)
|
|
|
|
# Step 1: Insert the item
|
|
conn.execute("""
|
|
INSERT INTO items (title, colour, url, description, pinned, "order", type, user_id, class)
|
|
VALUES (?, ?, ?, ?, 0, 0, 0, 1, NULL)
|
|
""", ("Service Name", "#hexcolor", "http://192.168.50.98:PORT", "Optional description"))
|
|
|
|
# Step 2: Add the tag entry (MANDATORY — without this, tile won't show)
|
|
conn.execute("""
|
|
INSERT INTO item_tag (item_id, tag_id)
|
|
VALUES ((SELECT id FROM items WHERE title='Service Name'), 0)
|
|
""")
|
|
|
|
conn.commit()
|
|
conn.close()
|
|
```
|
|
|
|
## Updating URLs (Bulk)
|
|
|
|
```sql
|
|
-- Change all IPs at once
|
|
UPDATE items SET url = REPLACE(url, '192.168.50.150', '192.168.50.98');
|
|
```
|
|
|
|
## Deleting the Cache
|
|
|
|
Heimdall uses Laravel caching — after DB changes, clear it:
|
|
|
|
```sql
|
|
DELETE FROM cache;
|
|
DELETE FROM cache_locks;
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### Tile not appearing after insert
|
|
1. **Missing `item_tag` entry** — most common cause. Check with: `SELECT * FROM item_tag WHERE item_id=<id>;`
|
|
2. **Wrong `class` value** — custom items need `class=NULL`, not a string like "Audiobookshelf". Heimdall tries to load a PHP class from that name.
|
|
3. **`order` != 0** — items with non-zero order may be hidden. All working items use `order=0`.
|
|
4. **`type` is string "0" not integer 0** — set type to integer 0.
|