Document manual/API fallback for Homebox's missing entity types (#1593)

services/homebox.md gets auto-appended to Homebox's generated README
by write_readme(). Covers the installer's own opt-in fix plus a fully
manual UI walkthrough and a direct curl/API path, for anyone who'd
rather not paste a token into the installer or who's confirmed a
multi-collection setup isn't worth chasing through it.

UI navigation (collection selector -> Collection options -> Entity
Types tab, /collection/entity-types) confirmed against Homebox's own
frontend source rather than guessed.
This commit is contained in:
Claude
2026-08-28 11:10:07 +00:00
parent fe9ff46081
commit 07a6786ea5
+54
View File
@@ -0,0 +1,54 @@
## "Please select an entity type" with an empty type dropdown
Some collections hit an upstream Homebox bug
([sysadminsmedia/homebox#1593](https://github.com/sysadminsmedia/homebox/issues/1593)):
the default `Location`/`Item` entity types never get seeded, so the Create
dialog's type dropdown comes up empty and every Location/Item creation fails
with "Please select an entity type."
### Option 1 — let the installer fix it
Re-run `sudo ./setup.sh homebox`, choose **update**, and say yes when asked
"Hit 'Please select an entity type' with an empty type list...?" You'll need
a Homebox API token (see step 2 below) — it's used once, right then, and
never written to `.env` or disk.
This only fixes the ONE collection that token's account belongs to. Homebox
has no documented way to switch a token between collections, so a
multi-collection setup needs this repeated once per collection — not
something the installer can do for you in one pass, and not really worth
the trouble if you've only hit this on one collection already.
### Option 2 — fix it by hand in the UI
1. Log into Homebox (register first if you haven't — the first account
becomes the admin).
2. Click the **collection selector** (shows your current collection's name,
near the top of the page) → **Collection options** (gear icon). This
opens Collection Settings.
3. Click the **Entity Types** tab (`/collection/entity-types`).
4. Click **Create**, add:
- Name: `Location`, with **Is Location** toggled **ON**
- Name: `Item`, with **Is Location** toggled **OFF**
5. Go back to the Create (+) dialog — "Select a type..." now lists both, so
you can create Locations and Items normally.
If you use more than one collection, repeat step 24 once per collection —
entity types are scoped per collection, not shared across your whole
Homebox instance.
### Option 3 — fix it via the API directly
Needs an API token from your profile menu (**Create API Token**):
```bash
curl -X POST "http://localhost:<port>/api/v1/entity-types" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"name":"Location","isLocation":true}'
curl -X POST "http://localhost:<port>/api/v1/entity-types" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"name":"Item","isLocation":false}'
```