Deploying HomeBox

Introduction

HomeBox is a simple yet powerful home inventory management application designed to help you organize, track, and manage your possessions. Whether you need to catalog items for insurance purposes, track where things are stored, or simply want to know what you own, HomeBox provides an intuitive interface for managing your home inventory.

Developed and maintained by SysAdminsMedia after the original project was archived, HomeBox continues to receive updates and improvements. The application features a clean, modern interface with support for locations, labels, custom fields, and QR code labels for physical organization.

Key highlights of HomeBox:

• Location Management: Organize items by rooms, shelves, or containers
• Label System: Categorize items with custom labels
• Custom Fields: Add any additional information you need
• QR Codes: Generate and print labels for physical items
• Asset Tracking: Track serial numbers, warranties, and purchase info
• Photo Attachments: Add images to your inventory items
• Import/Export: Bulk import from CSV and export your data
• Multi-User: Share access with family members

This guide walks through deploying HomeBox on Klutch.sh using Docker, setting up your inventory system, and organizing your possessions.

Prerequisites

Before deploying HomeBox on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your HomeBox configuration
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

homebox-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the SysAdminsMedia HomeBox image:

FROM ghcr.io/sysadminsmedia/homebox:latest

# Environment variables
ENV HBOX_LOG_LEVEL=info
ENV HBOX_LOG_FORMAT=text
ENV HBOX_WEB_MAX_UPLOAD_SIZE=10
ENV HBOX_OPTIONS_ALLOW_REGISTRATION=${HBOX_OPTIONS_ALLOW_REGISTRATION:-true}

# Expose the application port
EXPOSE 7745

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:7745/api/v1/status || exit 1

Advanced Dockerfile with All Options

FROM ghcr.io/sysadminsmedia/homebox:latest

# Logging configuration
ENV HBOX_LOG_LEVEL=${HBOX_LOG_LEVEL:-info}
ENV HBOX_LOG_FORMAT=${HBOX_LOG_FORMAT:-text}

# Upload limits
ENV HBOX_WEB_MAX_UPLOAD_SIZE=${HBOX_WEB_MAX_UPLOAD_SIZE:-10}

# Registration settings
ENV HBOX_OPTIONS_ALLOW_REGISTRATION=${HBOX_OPTIONS_ALLOW_REGISTRATION:-true}

# Disable analytics
ENV HBOX_OPTIONS_ALLOW_ANALYTICS=false

# Currency (for purchase tracking)
ENV HBOX_OPTIONS_CURRENCY=${HBOX_OPTIONS_CURRENCY:-USD}

EXPOSE 7745

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:7745/api/v1/status || exit 1

Rootless Deployment

For enhanced security, use the rootless image:

FROM ghcr.io/sysadminsmedia/homebox:latest-rootless

ENV HBOX_LOG_LEVEL=info
ENV HBOX_OPTIONS_ALLOW_REGISTRATION=true
ENV HBOX_OPTIONS_ALLOW_ANALYTICS=false

EXPOSE 7745

# Note: For rootless, data directory should be owned by user 65532

Environment Variables Reference

Variable	Required	Default	Description
HBOX_LOG_LEVEL	No	info	Logging level (debug, info, warn, error)
HBOX_LOG_FORMAT	No	text	Log format (text or json)
HBOX_WEB_MAX_UPLOAD_SIZE	No	10	Maximum upload size in MB
HBOX_OPTIONS_ALLOW_REGISTRATION	No	true	Allow new user registration
HBOX_OPTIONS_ALLOW_ANALYTICS	No	true	Send anonymous analytics
HBOX_OPTIONS_CURRENCY	No	USD	Default currency for prices

Deploying HomeBox on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial HomeBox deployment configuration"
git remote add origin https://github.com/yourusername/homebox-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “homebox” or “inventory”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your HomeBox repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 7745

Set Environment Variables

Configure the following environment variables:

Variable	Value
HBOX_LOG_LEVEL	info
HBOX_OPTIONS_ALLOW_REGISTRATION	true (change to false after setup)
HBOX_OPTIONS_ALLOW_ANALYTICS	false
HBOX_OPTIONS_CURRENCY	Your currency (e.g., USD, EUR, GBP)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/data	10 GB	Database and uploaded files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start HomeBox with HTTPS enabled.

Access HomeBox

Once deployment completes, access your HomeBox instance at https://your-app-name.klutch.sh. Create your first account to get started.

Secure Your Instance

After creating your account, set HBOX_OPTIONS_ALLOW_REGISTRATION=false to prevent unauthorized signups.

Using HomeBox

Creating Your First Location

1. Log in to HomeBox
2. Navigate to Locations
3. Click Create Location
4. Enter details:
   • Name (e.g., “Living Room”, “Garage”)
   • Description
   • Parent location (for nested organization)
5. Save the location

Adding Items

1. Navigate to Items
2. Click Create Item
3. Fill in details:
   • Name
   • Description
   • Location
   • Labels (categories)
   • Quantity
4. Add optional fields:
   • Purchase price and date
   • Serial number
   • Warranty information
   • Custom fields
5. Upload photos
6. Save the item

Using Labels

Labels help categorize items across locations:

1. Navigate to Labels
2. Create labels like:
   • Electronics
   • Kitchen
   • Tools
   • Valuables
3. Apply labels when creating items
4. Filter inventory by labels

QR Code Labels

Generate printable labels:

1. Select an item
2. Click Print Label
3. QR code links to item details
4. Attach label to physical item
5. Scan with phone to view details

Custom Fields

Add any information you need:

1. Navigate to Settings > Custom Fields
2. Create fields like:
   • Color
   • Size
   • Condition
   • Insurance policy number
3. Fields appear on item forms

Bulk Import

Import existing inventory:

1. Prepare CSV file with columns:
   • name
   • description
   • location
   • labels
   • quantity
   • purchase_price
2. Navigate to Import
3. Upload your CSV
4. Map columns to fields
5. Import items

Organization Tips

Location Hierarchy

Create nested locations:

Home
├── Living Room
│   ├── TV Stand
│   └── Bookshelf
├── Kitchen
│   ├── Pantry
│   └── Cabinets
└── Garage
    ├── Tool Wall
    └── Storage Shelves

Labeling Strategy

Combine labels for flexible filtering:

• Type: Electronics, Furniture, Books
• Status: In Use, Stored, Lent Out
• Priority: Essential, Valuable, Replaceable

Insurance Documentation

For valuable items:

1. Add purchase receipts as attachments
2. Include serial numbers
3. Note warranty expiration
4. Document condition with photos

Troubleshooting

Cannot Log In

• Verify account was created successfully
• Check if registration is still enabled
• Review application logs

Upload Fails

• Check file size limits
• Verify storage space available
• Ensure file type is supported

Data Not Saving

• Verify persistent volume is mounted
• Check database permissions
• Review error logs

Additional Resources

• HomeBox GitHub Repository
• HomeBox Website
• HomeBox Quick Start Guide
• HomeBox Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying HomeBox on Klutch.sh provides a comprehensive home inventory management solution with location tracking, labeling, and asset documentation. Whether you’re cataloging items for insurance, organizing storage, or simply wanting to know where things are, HomeBox’s intuitive interface makes inventory management straightforward. With persistent storage for your data and photos, your inventory remains safe and accessible across deployments.