Compare commits
2 Commits
4600c75067
...
48977a1871
| Author | SHA1 | Date | |
|---|---|---|---|
|
48977a1871 | ||
|
|
178c3205db |
440
homebox/README.md
Normal file
440
homebox/README.md
Normal file
@@ -0,0 +1,440 @@
|
||||
<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️⃣: Create docker-compose.yml
|
||||
|
||||
```bash
|
||||
touch docker-compose.yml
|
||||
```
|
||||
### Step 2️⃣: Start Service
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
<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>
|
||||
Reference in New Issue
Block a user