mbtech/docker-compose-files

Fork 0

Files

mvbingham 48977a1871 Updated readme

2025-12-14 21:09:47 -05:00

10 KiB

Raw Permalink Blame History

📦 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

🏠 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:

Check logs for any errors:
```
docker-compose logs -f homebox
```
Verify the application is running:
```
docker-compose ps
```
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

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

Reset Database (⚠️ loses all data):

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

Manual Database Edit (advanced users only)

📤 Upload Size Issues

If uploads are failing:

Increase HBOX_WEB_MAX_UPLOAD_SIZE in .env
Restart the service:
```
docker-compose restart homebox
```

🐌 Performance Issues

For large inventories:

Regular Database Maintenance - SQLite can benefit from occasional vacuuming
Optimize Images - Compress large photos before uploading
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

Locations - Create hierarchical locations (House → Living Room → TV Stand)
Labels - Use consistent labeling (Electronics, Appliances, Tools, etc.)
Custom Fields - Add fields relevant to you (Purchase Date, Warranty Expiration, etc.)
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:

Reference from main docker-compose.yml:

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

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

10 KiB Raw Permalink Blame History Unescape Escape