docker-compose-files/homebox

📦 Homebox Inventory Management Service

Home inventory and organization system for tracking your belongings

GitHub • Documentation • Demo

---

📋 Overview

Homebox is a home inventory management system built for the Home User. It helps you track, organize, and manage your household items, receipts, warranties, and maintenance schedules all in one place.

✨ Key Features

• 📦 Asset Tracking - Track all your belongings with photos, receipts, and details
• 🏷️ Label & Location - Organize items by location, labels, and custom fields
• 📄 Document Storage - Attach receipts, manuals, and warranty information
• 📊 Reporting - Generate reports and export your inventory data
• 🔍 Quick Search - Find items quickly with powerful search functionality
• 📱 Responsive Design - Works seamlessly on desktop and mobile devices
• 🔐 Self-Hosted - Keep your data private and secure on your own server
• 👥 Multi-User - Share inventory with family members (optional)

---

🚀 Quick Start

Step 1️⃣: Create docker-compose.yml

touch docker-compose.yml

Step 2️⃣: Start Service

# homebox directory
docker-compose up -d

Step 3️⃣: Access Homebox

Open your browser to:

Item	Value
🌐 URL	http://localhost:3100 (or your configured port)
👤 First Time	Create your account on first visit

Step 4️⃣: Initial Setup

👤 Create Account Register your first user account

🏠 Set Up Locations Define rooms, storage areas, or locations

🏷️ Create Labels Add labels/tags for categorization

📦 Add Items Start adding your inventory items!

🔒 Security Note: After creating your account, consider disabling registration in .env

---

⚙️ Configuration

🔧 Environment Variables

Edit your .env file with the following settings:

# 🌐 Web Port
HOMEBOX_PORT=3100

# 📝 Logging Configuration
HBOX_LOG_LEVEL=info
HBOX_LOG_FORMAT=text

# 📤 Upload Settings (in MB)
HBOX_WEB_MAX_UPLOAD_SIZE=10

# 🔓 Registration Settings
HBOX_OPTIONS_ALLOW_REGISTRATION=true

Variable	Description	Default
HOMEBOX_PORT	Web interface port	3100
HBOX_LOG_LEVEL	Logging level (debug, info, warn, error)	info
HBOX_LOG_FORMAT	Log format (text, json)	text
HBOX_WEB_MAX_UPLOAD_SIZE	Max upload size in MB	10
HBOX_OPTIONS_ALLOW_REGISTRATION	Allow new user registrations	true

💾 Volume Mounts

Data persistence is handled through Docker named volumes:

Volume Name	Purpose	Contents
homebox_data	Application Data	SQLite database, uploaded files, attachments

📁 Data Structure

Inside the homebox_data volume:

/data/
├── homebox.db          # SQLite database
├── attachments/        # Uploaded files
└── photos/             # Item photos

---

🛠️ Management Commands

📋 View Logs

Monitor your service in real-time:

# View Homebox logs
docker-compose logs -f homebox

# View last 100 lines
docker-compose logs --tail=100 homebox

🔄 Restart Service

# Restart service
docker-compose restart homebox

🛑 Stop Service

# Stop service (keeps data)
docker-compose down

# Stop and remove volumes (⚠️ deletes all data!)
docker-compose down -v

💾 Backup Data

Complete Data Backup:

# Backup all data (database + attachments)
docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine tar czf /backup/homebox_backup_$(date +%Y%m%d).tar.gz /data

SQLite Database Only:

# Backup just the database
docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine cp /data/homebox.db /backup/homebox_$(date +%Y%m%d).db

📅 Best Practice: Schedule automated backups using cron or systemd timers

♻️ Restore Data

Complete Data Restore:

docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine tar xzf /backup/homebox_backup.tar.gz -C /

Database Only Restore:

# Stop service first
docker-compose down

# Restore database
docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine cp /backup/homebox.db /data/homebox.db

# Start service
docker-compose up -d

---

🏥 Health Checks

The service includes automated health monitoring:

Service	Health Check	Interval	Timeout
homebox	HTTP GET /api/v1/status	30s	10s

Check Service Status:

# View service health status
docker-compose ps

# Detailed health check information
docker inspect homebox | grep -A 10 Health

---

⬆️ Upgrading

🔼 Upgrade Homebox

# Pull latest image
docker-compose pull homebox

# Rebuild and restart
docker-compose up -d --build homebox

⚠️ Important: Always backup your data before upgrading!

Post-Upgrade Steps:

1. Check logs for any errors:

   docker-compose logs -f homebox
   

2. Verify the application is running:

   docker-compose ps
   

3. Test access at http://localhost:3100

---

🔧 Troubleshooting

❌ Service Won't Start

Click to expand troubleshooting steps

Step 1: Check logs

docker-compose logs homebox

Step 2: Verify port is not in use

# Linux/Mac
lsof -i :3100

# Windows
netstat -ano | findstr :3100

Step 3: Check disk space

df -h

Step 4: Verify volume permissions

docker-compose exec homebox ls -la /data

🔐 Cannot Login / Forgot Password

Currently, Homebox doesn't have a built-in password reset. Options:

1. Reset Database (⚠️ loses all data):

   docker-compose down
   docker volume rm homebox_data
   docker-compose up -d
   

2. Manual Database Edit (advanced users only)

📤 Upload Size Issues

If uploads are failing:

1. Increase HBOX_WEB_MAX_UPLOAD_SIZE in .env
2. Restart the service:

   docker-compose restart homebox
   

🐌 Performance Issues

For large inventories:

1. Regular Database Maintenance - SQLite can benefit from occasional vacuuming
2. Optimize Images - Compress large photos before uploading
3. Resource Allocation - Ensure Docker has adequate resources

---

🔒 Security Recommendations

Priority	Recommendation	Implementation
🔴 Critical	Disable registration	Set HBOX_OPTIONS_ALLOW_REGISTRATION=false after setup
🔴 Critical	Enable HTTPS	Configure reverse proxy (Nginx/Traefik) with SSL
🟡 Important	Regular backups	Schedule automated backups (daily/weekly)
🟡 Important	Keep updated	Regular Homebox updates
🟢 Recommended	Strong passwords	Use complex passwords for all accounts
🟢 Recommended	Network isolation	Use Docker networks for security

🛡️ Security Checklist

• Registration disabled after initial account creation
• SSL/TLS enabled via reverse proxy
• Automated backup system in place
• Regular update schedule established
• Strong passwords for all user accounts
• Firewall rules configured
• Access restricted to local network or VPN

---

💡 Usage Tips

📸 Taking Good Item Photos

• Use good lighting
• Include serial numbers or model information
• Take multiple angles for valuable items
• Keep photos under 5MB for faster loading

🏷️ Organization Best Practices

1. Locations - Create hierarchical locations (House → Living Room → TV Stand)
2. Labels - Use consistent labeling (Electronics, Appliances, Tools, etc.)
3. Custom Fields - Add fields relevant to you (Purchase Date, Warranty Expiration, etc.)
4. Attachments - Always attach receipts and manuals

📊 Maintenance Schedules

Use Homebox to track:

• HVAC filter changes
• Appliance maintenance
• Tool calibration
• Warranty expirations

---

🔗 Integration with Main Stack

To include Homebox in the main docker-infrastructure setup:

1. Reference from main docker-compose.yml:

   include:
     - services/homebox/docker-compose.yml
   

2. Or use service discovery with shared networks

See the main repository README for complete integration instructions.

---

📚 Resources

📖 Documentation

Resource	Link
📘 Official Docs	hay-kot.github.io/homebox
🐙 GitHub Repo	github.com/hay-kot/homebox
🎮 Live Demo	homebox.fly.dev

🆘 Support

Need help? Check these resources:

• 💬 GitHub Discussions: github.com/hay-kot/homebox/discussions
• 🐛 GitHub Issues: github.com/hay-kot/homebox/issues
• 📖 Documentation: hay-kot.github.io/homebox

---

🎯 Use Cases

🏠 Home Inventory

Track all household items for insurance purposes, moving, or organization

🔧 Tool Management

Keep track of tools, equipment, and their locations in workshop or garage

📚 Collection Management

Manage collections (books, games, movies, collectibles)

🏢 Small Business

Inventory for small businesses, offices, or rental properties

🎓 Educational

Lab equipment, classroom supplies, or library materials

---

🌟 Happy Organizing! 🌟

Made with ❤️ using Docker & Homebox

⬆️ Back to Top