Self-Hosting Homebox with Docker Compose

What Is Homebox?

Homebox is a self-hosted home inventory management system. It tracks your stuff — items, locations, labels, warranties, maintenance schedules, and receipts. Built-in QR code generation and scanning lets you label physical items and pull up their details instantly. It uses under 50 MB of RAM, supports photos and attachments, and includes CSV import/export for bulk operations. Maintained by sysadminsmedia (the original hay-kot/homebox repo was archived in June 2024).

Docker Compose Configuration

One container, one volume, zero dependencies:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:0.23.1
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    environment:
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10          # Max file upload in MB
      - HBOX_OPTIONS_ALLOW_REGISTRATION=true  # Disable after creating accounts
      - HBOX_OPTIONS_ALLOW_ANALYTICS=false
    volumes:
      - homebox-data:/data

volumes:
  homebox-data:

Start the stack:

docker compose up -d

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM (Homebox uses under 50 MB)

Initial Setup

1. Navigate to http://your-server:3100
2. Click Register and create your account (email + password)
3. Log in with your new credentials

Invite Other Users

To share your inventory with family members:

1. Go to your Profile settings
2. Generate an invite link
3. Share it — users who register through this link join your inventory

Users who register without an invite link get their own separate, isolated inventory.

Disable Registration

After all users are registered, prevent new signups:

- HBOX_OPTIONS_ALLOW_REGISTRATION=false

Restart the container to apply.

How Homebox Works

Homebox uses a hierarchy of locations and items:

Locations (nested)          Items
├── House                   ├── TV (Living Room)
│   ├── Living Room         ├── Sofa (Living Room)
│   ├── Kitchen             ├── Mixer (Kitchen → Counter)
│   │   ├── Counter         ├── Server (Office → Desk)
│   │   └── Pantry          └── Backup Drive (Office → Desk)
│   └── Office
│       └── Desk
└── Garage
    └── Shelf A

Each item can have:

Field	Description
Name, description	Basic identification
Location	Where it lives (nested locations supported)
Labels	Tags for categorization
Asset ID	Auto-incrementing ID (format: 000-001)
Quantity	How many you have
Manufacturer, model, serial number	Product identification
Purchase date, price	Cost tracking
Warranty expiration	Warranty management
Photos, attachments	Visual reference and documentation
Custom fields	Arbitrary key-value pairs
Maintenance schedule	Recurring maintenance reminders
Insurance status	Mark items as insured

Configuration

Behind a Reverse Proxy

Set the trust proxy option so QR codes and links use the correct URL scheme:

- HBOX_OPTIONS_TRUST_PROXY=true

Without this, generated QR codes may point to http:// instead of https://.

OIDC Single Sign-On

Integrate with Authentik, Keycloak, or Authelia:

- HBOX_OIDC_ENABLED=true
- HBOX_OIDC_ISSUER_URL=https://auth.example.com/realms/myrealm
- HBOX_OIDC_CLIENT_ID=homebox
- HBOX_OIDC_CLIENT_SECRET=your-client-secret
- HBOX_OIDC_SCOPE=openid profile email
- HBOX_OIDC_AUTO_REDIRECT=false           # true to skip local login page
- HBOX_OPTIONS_ALLOW_LOCAL_LOGIN=true      # Keep password login as fallback

PostgreSQL (Optional)

For larger inventories or better full-text search (especially with non-ASCII languages like Russian or Chinese), switch to PostgreSQL:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:0.23.1
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    environment:
      - HBOX_DATABASE_DRIVER=postgres
      - HBOX_DATABASE_HOST=homebox-db
      - HBOX_DATABASE_PORT=5432
      - HBOX_DATABASE_USERNAME=homebox
      - HBOX_DATABASE_PASSWORD=secure_password
      - HBOX_DATABASE_DATABASE=homebox
      - HBOX_DATABASE_SSL_MODE=disable
      - HBOX_OPTIONS_ALLOW_REGISTRATION=true
      - HBOX_OPTIONS_ALLOW_ANALYTICS=false
    volumes:
      - homebox-data:/data
    depends_on:
      - homebox-db

  homebox-db:
    image: postgres:17-alpine
    container_name: homebox-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=homebox
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=homebox
    volumes:
      - homebox-postgres:/var/lib/postgresql/data

volumes:
  homebox-data:
  homebox-postgres:

Label Printing

Homebox generates QR code labels that you can print and stick on items. Customize label dimensions:

- HBOX_LABEL_MAKER_WIDTH=526
- HBOX_LABEL_MAKER_HEIGHT=200
- HBOX_LABEL_MAKER_FONT_SIZE=32.0
- HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION=John's Inventory  # Printed on each label

Email Notifications

Configure SMTP for maintenance reminders:

- HBOX_MAILER_HOST=smtp.example.com
- HBOX_MAILER_PORT=587
- [email protected]
- HBOX_MAILER_PASSWORD=your-smtp-password
- [email protected]

Cloud Storage

Store uploaded files on S3-compatible storage instead of local disk:

- HBOX_STORAGE_CONN_STRING=s3://your-bucket?endpoint=https://s3.amazonaws.com&region=us-east-1

Supports AWS S3, MinIO, Google Cloud Storage, and Azure Blob Storage.

Notification Services

Homebox integrates with 18+ notification services for maintenance reminders via the Shoutrrr library: Discord, Slack, Telegram, ntfy, Gotify, email, generic webhooks, and more.

CSV Import

Bulk-import items from a spreadsheet:

1. Prepare a CSV file with columns matching Homebox’s import format
2. Go to Tools → Import
3. Upload your CSV
4. Items are created with locations auto-generated from the CSV

Homebox supports nested location paths in CSV (e.g., House/Kitchen/Counter) and deduplicates items using import references.

Reverse Proxy

Standard reverse proxy configuration — WebSocket support needed for full functionality:

location / {
    proxy_pass http://127.0.0.1:3100;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

See Reverse Proxy Setup.

Backup

All data lives in the /data volume (SQLite database, uploaded photos, attachments):

docker compose stop homebox
docker run --rm -v homebox-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/homebox-backup-$(date +%Y%m%d).tar.gz /data
docker compose start homebox

See Backup Strategy.

Troubleshooting

Copy-to-clipboard doesn’t work

Symptom: Clicking copy buttons does nothing. Fix: The clipboard API requires HTTPS or localhost. Set up a reverse proxy with SSL, or access via http://localhost:3100.

QR codes point to wrong URL

Symptom: Generated QR codes use http:// instead of https://, or point to the internal IP. Fix: Set HBOX_OPTIONS_TRUST_PROXY=true and ensure your reverse proxy sends X-Forwarded-Proto: https.

Users can’t see shared inventory

Symptom: A new user registers but has an empty inventory. Fix: They registered without an invite link. Users must register through an invite link (generated in your Profile) to join your inventory. Without it, they get an isolated inventory.

Timeouts on large file uploads

Symptom: Photo uploads fail with timeout errors. Fix: Increase HBOX_WEB_READ_TIMEOUT and HBOX_WEB_WRITE_TIMEOUT. The values must include a unit suffix: HBOX_WEB_READ_TIMEOUT=30s (not just 30).

Resource Requirements

• RAM: Under 50 MB idle (official specification)
• CPU: Minimal — single Go binary
• Disk: A few hundred MB for a typical home inventory with photos. Scales with attachments.

Verdict

Homebox hits the sweet spot between too-simple spreadsheets and too-complex enterprise asset management. The QR code system is genuinely useful — print labels, scan with your phone, and instantly see what’s in that storage box. Maintenance scheduling and warranty tracking add real practical value. And at under 50 MB RAM with zero dependencies, it’s one of the lightest self-hosted apps you can run.

The main limitation is that it’s designed for home use, not business inventory. There’s no barcode scanning integration for retail products (beyond the BarcodeSpider API), no multi-warehouse support, and no purchase order tracking. For those needs, look at Snipe-IT or Grocy. For home inventory, Homebox is the best option available.

Related

• Grocy vs Homebox: Home Inventory Compared
• Snipe-IT vs Homebox: Which Inventory Tool?
• Best Self-Hosted Home Inventory Tools
• Grocy: Self-Hosted Household Management
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy
• Authelia: Self-Hosted SSO
• Authentik: Self-Hosted Identity Provider