<div align="center"> # 📦 Homebox Inventory Management Service ### Home inventory and organization system for tracking your belongings [](https://github.com/hay-kot/homebox) [](https://docs.docker.com/compose/) [](https://github.com/hay-kot/homebox/blob/main/LICENSE) [GitHub](https://github.com/hay-kot/homebox) • [Documentation](https://hay-kot.github.io/homebox/) • [Demo](https://homebox.fly.dev/) </div> --- ## 📋 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️⃣: Configure Environment ```bash cd services/homebox cp .env.example .env # Edit .env with your settings ``` > 💡 **Tip**: You can disable registration after creating your account by setting `HBOX_OPTIONS_ALLOW_REGISTRATION=false` ### Step 2️⃣: Start Service ```bash # From services/homebox directory docker-compose up -d # Or from repository root docker-compose -f services/homebox/docker-compose.yml 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 <table> <tr><td> #### 👤 Create Account Register your first user account </td></tr> <tr><td> #### 🏠 Set Up Locations Define rooms, storage areas, or locations </td></tr> <tr><td> #### 🏷️ Create Labels Add labels/tags for categorization </td></tr> <tr><td> #### 📦 Add Items Start adding your inventory items! </td></tr> </table> > 🔒 **Security Note**: After creating your account, consider disabling registration in `.env` --- ## ⚙️ Configuration ### 🔧 Environment Variables Edit your `.env` file with the following settings: ```bash # 🌐 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: ```bash # View Homebox logs docker-compose logs -f homebox # View last 100 lines docker-compose logs --tail=100 homebox ``` ### 🔄 Restart Service ```bash # Restart service docker-compose restart homebox ``` ### 🛑 Stop Service ```bash # Stop service (keeps data) docker-compose down # Stop and remove volumes (⚠️ deletes all data!) docker-compose down -v ``` ### 💾 Backup Data **Complete Data Backup:** ```bash # 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:** ```bash # 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:** ```bash docker run --rm -v homebox_data:/data -v $(pwd):/backup alpine tar xzf /backup/homebox_backup.tar.gz -C / ``` **Database Only Restore:** ```bash # 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:** ```bash # View service health status docker-compose ps # Detailed health check information docker inspect homebox | grep -A 10 Health ``` --- ## ⬆️ Upgrading ### 🔼 Upgrade Homebox ```bash # 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: ```bash docker-compose logs -f homebox ``` 2. Verify the application is running: ```bash docker-compose ps ``` 3. Test access at http://localhost:3100 --- ## 🔧 Troubleshooting ### ❌ Service Won't Start <details> <summary><b>Click to expand troubleshooting steps</b></summary> **Step 1: Check logs** ```bash docker-compose logs homebox ``` **Step 2: Verify port is not in use** ```bash # Linux/Mac lsof -i :3100 # Windows netstat -ano | findstr :3100 ``` **Step 3: Check disk space** ```bash df -h ``` **Step 4: Verify volume permissions** ```bash docker-compose exec homebox ls -la /data ``` </details> ### 🔐 Cannot Login / Forgot Password Currently, Homebox doesn't have a built-in password reset. Options: 1. **Reset Database** (⚠️ loses all data): ```bash 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: ```bash 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`: ```yaml include: - services/homebox/docker-compose.yml ``` 2. Or use service discovery with shared networks See the [main repository README](../../README.md) for complete integration instructions. --- ## 📚 Resources ### 📖 Documentation | Resource | Link | |----------|------| | 📘 Official Docs | [hay-kot.github.io/homebox](https://hay-kot.github.io/homebox/) | | 🐙 GitHub Repo | [github.com/hay-kot/homebox](https://github.com/hay-kot/homebox) | | 🎮 Live Demo | [homebox.fly.dev](https://homebox.fly.dev/) | ### 🆘 Support Need help? Check these resources: - 💬 **GitHub Discussions**: [github.com/hay-kot/homebox/discussions](https://github.com/hay-kot/homebox/discussions) - 🐛 **GitHub Issues**: [github.com/hay-kot/homebox/issues](https://github.com/hay-kot/homebox/issues) - 📖 **Documentation**: [hay-kot.github.io/homebox](https://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 --- <div align="center"> ### 🌟 Happy Organizing! 🌟 **Made with ❤️ using Docker & Homebox** [⬆️ Back to Top](#-homebox-inventory-management-service) </div>