HomeBox

https://github.com/sysadminsmedia/homebox
Admin
HomeBox is an inventory and organization system for home users that simplifies managing household...
Tokens:56,544
Snippets:556
Trust Score:8.1
License:AGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start the development server with pnpm run dev

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/documentation/index.mdx

Starts the Starlight documentation development server. The site will be available at http://localhost:3000 and automatically reloads on file changes.

```bash
pnpm run dev
```

--------------------------------

### Ent query examples

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Shows common ent queries: get by ID, query with relationships, count, filter with And, and pagination using Offset and Limit.

```go
// Get a single user by ID
user, err := client.User.Get(ctx, userID)

// Get all items for a group with relationships
items, err := client.Item.Query().
	Where(item.GroupID(groupID)).
	WithLabels().
	WithLocation().
	All(ctx)

// Count items
count, err := client.Item.Query().
	Where(item.GroupID(groupID)).
	Count(ctx)

// Query with filters
items, err := client.Item.Query().
	Where(
		item.And(
			item.GroupID(groupID),
			item.Archived(false),
			item.NameContains("search term"),
		),
	).
	All(ctx)

// Pagination
items, err := client.Item.Query().
	Where(item.GroupID(groupID)).
	Offset(page * pageSize).
	Limit(pageSize).
	All(ctx)
```

--------------------------------

### GET List All Items with adapters.Command

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Shows the GET list-all pattern using adapters.Command when there is no request body or query parameters. The handler returns a slice of repo.LabelSummary and is registered with the route /v1/labels.

```go
// HandleLabelsGetAll godoc
//
//	@Summary	Get All Labels
//	@Tags		Labels
//	@Produce	json
//	@Success	200	{object}	[]repo.LabelSummary
//	@Router		/v1/labels [GET]
//	@Security	Bearer
func (ctrl *V1Controller) HandleLabelsGetAll() errchain.HandlerFunc {
    fn := func(r *http.Request) ([]repo.LabelSummary, error) {
        auth := services.NewContext(r.Context())
        return ctrl.repo.Labels.GetAll(auth, auth.GID)
    }

    return adapters.Command(fn, http.StatusOK)
}
```

```go
r.Get("/labels", chain.ToHandlerFunc(v1Ctrl.HandleLabelsGetAll(), userMW...))
```

--------------------------------

### Private network example: systemd-run with unix socket

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/index.mdx

Starts Homebox in an isolated network using systemd-run with PrivateNetwork=yes, preventing external requests. The command uses a unix socket at /run/user/$UID/homebox.sock. Output shows the server starting and a failed GitHub release check due to network isolation.

```bash
❯ sudo systemd-run --property=PrivateNetwork=yes --uid $UID --pty --same-dir --wait --collect homebox --web-host "unix?path=/run/user/$UID/homebox.sock"
Running as unit: run-p74482-i74483.service
Press ^] three times within 1s to disconnect TTY.
2025/07/11 22:33:29 goose: no migrations to run. current version: 20250706190000
10:33PM INF ../../../go/src/app/app/api/handlers/v1/v1_ctrl_auth.go:98 > registering auth provider name=local
10:33PM INF ../../../go/src/app/app/api/main.go:275 > Server is running on unix?path=/run/user/1000/homebox.sock
10:33PM ERR ../../../go/src/app/app/api/main.go:403 > failed to get latest github release error="failed to make latest version request: Get \"https://api.github.com/repos/sysadminsmedia/homebox/releases/l
atest\": dial tcp: lookup api.github.com on [::1]:53: read udp [::1]:50951->[::1]:53: read: connection refused"
10:33PM INF ../../../go/src/app/internal/web/mid/logger.go:36 > request received method=GET path=/ rid=hname/PoXyRgt6ol-000001
10:33PM INF ../../../go/src/app/internal/web/mid/logger.go:41 > request finished method=GET path=/ rid=hname/PoXyRgt6ol-000001 status=0

```

--------------------------------

### SQLite3 SQL Migration Example (20220929052821_init.sql)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Example of a SQL migration for SQLite3 using Goose annotations. It creates a users table with a unique email and timestamps. Includes a Down migration that cannot be reversed.

```sql
-- +goose Up
-- +goose StatementBegin
CREATE TABLE IF NOT EXISTS users (
    id TEXT PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- +goose StatementEnd

-- +goose Down
-- This migration cannot be reversed
```

--------------------------------

### Systemd socket example: homebox.socket

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/index.mdx

Systemd socket unit file that listens on /run/homebox.sock with group caddy and mode 0660, allowing only the Caddy webserver to access Homebox. Part of a secure setup where other processes cannot bypass the webserver.

```systemd
# /usr/local/lib/systemd/system/homebox.socket
[Unit]
Description=Homebox socket

[Socket]
ListenStream=/run/homebox.sock
SocketGroup=caddy
SocketMode=0660

[Install]
WantedBy=sockets.target

```

--------------------------------

### PostgreSQL SQL Migration Example (20220929052825_init.sql)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Example of a SQL migration for PostgreSQL using Goose annotations. Creates a users table with a uuid primary key and timestamps. Includes a Down migration that cannot be reversed.

```sql
-- +goose Up
CREATE TABLE IF NOT EXISTS users (
    id uuid PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- +goose Down
-- (cannot reverse)
```

--------------------------------

### Run Homebox with Docker (Regular image)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/install.mdx

Runs the Homebox container with the regular image. Suitable for testing, not recommended for production. Requires Docker installed and a writable data folder.

```bash
docker run -d --name homebox --restart unless-stopped \
--publish 3100:7745 --env HBOX_OPTIONS_ALLOW_ANALYTICS=false \
--env HBOX_AUTH_API_KEY_PEPPER=some_random_string \
--volume /path/to/data/folder:/data \
ghcr.io/sysadminsmedia/homebox:latest
```

--------------------------------

### Start systemd socket

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/index.mdx

Command to start the Homebox systemd socket unit, which activates the service on demand.

```bash
systemctl start homebox.socket

```

--------------------------------

### GET with Query Parameters using adapters.Query

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Shows the GET with query parameters pattern using adapters.Query. The handler parses a LocationQuery struct with a FilterChildren bool field and returns a slice of repo.LocationOutCount.

```go
// HandleLocationGetAll godoc
//
//	@Summary	Get All Locations
//	@Tags		Locations
//	@Produce	json
//	@Param		filterChildren	query		bool	false	"Filter locations with parents"
//	@Success	200				{object}	[]repo.LocationOutCount
//	@Router		/v1/locations [GET]
//	@Security	Bearer
func (ctrl *V1Controller) HandleLocationGetAll() errchain.HandlerFunc {
    fn := func(r *http.Request, q repo.LocationQuery) ([]repo.LocationOutCount, error) {
        auth := services.NewContext(r.Context())
        return ctrl.repo.Locations.GetAll(auth, auth.GID, q)
    }

    return adapters.Query(fn, http.StatusOK)
}
```

```go
type LocationQuery struct {
    FilterChildren bool
}
```

--------------------------------

### Quick Start: Run Homebox with Docker

Source: https://github.com/sysadminsmedia/homebox/blob/main/README.md

Use this bash script to generate a pepper key, set up the data folder permissions, and run the Homebox container. The command publishes port 3100 to 7745, sets the timezone, and mounts the data folder. Commented lines show alternative image tags for rootless and hardened variants.

```bash
# Save pepper to local file
openssl rand -base64 48 > hbox.pepper
chmod 400 hbox.pepper
# If using the rootless or hardened image, ensure data 
# folder has correct permissions
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder
docker run -d \
  --name homebox \
  --restart unless-stopped \
  --publish 3100:7745 \
  --env TZ=Europe/Bucharest \
  --env HBOX_AUTH_API_KEY_PEPPER=$(cat hbox.pepper) \
  --volume /path/to/data/folder/:/data \
  ghcr.io/sysadminsmedia/homebox:latest
# ghcr.io/sysadminsmedia/homebox:latest-rootless
# ghcr.io/sysadminsmedia/homebox:latest-hardened
```

--------------------------------

### Go Migration Example for SQLite3 (20241226183418_sync_children.go)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Go migration using goose.AddMigrationContext. Checks if a column exists before adding it, and provides a no-op Down migration. Used when SQL is insufficient.

```go
package sqlite3

import (
	"context"
	"database/sql"
	"fmt"

	"github.com/pressly/goose/v3"
)

//nolint:gochecknoinits
func init() {
	goose.AddMigrationContext(Up20241226183418, Down20241226183418)
}

func Up20241226183418(ctx context.Context, tx *sql.Tx) error {
	// Check if the column already exists
	columnName := "sync_child_items_locations"
	query := `
		SELECT name
		FROM pragma_table_info('items')
		WHERE name = 'sync_child_items_locations';
	`
	err := tx.QueryRowContext(ctx, query).Scan(&columnName)
	if err == nil {
		// Column already exists, skip migration
		return nil
	}

	// Add the column if it doesn't exist
	_, err = tx.ExecContext(ctx, `
		ALTER TABLE items ADD COLUMN sync_child_items_locations BOOLEAN DEFAULT FALSE;
	`)
	if err != nil {
		return fmt.Errorf("failed to add column: %w", err)
	}

	return nil
}

func Down20241226183418(ctx context.Context, tx *sql.Tx) error {
	// This migration is a no-op for SQLite (cannot reverse)
	return nil
}
```

--------------------------------

### Frontmatter example

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/documentation/index.mdx

Required frontmatter for every documentation page, defining title, description, and sidebar order.

```markdown
---
title: Page Title
description: A brief description of the page
sidebar:
  order: 1
---
```

--------------------------------

### GET /v1/entities/fields

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get all custom field names.

```APIDOC
## GET /v1/entities/fields

### Description
Get all custom field names.

### Method
GET

### Endpoint
/v1/entities/fields

### Response
#### Success Response (200)
- **fields** (array) - List of custom field names.

#### Response Example
```json
{
  "fields": []
}
```
```

--------------------------------

### GET /label-service

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/external-label-service.mdx

Documentation for the external label service HTTP GET request used to generate asset and location labels in homebox.

```APIDOC
## GET /label-service

### Description
Generates a label image for an asset or location by sending an HTTP GET request to the external label service. The service returns an image file that homebox uses when creating labels from an item or location.

### Method
GET

### Endpoint
The endpoint is configured via the `HBOX_LABEL_MAKER_LABEL_SERVICE_URL` environment variable. All parameters are passed as query string parameters.

### Parameters
#### Query Parameters
- **AdditionalInformation** (string) - Optional - Extra free text to include on the label. Value from `HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION`.
- **ComponentPadding** (int) - Optional - Padding around label components (pixels). Value from `HBOX_LABEL_MAKER_PADDING`.
- **DescriptionFontSize** (float) - Optional - Font size for the description text.
- **DescriptionText** (string) - Optional - Descriptive text, can be multi-line. Item name or "Homebox Location".
- **Dpi** (float) - Optional - Rendering resolution (dots per inch).
- **DynamicLength** (bool) - Optional - Whether the label length should auto-adjust. Value from `HBOX_LABEL_MAKER_DYNAMIC_LENGTH`.
- **Height** (int) - Optional - Label height in pixels. Value from `HBOX_LABEL_MAKER_HEIGHT`.
- **Margin** (int) - Optional - Margin around the label in pixels. Value from `HBOX_LABEL_MAKER_MARGIN`.
- **QrSize** (int) - Optional - Size of the QR code element in pixels.
- **TitleFontSize** (float) - Optional - Font size for the title text.
- **TitleText** (string) - Optional - Main label title (e.g. product code). Asset ID or Location Name.
- **URL** (string) - Optional - URL to be encoded into the QR code. Generated based on the configured homebox URL and Asset / Location ID.
- **Width** (int) - Optional - Label width in pixels. Value from `HBOX_LABEL_MAKER_WIDTH`.

### Headers
- **User-Agent**: Homebox-LabelMaker/1.0
- **Accept**: image/*

### Response
#### Success Response (200)
- **Content-Type**: image/* (as specified in the response header)
- **Size**: Less than or equal to `HBOX_WEB_MAX_UPLOAD_SIZE` (Default: 10Mb)
- **Time**: Within the time specified in `HBOX_LABEL_MAKER_LABEL_SERVICE_TIMEOUT` (Default 30s)

#### Response Example
The response is an image file (e.g., PNG, JPEG) with a Content-Type of image/*.
```

--------------------------------

### Group Scoping Query Example

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Shows how to scope queries to the user's group using the GroupMixin. The repository method enforces filtering by groupID.

```go
// Always scope queries to the user's group
items, err := repo.Items.QueryByGroup(ctx, auth.GID, query)

// This is enforced in the repository layer
func (r *ItemsRepository) GetAll(ctx context.Context, groupID uuid.UUID) ([]ItemOut, error) {
	items, err := r.db.Item.Query().
		Where(item.GroupID(groupID)). // ← ALWAYS filter by groupID
		All(ctx)
	// ...
}
```

--------------------------------

### Systemd socket example: homebox.service

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/index.mdx

Systemd service unit that runs Homebox with DynamicUser, StateDirectory, and the HBOX_WEB_HOST environment variable set to sysd?name=homebox.socket. Includes security hardening options like NoNewPrivileges and SystemCallFilter.

```systemd
# /usr/local/lib/systemd/system/homebox.service
[Unit]
Description=Homebox
After=network.target
Documentation=https://homebox.software

[Service]
DynamicUser=yes
StateDirectory=homebox
Environment=HBOX_WEB_HOST=sysd?name=homebox.socket
WorkingDirectory=/var/lib/homebox

ExecStart=/usr/local/bin/homebox

NoNewPrivileges=yes
CapabilityBoundingSet=
RestrictNamespaces=true
SystemCallFilter=@system-service

```

--------------------------------

### Soft Delete Example

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Demonstrates marking an item as archived instead of deleting it. Queries exclude archived items by default.

```go
// Mark as archived instead of deleting
item, err := repo.Items.Update(ctx, ItemUpdate{
	ID:       itemID,
	Archived: true,
})

// Query excludes archived by default
items, err := repo.Items.GetAll(ctx, groupID)
```

--------------------------------

### Block multiple networks for webhook notifiers

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/user-guide/notifiers.mdx

Example of blocking multiple networks using CIDR notation.

```bash
HBOX_NOTIFIER_BLOCK_NETS="192.168.0.0/16;172.16.0.0/12;10.10.0.0/16"
```

--------------------------------

### GET Single Item by ID with adapters.CommandID

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Shows the GET single item by ID pattern using adapters.CommandID. The first argument to adapters.CommandID() is the path parameter name ("id") and must match the route definition.

```go
// HandleItemGet godocs
//
//	@Summary	Get Item
//	@Tags		Items
//	@Produce	json
//	@Param		id	path		string	true	"Item ID"
//	@Success	200	{object}	repo.ItemOut
//	@Router		/v1/items/{id} [GET]
//	@Security	Bearer
func (ctrl *V1Controller) HandleItemGet() errchain.HandlerFunc {
    fn := func(r *http.Request, ID uuid.UUID) (repo.ItemOut, error) {
        auth := services.NewContext(r.Context())
        return ctrl.repo.Items.GetOneByGroup(auth, auth.GID, ID)
    }

    return adapters.CommandID("id", fn, http.StatusOK)
}
```

--------------------------------

### Set custom DNS64 prefix for webhook notifiers

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/user-guide/notifiers.mdx

Example of setting a custom DNS64 prefix for networks using a non-standard NAT64 translation prefix.

```bash
HBOX_NOTIFIER_DNS64_NETS="2001:db8:64::/96"
```

--------------------------------

### Add PostgreSQL service to compose.yml

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/database.mdx

Add this PostgreSQL service definition to your compose.yml file to start a PostgreSQL database for Homebox. Change the POSTGRES_PASSWORD environment variable to a secure password; you can also adjust POSTGRES_USER and POSTGRES_DB. No ports section is needed because the service is automatically exposed to the Homebox compose network.

```yaml
postgres:
  image: postgres:17-alpine
  restart: unless-stopped
  volumes:
    - postgres:/var/lib/postgresql/data
  environment:
    POSTGRES_PASSWORD: your_secure_password
    POSTGRES_USER: homebox
    POSTGRES_DB: homebox
...
volumes:
...
  postgres:
```

--------------------------------

### Frontend telemetry proxy payload example

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/opentelemetry.mdx

Example JSON payload for POSTing to the /api/v1/telemetry endpoint. The payload must include a 'spans' array. Request bodies are limited to 1 MiB, larger payloads return 413. Invalid payloads return 400, valid ones return 202.

```json
{
  "resourceAttributes": {
	"deployment.environment": "prod"
  },
  "spans": [
	{
	  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
	  "spanId": "00f067aa0ba902b7",
	  "name": "ui.click",
	  "kind": "client",
	  "startTime": 1710000000000,
	  "endTime": 1710000000150
	}
  ]
}
```

--------------------------------

### Extract authenticated user with services.NewContext

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Use services.NewContext(r.Context()) in every handler to get the authenticated user. The middleware sets up the context automatically. Always scope queries to auth.GID for multi-tenancy.

```go
auth := services.NewContext(r.Context())
// auth.UID  - Current user's ID
// auth.GID  - Current user's group ID (for multi-tenancy)
// auth.User - Full user object
```

--------------------------------

### GET /v1/entities

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Query entities. Returns items by default; pass `?isLocation=true` for locations.

```APIDOC
## GET /v1/entities

### Description
Query entities. Returns items by default; pass `?isLocation=true` for locations.

### Method
GET

### Endpoint
/v1/entities

### Parameters
#### Query Parameters
- **isLocation** (boolean) - Optional - If true, returns locations instead of items.

### Response
#### Success Response (200)
- **entities** (array) - List of entity objects.

#### Response Example
```json
{
  "entities": []
}
```
```

--------------------------------

### Block a single IP for webhook notifiers

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/user-guide/notifiers.mdx

Example of blocking a single IP address using CIDR notation.

```bash
HBOX_NOTIFIER_BLOCK_NETS="192.168.1.100/32"
```

--------------------------------

### Create Entity Type Request Body (POST /v1/entity-types)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Example request body for creating an entity type. isLocation true makes entities of this type act as containers; defaultTemplateId is optional and auto-applies template defaults when set.

```json
{
  "name": "Shelf",
  "isLocation": true,
  "icon": "",
  "defaultTemplateId": "uuid-or-omit"
}
```

--------------------------------

### Notification Message Format

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/user-guide/notifiers.mdx

Example message format for scheduled maintenance reminders. Includes the date and a list of maintenance items.

```text
Homebox Maintenance for (YYYY-MM-DD):
 - Maintenance Item 1
 - Maintenance Item 2
 - Maintenance Item 3
```

--------------------------------

### Build documentation for production

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/documentation/index.mdx

Run this command to build the documentation for production. The built site will be in the dist/ directory.

```bash
pnpm run build
```

--------------------------------

### Preview production build locally

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/documentation/index.mdx

Run this command to preview the production build locally.

```bash
pnpm run preview
```

--------------------------------

### Register Repository in repos_all.go

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Shows how to add the MyEntities repository to the AllRepos struct and initialize it in the New function. Existing fields and repos are indicated with comments.

```go
type AllRepos struct {
    // ... existing fields ...
    MyEntities *MyEntitiesRepository
}

func New(db *ent.Client, ...) *AllRepos {
    return &AllRepos{
        // ... existing repos ...
        MyEntities: &MyEntitiesRepository{db},
    }
}

```

--------------------------------

### GET /v1/entities/fields/values

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get all values for a given custom field.

```APIDOC
## GET /v1/entities/fields/values

### Description
Get all values for a given custom field.

### Method
GET

### Endpoint
/v1/entities/fields/values

### Parameters
#### Query Parameters
- **field** (string) - Required - The custom field name.

### Response
#### Success Response (200)
- **values** (array) - List of values for the custom field.

#### Response Example
```json
{
  "values": []
}
```
```

--------------------------------

### GET /v1/entities/tree

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get the location/item tree (replaces `/v1/locations/tree`).

```APIDOC
## GET /v1/entities/tree

### Description
Get the location/item tree (replaces `/v1/locations/tree`).

### Method
GET

### Endpoint
/v1/entities/tree

### Response
#### Success Response (200)
- **tree** (object) - The location/item tree.

#### Response Example
```json
{
  "tree": {}
}
```
```

--------------------------------

### GET /v1/entities/{id}

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get a single entity by ID.

```APIDOC
## GET /v1/entities/{id}

### Description
Get a single entity by ID.

### Method
GET

### Endpoint
/v1/entities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity.

### Response
#### Success Response (200)
- **entity** (object) - The requested entity.

#### Response Example
```json
{
  "entity": {}
}
```
```

--------------------------------

### Run Homebox with Docker (Rootless image)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/install.mdx

Runs the Homebox container with the rootless image. Before running, the data folder must be created and owned by UID/GID 65532. The rootless image includes the MQTT client.

```bash
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder
# --------
# Run the container
docker run -d --name homebox --restart unless-stopped \
--publish 3100:7745 --env HBOX_OPTIONS_ALLOW_ANALYTICS=false \
--env HBOX_AUTH_API_KEY_PEPPER=some_random_string \
--volume /path/to/data/folder:/data \
ghcr.io/sysadminsmedia/homebox:latest-rootless
```

--------------------------------

### GET /v1/entities/{id}/maintenance

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get maintenance log for an entity.

```APIDOC
## GET /v1/entities/{id}/maintenance

### Description
Get maintenance log for an entity.

### Method
GET

### Endpoint
/v1/entities/{id}/maintenance

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity.

### Response
#### Success Response (200)
- **maintenance** (array) - List of maintenance entries.

#### Response Example
```json
{
  "maintenance": []
}
```
```

--------------------------------

### Useful Development Commands

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Lists common task commands for regenerating ent code, running tests, linting, and running the application with SQLite3 or PostgreSQL.

```bash
task generate          # Regenerate ent code
task go:test          # Run database tests
task go:lint          # Check for issues
task go:run          # Run with SQLite3
task go:run:postgres # Run with PostgreSQL
```

--------------------------------

### GET /v1/entities/{id}/path

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Get the full hierarchy path to an entity.

```APIDOC
## GET /v1/entities/{id}/path

### Description
Get the full hierarchy path to an entity.

### Method
GET

### Endpoint
/v1/entities/{id}/path

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity.

### Response
#### Success Response (200)
- **path** (array) - The hierarchy path to the entity.

#### Response Example
```json
{
  "path": []
}
```
```

--------------------------------

### Create Repository (repo_myentities.go)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Defines the MyEntitiesRepository with a GetAll method that queries entities by group ID. It uses the Ent client and returns a slice of MyEntitySummary.

```go
package repo

import (
    "context"
    "github.com/google/uuid"
    "github.com/sysadminsmedia/homebox/backend/internal/data/ent"
    "github.com/sysadminsmedia/homebox/backend/internal/data/ent/myentity"
)

type MyEntitiesRepository struct {
    db *ent.Client
}

func (r *MyEntitiesRepository) GetAll(ctx context.Context, groupID uuid.UUID) ([]MyEntitySummary, error) {
    entities, err := r.db.MyEntity.Query().
        Where(myentity.GroupID(groupID)).
        All(ctx)
    if err != nil {
        return nil, err
    }
    return mapMyEntitySummaries(entities), nil
}

```

--------------------------------

### CLI Options Usage

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/configure/index.mdx

Displays the full list of command-line options for the homebox binary, including flags for authentication, database, logging, mailer, notifier, OIDC, and label maker settings. Each option shows its type and default value where applicable.

```sh
Usage: homebox [options...] [arguments...]

OPTIONS
      --auth-api-key-pepper                 <string>
      --auth-rate-limit-base-backoff        <duration>  (default: 10s)
      --auth-rate-limit-enabled             <bool>      (default: true)
      --auth-rate-limit-max-attempts        <int>       (default: 5)
      --auth-rate-limit-max-backoff         <duration>  (default: 5m)
      --auth-rate-limit-window              <duration>  (default: 1m)
      --barcode-open-food-facts-contact     <string>
      --barcode-token-barcodespider         <string>
      --database-database                   <string>
      --database-driver                     <string>    (default: sqlite3)
      --database-host                       <string>
      --database-password                   <string>
      --database-port                       <string>
      --database-pub-sub-conn-string        <string>    (default: mem://{{ .Topic }})
      --database-sqlite-path                <string>    (default: ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite)
      --database-ssl-cert                   <string>
      --database-ssl-key                    <string>
      --database-ssl-mode                   <string>    (default: require)
      --database-ssl-root-cert              <string>
      --database-username                   <string>
      --debug-enabled                       <bool>      (default: false)
      --debug-port                          <string>    (default: 4000)
      --demo                                <bool>
  -h, --help                                                                                                                                                       display this help message
      --label-maker-additional-information  <string>
      --label-maker-bold-font-path          <string>
      --label-maker-dynamic-length          <bool>      (default: true)
      --label-maker-font-size               <float>     (default: 32.0)
      --label-maker-height                  <int>       (default: 200)
      --label-maker-label-service-timeout   <int>
      --label-maker-label-service-url       <string>
      --label-maker-margin                  <int>       (default: 32)
      --label-maker-padding                 <int>       (default: 32)
      --label-maker-print-command           <string>
      --label-maker-regular-font-path       <string>
      --label-maker-width                   <int>       (default: 526)
      --log-format                          <string>    (default: text)
      --log-level                           <string>    (default: info)
      --mailer-from                         <string>
      --mailer-host                         <string>
      --mailer-password                     <string>
      --mailer-port                         <int>
      --mailer-username                     <string>
      --mode                                <string>    (default: development)
      --notifier-allow-nets                 <string>
      --notifier-block-nets                 <string>
      --notifier-block-bogon-nets           <bool>      (default: true)
      --notifier-block-cloud-metadata       <bool>      (default: true)
      --notifier-block-local-nets           <bool>      (default: false)
      --notifier-block-localhost            <bool>      (default: false)
      --notifier-dns64-nets                 <string>    (default: 64:ff9b::/96;64:ff9b:1::/48)
      --oidc-allowed-groups                 <string>
      --oidc-auto-redirect                  <bool>      (default: false)
      --oidc-button-text                    <string>    (default: Sign in with OIDC)
      --oidc-client-id                      <string>
      --oidc-client-secret                  <string>
      --oidc-email-claim                    <string>    (default: email)
```

--------------------------------

### Create a new Starlight project

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/README.md

Scaffolds a new Astro project using the Starlight template. Run from the terminal in the directory where you want the project created.

```bash
pnpm create astro@latest -- --template starlight
```

--------------------------------

### GET /v1/entities/export

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Export entities as CSV.

```APIDOC
## GET /v1/entities/export

### Description
Export entities as CSV.

### Method
GET

### Endpoint
/v1/entities/export

### Response
#### Success Response (200)
- **file** (file) - CSV file containing entities.
```

--------------------------------

### Run Backend Tests with task go:test

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Runs the backend test suite using the `task go:test` command.

```bash
task go:test

```

--------------------------------

### Run Homebox with Docker (Hardened image)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/install.mdx

Runs the Homebox container with the hardened distroless image. The data folder must be created and owned by UID/GID 65532. This image does not contain the MQTT client, so MQTT is not supported.

```bash
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder
# --------
# Run the container
docker run -d --name homebox --restart unless-stopped \
--publish 3100:7745 --env HBOX_OPTIONS_ALLOW_ANALYTICS=false \
--env HBOX_AUTH_API_KEY_PEPPER=some_random_string \
--volume /path/to/data/folder:/data \
ghcr.io/sysadminsmedia/homebox:latest-hardened
```

--------------------------------

### GET /v1/entity-types

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

List all entity types for the current group.

```APIDOC
## GET /v1/entity-types

### Description
List all entity types for the current group.

### Method
GET

### Endpoint
/v1/entity-types

### Response
#### Success Response (200)
- **entityTypes** (array) - List of entity types.

#### Response Example
```json
{
  "entityTypes": []
}
```
```

--------------------------------

### Create item with ent builder

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Shows how to create a new item using the type-safe ent create builder with Set and Add methods.

```go
item, err := client.Item.Create().
	SetName("Laptop").
	SetQuantity(1).
	SetArchived(false).
	SetGroupID(groupID).
	SetLocationID(locationID).
	AddLabelIDs(labelIDs...).
	Save(ctx)
```

--------------------------------

### GET /v1/entities/fields/values

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Retrieves the possible values for a specified custom field.

```APIDOC
## GET /v1/entities/fields/values

### Description
Retrieves the possible values for a specified custom field.

### Method
GET

### Endpoint
/v1/entities/fields/values

### Parameters
#### Query Parameters
- **field** (string) - Required - The custom field name to get values for.
```

--------------------------------

### HandleItemsGetAll: Manual Query Parameter Parsing

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Manually parses complex query parameters (page, pageSize, q, labels, locations, includeArchived) inside the handler because standard adapters cannot handle them. Uses helper functions like queryIntOrNegativeOne, queryUUIDList, and queryBool to build a repo.ItemQuery, then queries items by group and returns a JSON response.

```go
// HandleItemsGetAll godoc
//
//	@Summary	Query All Items
//	@Tags		Items
//	@Produce	json
//	@Param		q			query		string		false	"search string"
//	@Param		page		query		int			false	"page number"
//	@Param		pageSize	query		int			false	"items per page"
//	@Param		labels		query		[]string	false	"label IDs"			collectionFormat(multi)
//	@Param		locations	query		[]string	false	"location IDs"		collectionFormat(multi)
//	@Success	200			{object}	repo.PaginationResult[repo.ItemSummary]{}
//	@Router		/v1/items [GET]
//	@Security	Bearer
func (ctrl *V1Controller) HandleItemsGetAll() errchain.HandlerFunc {
    extractQuery := func(r *http.Request) repo.ItemQuery {
        params := r.URL.Query()
        return repo.ItemQuery{
            Page:            queryIntOrNegativeOne(params.Get("page")),
            PageSize:        queryIntOrNegativeOne(params.Get("pageSize")),
            Search:          params.Get("q"),
            LocationIDs:     queryUUIDList(params, "locations"),
            LabelIDs:        queryUUIDList(params, "labels"),
            IncludeArchived: queryBool(params.Get("includeArchived")),
        }
    }

    return func(w http.ResponseWriter, r *http.Request) error {
        ctx := services.NewContext(r.Context())
        items, err := ctrl.repo.Items.QueryByGroup(ctx, ctx.GID, extractQuery(r))
        if err != nil {
            return validate.NewRequestError(err, http.StatusInternalServerError)
        }
        return server.JSON(w, http.StatusOK, items)
    }
}
```

--------------------------------

### GET /v1/entities/{id}/attachments/{attachment_id}

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Download an attachment file.

```APIDOC
## GET /v1/entities/{id}/attachments/{attachment_id}

### Description
Download an attachment file.

### Method
GET

### Endpoint
/v1/entities/{id}/attachments/{attachment_id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity.
- **attachment_id** (string) - Required - The ID of the attachment.

### Response
#### Success Response (200)
- **file** (file) - The attachment file.
```

--------------------------------

### GET /v1/entities/tree

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Retrieves the entity tree, optionally including items (non-location entities).

```APIDOC
## GET /v1/entities/tree

### Description
Retrieves the entity tree, optionally including items (non-location entities).

### Method
GET

### Endpoint
/v1/entities/tree

### Parameters
#### Query Parameters
- **withItems** (bool) - Optional - Default: false - Include items (non-location entities) in the tree.
```

--------------------------------

### NewControllerV1 constructor

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Constructor for V1Controller that initializes it with required dependencies and applies optional functional options. Sets allowRegistration to true by default.

```go
func NewControllerV1(
    svc *services.AllServices,
    repos *repo.AllRepos,
    bus *eventbus.EventBus,
    config *config.Config,
    options ...func(*V1Controller),
) *V1Controller {
    ctrl := &V1Controller{
        repo:              repos,
        svc:               svc,
        allowRegistration: true,
        bus:               bus,
        config:            config,
    }

    for _, opt := range options {
        opt(ctrl)
    }

    return ctrl
}
```

--------------------------------

### GET /v1/entities

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Retrieves a list of entities (items or locations) with support for filtering, searching, pagination, and sorting.

```APIDOC
## GET /v1/entities

### Description
Retrieves a list of entities (items or locations) with support for filtering, searching, pagination, and sorting.

### Method
GET

### Endpoint
/v1/entities

### Parameters
#### Query Parameters
- **isLocation** (bool) - Optional - Default: false - `true` returns locations only (with `itemCount` on each). Omit or `false` for items only.
- **filterChildren** (bool) - Optional - Default: false - When `isLocation=true`, return only root locations (those with no parent).
- **parentIds** ([]string) - Optional - Filter by parent entity ID. **Replaces the old `locations` parameter.**
- **q** (string) - Optional - Search query.
- **tags** ([]string) - Optional - Filter by tag IDs.
- **negateTags** (bool) - Optional - Default: false - Exclude entities matching the given tags.
- **page** (int) - Optional - Page number for pagination.
- **pageSize** (int) - Optional - Items per page.
- **orderBy** (string) - Optional - Sort field (`name`, `createdAt`, `updatedAt`).
- **includeArchived** (bool) - Optional - Default: false - Include archived entities.
- **fields** ([]string) - Optional - Filter by custom field values (`fieldName=value` format).
```

--------------------------------

### Generic OTLP Collector (cloud, with prefix and authentication)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/opentelemetry.mdx

Environment variables for a cloud OTLP collector with a path prefix and authentication. Uses HTTP protocol, a secure connection, and sets the endpoint to collector.example.net with /otlp prefix.

```bash
HBOX_OTEL_ENABLED=true
HBOX_OTEL_ENDPOINT=collector.example.net
HBOX_OTEL_PATH_PREFIX=/otlp
HBOX_OTEL_HEADERS=Authentication=YOUR_INGESTION_TOKEN
HBOX_OTEL_PROTOCOL=http
HBOX_OTEL_INSECURE=false
HBOX_OTEL_SAMPLE_RATE=1.0
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/user-guide/notifiers.mdx

Development environment configuration with more flexibility: disables localhost and local network blocking while still blocking bogons and cloud metadata.

```bash
HBOX_NOTIFIER_BLOCK_LOCALHOST=false
HBOX_NOTIFIER_BLOCK_LOCAL_NETS=false
HBOX_NOTIFIER_BLOCK_BOGON_NETS=true
HBOX_NOTIFIER_BLOCK_CLOUD_METADATA=true
```

--------------------------------

### Repository pattern wrapping ent queries

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/database.mdx

Shows a repository that wraps ent queries for a cleaner API. Handles not-found errors by returning a zero value.

```go
// Repositories wrap ent queries for cleaner API
type ItemsRepository struct {
	db *ent.Client
}

func (r *ItemsRepository) GetOneByGroup(ctx context.Context, groupID, itemID uuid.UUID) (ItemOut, error) {
	item, err := r.db.Item.Query().
		Where(
			item.And(
				item.GroupID(groupID),
				item.ID(itemID),
			),
		).
		WithLabels().
		WithLocation().
		Only(ctx)

	if err != nil {
		if ent.IsNotFound(err) {
			return ItemOut{}, nil // Return zero value for not found
		}
		return ItemOut{}, err
	}

	return mapItemOut(item), nil
}
```

--------------------------------

### Adding a New Endpoint: Handler, Route, and Commands

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Steps to add a new endpoint: create a handler in `backend/app/api/handlers/v1/`, register the route in `backend/app/api/routes.go`, regenerate Swagger docs and TypeScript types with `task generate`, then build and test with `task go:build` and `task go:test`.

```go
// HandleMyEntityGet godoc
//
//	@Summary	Get MyEntity
//	@Tags		MyEntity
//	@Produce	json
//	@Param		id	path		string	true	"MyEntity ID"
//	@Success	200	{object}	repo.MyEntityOut
//	@Router		/v1/my-entity/{id} [GET]
//	@Security	Bearer
func (ctrl *V1Controller) HandleMyEntityGet() errchain.HandlerFunc {
    fn := func(r *http.Request, ID uuid.UUID) (repo.MyEntityOut, error) {
        auth := services.NewContext(r.Context())
        return ctrl.repo.MyEntity.GetOneByGroup(auth, auth.GID, ID)
    }

    return adapters.CommandID("id", fn, http.StatusOK)
}
```

```go
r.Get("/my-entity/{id}", chain.ToHandlerFunc(v1Ctrl.HandleMyEntityGet(), userMW...))
```

```bash
task generate
```

```bash
task go:build
task go:test
```

--------------------------------

### Paginated Response JSON

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Shows the consistent paginated response shape for all GET /v1/entities responses. totalPrice is the sum of purchasePrice * quantity for non-sold items in the result.

```json
{
  "page": 1,
  "pageSize": 50,
  "total": 120,
  "items": [],
  "totalPrice": 1234.56
}
```

--------------------------------

### POST Create New Item with adapters.Action

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/development/backend/api-handlers.mdx

Shows the POST create new item pattern using adapters.Action to decode the request body. POST handlers return http.StatusCreated (201) instead of http.StatusOK (200) following REST conventions.

```go
// HandleItemsCreate godoc
//
//	@Summary	Create Item
//	@Tags		Items
//	@Produce	json
//	@Param		payload	body		repo.ItemCreate	true	"Item Data"
//	@Success	201		{object}	repo.ItemOut
//	@Router		/v1/items [POST]
//	@Security	Bearer
func (ctrl *V1Controller) HandleItemsCreate() errchain.HandlerFunc {
    fn := func(r *http.Request, body repo.ItemCreate) (repo.ItemOut, error) {
        return ctrl.svc.Items.Create(services.NewContext(r.Context()), body)
    }

    return adapters.Action(fn, http.StatusCreated)
}
```

--------------------------------

### Steps component usage

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/contribute/documentation/index.mdx

Use the <Steps> component from @astrojs/starlight/components for numbered instructions.

```jsx
import { Steps } from '@astrojs/starlight/components'

<Steps>
    1. First step here
    2. Second step here
    3. Third step here
</Steps>
```

--------------------------------

### Project structure overview

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/README.md

Shows the default folder and file structure of an Astro + Starlight project. Starlight looks for .md or .mdx files in src/content/docs/, images can be added to src/assets/, and static assets go in public/.

```text
.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```

--------------------------------

### WebSocket event payload for entity.mutation

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/advanced/entity-merge-upgrade.mdx

Example JSON payload for the merged `entity.mutation` WebSocket event. Subscribe to this event to be notified of any entity change (create, update, delete) regardless of whether it's an item or location.

```json
{
  "event": "entity.mutation",
  "data": {
    "gid": "group-uuid"
  }
}
```

--------------------------------

### Docker Compose configuration for Homebox (Regular image)

Source: https://github.com/sysadminsmedia/homebox/blob/main/docs/src/content/docs/en/quick-start/install.mdx

Docker Compose configuration for the standard Homebox image. Sets environment variables for logging, upload size, analytics, and API key pepper. Maps port 3100 to 7745 and uses a named volume for data.

```yaml
services:
    homebox:
        image: ghcr.io/sysadminsmedia/homebox:latest
        restart: always
        environment:
            - HBOX_LOG_LEVEL=info
            - HBOX_LOG_FORMAT=text
            - HBOX_WEB_MAX_UPLOAD_SIZE=10
            # Please consider allowing analytics to help us improve Homebox (basic computer information, no personal data)
            - HBOX_OPTIONS_ALLOW_ANALYTICS=false
            # Use a strong random string for the pepper in production, it will be used to hash API keys and make them more secure
            - HBOX_AUTH_API_KEY_PEPPER=some_random_string
        volumes:
            - homebox-data:/data/
        ports:
            - 3100:7745

volumes:
    homebox-data:
        driver: local
```
Tokens:
Raw