docker-compose-files/homebox/README.md

<div align="center">

# 📦 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/)

</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>