From 178c3205db4092a0801970c79e4521d0e9529687 Mon Sep 17 00:00:00 2001 From: mvbingham Date: Sun, 14 Dec 2025 21:09:17 -0500 Subject: [PATCH] updated README --- homebox/README.mc | 448 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 448 insertions(+) create mode 100644 homebox/README.mc diff --git a/homebox/README.mc b/homebox/README.mc new file mode 100644 index 0000000..a1f8de7 --- /dev/null +++ b/homebox/README.mc @@ -0,0 +1,448 @@ +
+ +# 📦 Homebox Inventory Management Service + +### Home inventory and organization system for tracking your belongings + +[![Homebox](https://img.shields.io/badge/Homebox-Latest-blue?logo=github)](https://github.com/hay-kot/homebox) +[![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker)](https://docs.docker.com/compose/) +[![License](https://img.shields.io/badge/License-AGPL--3.0-green)](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/) + +
+ +--- + +## 📋 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 + + + + + + +
+ +#### 👤 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: + +```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 + +
+Click to expand troubleshooting steps + +**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 +``` + +
+ +### 🔐 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 + +--- + +
+ +### 🌟 Happy Organizing! 🌟 + +**Made with ❤️ using Docker & Homebox** + +[⬆️ Back to Top](#-homebox-inventory-management-service) + +