HomeBox на Ubuntu 24.04: пошаговая установка

MAATRIX

Через полгода после переезда или ремонта половина техники и вещей теряется в памяти: где та коробка с кабелями, сколько стоил проектор и кончилась ли на него гарантия. Excel-таблица для этого работает плохо — не открыть с телефона в магазине, не привязать фото и чек, не найти вещь по QR-коду на коробке. HomeBox — open-source приложение именно под эту задачу: инвентаризация домашнего имущества с локациями, категориями, вложениями и историей. Ниже — как поставить его на VPS с Ubuntu 24.04.

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

HomeBox — self-hosted веб-приложение для учёта личного имущества. Разработчик описывает его как "inventory and organization system built for the ~things~ home", и по факту это то, чем часто пытаются заменить блокнот или таблицу: у каждой вещи есть карточка с фото, стоимостью, датой покупки, гарантией, местом хранения и произвольными полями.

Из практичного:

• Локации — иерархия вида "Дом → Гараж → Стеллаж → Полка 3", вещь привязывается к конкретному месту.
• Категории и лейблы — можно завести "Электроника", "Инструменты", "Документы" и фильтровать по ним.
• QR-коды — на каждую вещь и локацию генерируется QR, который можно распечатать и наклеить на коробку.
• Учёт стоимости — цена покупки, текущая оценочная стоимость, гарантия — удобно для страховки или при переезде.
• Вложения — чеки, фото, инструкции по эксплуатации хранятся прямо в карточке.
• Импорт/экспорт CSV — можно быстро занести список вещей из таблицы, если она уже была.

Важная оговорка: HomeBox — живой проект с активной разработкой, интерфейс и API между релизами иногда меняются заметнее, чем у зрелых продуктов. Это не повод отказываться, но бэкапы делать обязательно (об этом ниже), а обновления ставить не вслепую.

Почему не держать это на домашнем NAS или ноутбуке: доступ нужен из любой точки — стоя в магазине хозтоваров с вопросом "а у меня уже есть такая отвёртка?" телефон должен открыть страницу за секунду, а не через VPN до квартиры, который иногда не поднимается. VPS с постоянным IP и сертификатом снимает это неудобство.

Требования к серверу и подготовка

HomeBox лёгкий: база данных по умолчанию SQLite, память под сам сервис редко превышает 100-150 МБ, диск съедают в основном фотографии и вложения. Для домашнего использования достаточно:

Если сервер нужен только под HomeBox, хватит младшего тарифа VPS. Если планируете держать на нём же ещё пару self-hosted сервисов (например, Nextcloud для файлов) — берите тариф с запасом по RAM.

Перед установкой сервер должен быть подготовлен: обновлена система, настроен пользователь без root, включён файрвол. Если этот шаг ещё не сделан — разберите его отдельно в статье про первичную настройку и безопасность Ubuntu 24.04, а после — про настройку файрвола с нуля. Дальше в этой статье предполагается, что базовая защита уже включена и открыты порты 22, 80, 443.

Установка Docker и подготовка каталогов

HomeBox официально распространяется как Docker-образ, и это самый простой способ его поставить и обновлять. Если Docker ещё не стоит на сервере, поставьте его по инструкции Ubuntu 24.04: установка Docker с нуля, либо коротко:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER

После usermod перелогиньтесь (или выполните newgrp docker), чтобы работать с Docker без sudo.

Создайте каталог под проект и данные:

mkdir -p ~/homebox/data
cd ~/homebox

Каталог data — это то место, где HomeBox хранит SQLite-базу и все загруженные файлы (фото, чеки, документы). Именно его нужно будет бэкапить.

Docker Compose файл HomeBox

Создайте docker-compose.yml:

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    environment:
      - HBOX_LOG_LEVEL=info
      - HBOX_WEB_MAX_UPLOAD_SIZE=50
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:7745:7745"

Пояснения по образу и переменным:

• Официальный образ опубликован в GitHub Container Registry под ghcr.io/sysadminsmedia/homebox — это активно поддерживаемый форк исходного проекта, привязывайтесь именно к нему.
• HBOX_WEB_MAX_UPLOAD_SIZE — лимит загружаемого файла в мегабайтах; 50 МБ обычно достаточно для фото с телефона.
• Порт 7745 опубликован только на 127.0.0.1 — наружу отдаёт обратный прокси с SSL (раздел ниже), напрямую в интернет контейнер не смотрит.
• Вместо latest для продакшена лучше зафиксировать конкретный тег версии из релизов — так апдейт станет осознанным действием, а не сюрпризом при рестарте.

Запуск:

docker compose up -d
docker compose logs -f homebox

В логах должно появиться сообщение о старте сервера на порту 7745. Проверьте локально:

curl -I http://127.0.0.1:7745

Ответ 200 OK или 301 означает, что сервис поднялся и слушает порт.

Обратный прокси и SSL-сертификат

Отдавать HomeBox напрямую по IP:порту неудобно и небезопасно — нужен домен и HTTPS. Проще всего поставить Nginx как обратный прокси и получить сертификат Let's Encrypt.

Если у вас уже есть привязанный к серверу домен (или поддомен вроде home.example.com), настройте Nginx:

sudo apt install -y nginx
sudo nano /etc/nginx/sites-available/homebox

Конфиг:

server {
    listen 80;
    server_name home.example.com;

    client_max_body_size 60M;

    location / {
        proxy_pass http://127.0.0.1:7745;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

client_max_body_size должен быть не меньше значения HBOX_WEB_MAX_UPLOAD_SIZE из docker-compose, иначе Nginx будет обрезать загрузку фото раньше, чем это сделает само приложение.

Активируйте конфиг и получите сертификат:

sudo ln -s /etc/nginx/sites-available/homebox /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d home.example.com

Certbot сам допишет блок listen 443 ssl и настроит редирект с 80 на 443. Про выбор между certbot и альтернативами есть отдельный разбор — certbot или acme.sh: что выбрать для сервера, если хочется автоматизировать обновление сертификатов иначе.

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

Первая настройка: регистрация и локации

Откройте https://home.example.com в браузере. HomeBox при первом запуске просит создать первого пользователя — email и пароль. Это локальная регистрация внутри вашего инстанса, никаких внешних сервисов не задействовано.

После входа стоит сразу настроить структуру, прежде чем заносить вещи:

1. Создайте локации — раздел Locations. Логично повторить реальную структуру жилья: Квартира → Комнаты → Шкафы/полки. Локации можно вкладывать друг в друга произвольно глубоко.
2. Заведите лейблы — раздел Labels. Это плоские теги поверх категорий: "Гарантия до 2027", "Для продажи", "Хрупкое" — что угодно, что удобно фильтровать.
3. Проверьте категории — раздел Categories. По умолчанию их немного, можно дополнить под свои нужды (Электроника, Мебель, Инструменты, Одежда).
4. Настройте валюту в профиле пользователя (Settings → Profile), если рубль или доллар важны для отображения стоимости вещей — по умолчанию может стоять USD.

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

Для разового переноса большого списка вещей (например, если раньше велась таблица в Excel) в разделе Import можно загрузить CSV с колонками название/локация/цена и так далее — формат описан прямо на странице импорта в интерфейсе.

Бэкапы и обновление

HomeBox по умолчанию хранит всё в SQLite-файле и локальной папке с вложениями — оба лежат в каталоге ~/homebox/data, который был примонтирован в контейнер. Это удобно: бэкап — это просто копия каталога.

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

#!/bin/bash
BACKUP_DIR=/home/$USER/backups/homebox
DATE=$(date +%Y-%m-%d)
mkdir -p "$BACKUP_DIR"

docker compose -f /home/$USER/homebox/docker-compose.yml stop homebox
tar -czf "$BACKUP_DIR/homebox-$DATE.tar.gz" -C /home/$USER/homebox data
docker compose -f /home/$USER/homebox/docker-compose.yml start homebox

find "$BACKUP_DIR" -name "homebox-*.tar.gz" -mtime +30 -delete

Остановка контейнера на секунды перед архивацией — подстраховка от повреждения SQLite-файла при копировании "на лету"; для домашнего инвентаря такая пауза ночью незаметна. Сохраните скрипт как ~/backup-homebox.sh, сделайте исполняемым (chmod +x) и добавьте в cron:

crontab -e

0 3 * * * /home/YOUR_USER/backup-homebox.sh >> /home/YOUR_USER/backup-homebox.log 2>&1

Готовые архивы стоит время от времени копировать за пределы сервера — на локальный диск или в облачное хранилище, иначе бэкап на том же диске не спасёт при отказе самого сервера. Общие принципы автоматизации бэкапов баз данных разобраны в статье резервное копирование БД: автоматизация — подход с SQLite проще, чем с PostgreSQL/MySQL, но идея та же.

Обновление версии — замена тега образа в docker-compose.yml и пересоздание контейнера:

docker compose pull
docker compose up -d

Перед обновлением на новую мажорную версию стоит свериться с changelog проекта на GitHub — иногда меняется формат данных, и рекомендуется сначала сделать свежий бэкап (см. выше), а уже потом обновляться.

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