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