initial commit

skills/devops/selfhosted-migration/references/heimdall-sqlite-management.md

@@ -0,0 +1,91 @@
+# 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.