HomeBox в Docker Compose: готовый файл

MAATRIX

Когда в третий раз не можете вспомнить, куда положили гарантийный чек на телевизор или в какой коробке лежит запасной блок питания для NAS, самое время завести нормальную инвентаризацию. Google Таблицы для этого не подходят — нет фото, нет истории цены, нет привязки к местоположению. HomeBox — open-source приложение именно под эту задачу: лёгкое, быстрое, с QR-этикетками и понятным деревом «дом → комната → место → вещь». Ниже — рабочий docker-compose.yml, который можно поднять на любом VPS за десять минут.

Что такое HomeBox и кому он нужен

HomeBox —self-hosted инвентарный менеджер на Go (бэкенд) и Vue (фронтенд), упакованный в один контейнер. Разработчик прямо называет его «Home inventory for the geek in us all» — то есть это не корпоративная система учёта, а инструмент для дома: техника, инструменты, документы, коллекции, склад в гараже.

Типичные сценарии использования:

• Учёт техники и гарантий — модель, серийный номер, дата покупки, чек, срок гарантии с автоматическим напоминанием об истечении.
• Инвентаризация для страховки — если случится пожар или залив, у вас будет список вещей с фото и стоимостью для страховой компании.
• Организация склада/гаража — иерархия локаций (дом → этаж → комната → шкаф → полка) и быстрый поиск «где лежит».
• QR-этикетки — печатаете стикер, клеите на коробку, сканируете телефоном — сразу видите содержимое.
• Учёт коллекций — книги, инструменты, комплектующие для хобби.

Важное отличие от похожих проектов вроде Snipe-IT: Snipe-IT заточен под учёт IT-активов в компании (назначение сотрудникам, чек-ин/чек-аут), а HomeBox — под личное и семейное использование, без лишней сложности ролей и workflow.

Готовый docker-compose.yml

Официальный образ публикуется в GitHub Container Registry. Минимальная и при этом production-пригодная конфигурация:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    environment:
      - HBOX_LOG_LEVEL=info
      - HBOX_WEB_MAX_UPLOAD_SIZE=25
      - TZ=Europe/Moscow
    ports:
      - "3100:7745"
    volumes:
      - homebox_data:/data/

volumes:
  homebox_data:

Пояснения по переменным:

• HBOX_WEB_MAX_UPLOAD_SIZE — максимальный размер загружаемого файла (фото, вложения) в мегабайтах. По умолчанию 10 МБ, для нормальных фото с телефона лучше поднять до 25-50.
• TZ — часовой пояс, влияет на даты покупки, напоминания о гарантии и таймстампы в логах.
• Порт 7745 — внутренний порт приложения, наружу пробрасываем на любой свободный (в примере 3100).

Создайте директорию проекта, файл docker-compose.yml и поднимите:

mkdir -p ~/homebox && cd ~/homebox
nano docker-compose.yml   # вставить конфиг выше
docker compose up -d

Проверьте, что контейнер стартовал:

docker compose ps
docker compose logs -f homebox

Открывайте http://IP-сервера:3100 — увидите экран регистрации первого администратора. Аккаунт создаётся локально, без внешних сервисов авторизации.

Где хранятся данные и как их бэкапить

Все данные HomeBox — SQLite-база и загруженные файлы (фото, вложения) — лежат в одном каталоге /data внутри контейнера, который в конфиге выше смонтирован как именованный volume homebox_data. Это удобно тем, что бэкап сводится к копированию одной директории, без отдельной СУБД и её дампов.

Найти физический путь volume на диске:

docker volume inspect homebox_data | grep Mountpoint

Обычно это что-то вроде /var/lib/docker/volumes/homebox_homebox_data/_data.

Простой скрипт для ежедневного бэкапа в архив:

#!/bin/bash
# /root/scripts/homebox-backup.sh
DATE=$(date +%Y-%m-%d)
BACKUP_DIR=/backup/homebox
SRC=/var/lib/docker/volumes/homebox_homebox_data/_data

mkdir -p "$BACKUP_DIR"
docker compose -f /root/homebox/docker-compose.yml stop homebox
tar czf "$BACKUP_DIR/homebox-$DATE.tar.gz" -C "$SRC" .
docker compose -f /root/homebox/docker-compose.yml start homebox

# храним последние 14 архивов
find "$BACKUP_DIR" -name "homebox-*.tar.gz" -mtime +14 -delete

Остановка контейнера на секунду-две во время бэкапа — не проблема для домашнего использования и гарантирует консистентность SQLite-файла (без неё можно словить редкую, но неприятную блокировку базы на середине копирования).

Добавьте в cron:

chmod +x /root/scripts/homebox-backup.sh
crontab -e
# 0 4 * * * /root/scripts/homebox-backup.sh

Если сервер арендован, а не стоит дома, разумно ещё синхронизировать архивы на внешнее хранилище (rclone на S3-совместимый бакет или на локальный NAS) — так вы не теряете инвентаризацию при аварии диска на VPS. Об общих подходах к бэкапам томов Docker есть отдельный разбор: бэкап Docker volume на сервере — частые ошибки и решения.

HTTPS и доступ извне через Traefik

Открывать инвентарь по голому HTTP в интернет не стоит — там фотографии вашего имущества и потенциально серийники дорогой техники. Если у вас уже есть Traefik как reverse proxy для других сервисов, достаточно добавить лейблы:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    environment:
      - HBOX_LOG_LEVEL=info
      - HBOX_WEB_MAX_UPLOAD_SIZE=25
      - TZ=Europe/Moscow
    volumes:
      - homebox_data:/data/
    networks:
      - traefik-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homebox.rule=Host(`inventory.example.com`)"
      - "traefik.http.routers.homebox.entrypoints=websecure"
      - "traefik.http.routers.homebox.tls.certresolver=letsencrypt"
      - "traefik.http.services.homebox.loadbalancer.server.port=7745"

networks:
  traefik-net:
    external: true

volumes:
  homebox_data:

Замените inventory.example.com на свой домен (или поддомен), заранее направленный A-записью на IP сервера. Если Traefik ещё не настроен — есть пошаговый разбор: Traefik как reverse proxy для Docker и сравнение с альтернативой в статье Traefik или Nginx Proxy Manager — что выбрать для сервера.

Если поднимать Traefik ради одного HomeBox избыточно, а сервис нужен только вам и семье, проще не выставлять порт наружу вовсе и подключаться через Tailscale или WireGuard — тогда сертификат не нужен, а доступ есть только с доверенных устройств. Сравнение подходов — в статье Tailscale или ZeroTier для домашней сети.

Структура: локации, вещи, метки

HomeBox строится на трёх сущностях, и от того, как вы их спроектируете в первый час использования, зависит, будет ли системой пользоваться вся семья через полгода.

Locations (локации) — иерархическое дерево физических мест. Разумная глубина — 3-4 уровня: Квартира → Комната → Шкаф/Стеллаж → Полка. Не стоит уходить глубже — поиск начинает раздражать.

Items (вещи) — карточка предмета с полями: название, описание, серийный номер, модель, производитель, дата покупки, цена, продавец, гарантия (срок в месяцах, дата истечения считается автоматически), фото, вложения (PDF чека, инструкция), кастомные поля.

Labels (метки) — плоский тег-подобный слой поверх локаций, не привязанный к иерархии. Полезен для сквозной категоризации: «Электроника», «Требует ремонта», «Взято в долг», «Продать». Один предмет может иметь несколько меток одновременно, в отличие от локации, которая всегда одна.

Практический совет по вводу данных: не пытайтесь занести весь дом за один вечер. Начните с категории, где боль ощутимее всего (обычно это либо электроника с гарантиями, либо гараж/кладовка с инструментами), заведите 15-20 карточек, привыкните к интерфейсу — и дальше добавляйте по мере разбора остальных помещений.

QR-этикетки и мобильный доступ

Одна из сильных сторон HomeBox — генерация QR-кодов прямо из карточки локации или предмета. Печатаете на обычном принтере (или на термопринтере для наклеек типа Brother QL/Niimbot), клеите на коробку — и дальше сканирование телефоном сразу открывает содержимое в браузере, без установки приложения.

Пример рабочего процесса для гаража:

1. Создаёте локацию «Гараж → Стеллаж 2 → Ящик 3».
2. Заносите содержимое ящика как отдельные Items или одной карточкой «Разное — крепёж».
3. Печатаете QR-этикетку локации, клеите на ящик.
4. Через полгода, ища конкретный болт, сканируете этикетку вместо того чтобы перебирать пять ящиков вручную.

Отдельного мобильного приложения у HomeBox на данный момент нет — интерфейс адаптивный и нормально работает в браузере телефона, а PWA-режим (добавление на главный экран) даёт что-то близкое к нативному приложению без установки из магазина.

Обновление и миграция версий

HomeBox активно развивается, и с релиза на релиз меняются как фичи, так и (изредка) схема базы. Правило безопасного обновления:

cd ~/homebox
# сначала бэкап (см. раздел выше)
/root/scripts/homebox-backup.sh

docker compose pull
docker compose up -d
docker compose logs -f homebox

Если хотите зафиксировать версию вместо latest — что разумно для продакшен-инстанса, чтобы обновление не прилетело неожиданно вместе с docker compose pull для другого сервиса в том же compose-стеке — смотрите тег конкретного релиза в GitHub Container Registry проекта и подставляйте вместо latest, например ghcr.io/sysadminsmedia/homebox:v0.16.2 (номер версии уточняйте на странице релизов на момент установки — заранее не гарантируем).

Перед крупным мажорным обновлением (смена первой цифры версии) стоит поднять staging-копию на том же сервере с отдельным портом и volume, накатить на неё копию бэкапа и проверить, что интерфейс и данные выглядят нормально — только потом обновлять боевой инстанс.

Частые вопросы