Docker и Docker Compose: пошаговый мануал для новичков

-v /opt/mosquitto/config:/mosquitto/config — директория /opt/mosquitto/config на хосте доступна внутри контейнера как /mosquitto/config. Всё, что контейнер пишет в /mosquitto/config, на самом деле сохраняется на хосте. Удалили контейнер, создали заново — данные на месте.

Переменные окружения

Многие контейнеры настраиваются через переменные окружения:

bashКопироватьdocker run -d --name influxdb \
  -p 8086:8086 \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=admin \
  -e DOCKER_INFLUXDB_INIT_PASSWORD=supersecret \
  -e DOCKER_INFLUXDB_INIT_ORG=home \
  -e DOCKER_INFLUXDB_INIT_BUCKET=homeassistant \
  -v /opt/influxdb/data:/var/lib/influxdb2 \
  influxdb:2

-e задаёт переменную. Какие переменные поддерживает конкретный образ — описано в его документации на Docker Hub или GitHub.

Автозапуск контейнера

bashКопироватьdocker run -d --name mosquitto --restart unless-stopped eclipse-mosquitto:2

--restart unless-stopped — контейнер перезапускается автоматически при падении и при перезагрузке сервера. Не перезапускается, только если вы его остановили вручную командой docker stop.

Другие варианты: --restart always (перезапускать всегда), --restart on-failure (только при ошибке), --restart no (никогда).

Часть 3. Docker Compose

Запускать каждый контейнер отдельной командой docker run с десятком параметров — неудобно. Docker Compose позволяет описать все контейнеры в одном YAML-файле и управлять ими одной командой.

Создаём файл docker-compose.yml

Создайте директорию для проекта:

bashКопироватьmkdir -p /opt/smarthome
cd /opt/smarthome

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

bashКопироватьnano docker-compose.yml

Минимальный пример — Mosquitto:

yamlКопироватьservices:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

Сохраните (Ctrl+O, Enter, Ctrl+X в nano).

Запускаем

bashКопироватьdocker compose up -d

Docker Compose скачает образ, создаст контейнер с указанными параметрами и запустит его. Флаг -d — в фоне.

Основные команды Docker Compose

Все команды выполняются из директории, где лежит docker-compose.yml.

bashКопироватьdocker compose up -d          # запустить все сервисы
docker compose down            # остановить и удалить все контейнеры
docker compose stop            # остановить (без удаления)
docker compose start           # запустить остановленные
docker compose restart         # перезапустить все
docker compose restart mosquitto  # перезапустить один сервис
docker compose logs -f         # логи всех сервисов
docker compose logs -f mosquitto  # логи одного сервиса
docker compose ps              # статус контейнеров
docker compose pull            # скачать обновлённые образы

Обновление контейнеров

bashКопироватьdocker compose pull            # скачать новые версии образов
docker compose up -d           # пересоздать контейнеры из новых образов

Данные в примонтированных директориях сохраняются. Обновляется только сам контейнер (код приложения, библиотеки). Конфигурация и данные — на месте.

Для отката на предыдущую версию — укажите конкретный тег в docker-compose.yml:

yamlКопироватьimage: eclipse-mosquitto:2.0.18    # конкретная версия вместо "2" (последняя)

И выполните docker compose up -d.

Часть 4. Собираем инфраструктуру умного дома

Теперь — реальный пример. Файл docker-compose.yml, который поднимает базовую инфраструктуру: Mosquitto, Zigbee2MQTT и Home Assistant.

Подготовка директорий

bashКопироватьmkdir -p /opt/smarthome
cd /opt/smarthome

mkdir -p mosquitto/config mosquitto/data mosquitto/log
mkdir -p zigbee2mqtt/data
mkdir -p homeassistant/config

Конфигурация Mosquitto

Создайте файл конфигурации:

bashКопироватьnano mosquitto/config/mosquitto.conf

Содержимое:

Копироватьlistener 1883
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
allow_anonymous false
password_file /mosquitto/config/passwd

Сохраните. Теперь создайте файл паролей (пока пустой — заполним после первого запуска).

docker-compose.yml

yamlКопироватьservices:

  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./zigbee2mqtt/data:/app/data
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    depends_on:
      - mosquitto

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./homeassistant/config:/config
    privileged: true
    depends_on:
      - mosquitto

Разбор по строкам

mosquitto:

• image: eclipse-mosquitto:2 — образ Mosquitto, последняя версия ветки 2.x.
• ports: "1883:1883" — MQTT-порт доступен из локальной сети.
• volumes — конфигурация, данные и логи хранятся на хосте.

zigbee2mqtt:

• image: koenkk/zigbee2mqtt — образ Zigbee2MQTT (latest).
• ports: "8080:8080" — веб-интерфейс Zigbee2MQTT.
• devices: /dev/ttyUSB0:/dev/ttyUSB0 — проброс USB-координатора (Sonoff ZBDongle, SMLIGHT и т.д.) внутрь контейнера. Путь может отличаться — проверьте командой ls /dev/ttyUSB* или ls /dev/ttyACM*.
• depends_on: mosquitto — Zigbee2MQTT стартует после Mosquitto.

homeassistant:

• image: ghcr.io/home-assistant/home-assistant:stable — стабильная версия Home Assistant.
• network_mode: host — контейнер использует сеть хоста напрямую. Нужно для mDNS-обнаружения устройств. При host-режиме ports не указывают — все порты контейнера и так доступны на хосте. Home Assistant будет на порту 8123.
• privileged: true — расширенные права. Нужно для доступа к оборудованию (Bluetooth, USB). Для продвинутых пользователей — можно ограничить конкретными capabilities, но для начала privileged работает.
• depends_on: mosquitto — стартует после Mosquitto.

Запуск

bashКопироватьdocker compose up -d

Первый запуск — Docker скачает три образа (может занять несколько минут, зависит от скорости интернета). Затем создаст и запустит контейнеры.

Создание пользователя Mosquitto

После первого запуска Mosquitto создайте пользователя:

bashКопироватьdocker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd homeassistant

Введите пароль. Добавьте ещё пользователей (без флага -c, чтобы не перезаписать файл):

bashКопироватьdocker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd zigbee2mqtt

Перезапустите Mosquitto:

bashКопироватьdocker compose restart mosquitto

Проверка

• Home Assistant: http://IP-сервера:8123
• Zigbee2MQTT: http://IP-сервера:8080

Если всё открывается — поздравляю, базовая инфраструктура работает.

Часть 5. Добавляем сервисы

Инфраструктура растёт — добавляем сервисы в тот же docker-compose.yml.

Grafana + InfluxDB

Добавьте в раздел services::

yamlКопировать  influxdb:
    image: influxdb:2
    container_name: influxdb
    restart: unless-stopped
    ports:
      - "8086:8086"
    volumes:
      - ./influxdb/data:/var/lib/influxdb2
      - ./influxdb/config:/etc/influxdb2
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=changeme123
      - DOCKER_INFLUXDB_INIT_ORG=home
      - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant

  grafana:
    image: grafana/grafana
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./grafana/data:/var/lib/grafana
    depends_on:
      - influxdb

Создайте директории:

bashКопироватьmkdir -p influxdb/data influxdb/config grafana/data

Запустите:

bashКопироватьdocker compose up -d

Docker создаст только новые контейнеры — уже работающие не тронет.

• InfluxDB: http://IP-сервера:8086
• Grafana: http://IP-сервера:3000 (логин: admin, пароль: admin — поменяйте при первом входе)

AdGuard Home

yamlКопировать  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "3003:3000/tcp"
    volumes:
      - ./adguardhome/work:/opt/adguardhome/work
      - ./adguardhome/conf:/opt/adguardhome/conf

Порт 3003 на хосте (потому что 3000 уже занят Grafana) → порт 3000 внутри контейнера (веб-интерфейс AdGuard Home).

Nginx Proxy Manager

yamlКопировать  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "81:81"
    volumes:
      - ./npm/data:/data
      - ./npm/letsencrypt:/etc/letsencrypt

Веб-интерфейс: http://IP-сервера:81 (логин: admin@example.com, пароль: changeme — поменяйте сразу).

Portainer

yamlКопировать  portainer:
    image: portainer/portainer-ce
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9000:9000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./portainer/data:/data

/var/run/docker.sock — Docker-сокет, через который Portainer управляет контейнерами. Веб-интерфейс: http://IP-сервера:9000.

Часть 6. Повседневные операции

Посмотреть, что запущено

bashКопироватьdocker compose ps

Посмотреть, сколько ресурсов потребляет каждый контейнер

bashКопироватьdocker stats

Реалтайм-таблица с CPU, RAM, сетевым трафиком. Ctrl+C для выхода.

Зайти внутрь контейнера

Иногда нужно выполнить команду внутри контейнера — проверить файлы, запустить утилиту:

bashКопироватьdocker exec -it mosquitto sh

Вы окажетесь внутри контейнера, в его файловой системе. exit — выход обратно на хост.

Для контейнеров на базе Debian/Ubuntu — вместо sh используйте bash.

Узнать путь USB-устройства

Для Zigbee-координатора важно знать правильный путь:

bashКопироватьls -la /dev/ttyUSB*
ls -la /dev/ttyACM*

Если координатор — единственное USB-устройство, обычно это /dev/ttyUSB0 или /dev/ttyACM0.

Для стабильности рекомендуется использовать путь по ID:

bashКопироватьls -la /dev/serial/by-id/

Вывод будет вроде usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_xxxx-if00-port0. Используйте этот путь в docker-compose.yml:

yamlКопироватьdevices:
  - /dev/serial/by-id/usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_xxxx-if00-port0:/dev/ttyACM0

Так координатор будет найден даже если порядок USB-устройств изменится после перезагрузки.

Очистка неиспользуемых образов

Со временем на диске накапливаются старые версии образов:

bashКопироватьdocker image prune -a

Удалит все образы, которые не используются ни одним контейнером. Освобождает гигабайты.

bashКопироватьdocker system prune -a

Более агрессивная очистка: неиспользуемые образы, остановленные контейнеры, неиспользуемые сети и кэш сборки.

Часть 7. Резервное копирование

С Docker резервное копирование — это два элемента.

Что бэкапить

1. Файл docker-compose.yml — описание всей инфраструктуры.
2. Директории с данными — всё, что примонтировано через volumes.

В нашем примере — это вся директория /opt/smarthome:

Копировать/opt/smarthome/
├── docker-compose.yml
├── mosquitto/
│   ├── config/
│   ├── data/
│   └── log/
├── zigbee2mqtt/
│   └── data/
├── homeassistant/
│   └── config/
├── influxdb/
│   ├── data/
│   └── config/
├── grafana/
│   └── data/
└── ...

Простой бэкап

bashКопировать# Остановить контейнеры (для консистентности)
cd /opt/smarthome
docker compose stop

# Создать архив
tar czf /backup/smarthome-$(date +%Y%m%d).tar.gz /opt/smarthome/

# Запустить обратно
docker compose start

Для InfluxDB и других баз данных остановка перед бэкапом — рекомендуется, чтобы не получить повреждённую копию. Для файлов конфигурации (Home Assistant, Zigbee2MQTT, Mosquitto) — можно копировать на ходу, но остановка надёжнее.

Автоматизация через cron

bashКопироватьcrontab -e

Добавьте строку:

Копировать0 3 * * * cd /opt/smarthome && docker compose stop && tar czf /backup/smarthome-$(date +\%Y\%m\%d).tar.gz /opt/smarthome/ && docker compose start

Каждую ночь в 3:00 — остановка, бэкап, запуск. Контейнеры недоступны 1–5 минут.

Восстановление на новом сервере

1. Установите Docker (как в Части 1).
2. Распакуйте архив: tar xzf smarthome-20260305.tar.gz -C /
3. Перейдите в директорию: cd /opt/smarthome
4. Запустите: docker compose up -d

Всё. Весь умный дом восстановлен на новом сервере.

Часть 8. Частые ошибки и решения

«Permission denied» при обращении к Docker

КопироватьGot permission denied while trying to connect to the Docker daemon socket

Вы не добавили пользователя в группу docker. Выполните sudo usermod -aG docker $USER и перелогиньтесь.

Контейнер запускается и сразу останавливается

Смотрите логи:

bashКопироватьdocker compose logs имя-сервиса

Частые причины: неверная конфигурация, отсутствующий файл, занятый порт.

«Port is already in use»

КопироватьBind for 0.0.0.0:1883 failed: port is already allocated

Порт уже занят другим процессом или контейнером. Проверьте:

bashКопироватьsudo lsof -i :1883

Или смените порт хоста в docker-compose.yml: "1884:1883".

«Device not found» для USB-устройства

Координатор не найден по указанному пути. Проверьте ls /dev/serial/by-id/, убедитесь что устройство подключено, и обновите путь в docker-compose.yml.

Контейнер не видит другой контейнер по имени

Все контейнеры в одном docker-compose.yml автоматически в одной сети. Обращайтесь по имени сервиса (не container_name, а имени из YAML). Исключение: контейнер с network_mode: host (Home Assistant) — он в сети хоста и обращается к другим контейнерам через localhost:порт или IP-хоста:порт.

Данные пропали после пересоздания контейнера

Вы не примонтировали директорию. Всё, что не в volumes, живёт только внутри контейнера и исчезает при его удалении. Добавьте volumes для всех данных, которые должны сохраняться.

После обновления контейнер не стартует

Откатитесь на предыдущую версию. В docker-compose.yml укажите конкретный тег:

yamlКопироватьimage: koenkk/zigbee2mqtt:1.40.0    # вместо latest

И выполните docker compose up -d.

Часть 9. Полезные практики

Используйте конкретные теги вместо latest

yamlКопировать# Плохо — непредсказуемо
image: koenkk/zigbee2mqtt

# Хорошо — предсказуемо
image: koenkk/zigbee2mqtt:1.42.0

Тег latest (используется по умолчанию, когда тег не указан) означает «последняя версия». Сегодня это 1.42.0, завтра — 1.43.0 с возможными несовместимостями. Для стабильности указывайте конкретную версию. Обновляйтесь осознанно, проверив changelog.

Исключение: Home Assistant (:stable) и Mosquitto (:2) — здесь мажорные версии стабильны, и тег ветки безопасен.

Храните docker-compose.yml в Git

bashКопироватьcd /opt/smarthome
git init
git add docker-compose.yml
git commit -m "Initial setup"

Каждое изменение — коммит. История изменений, возможность отката, понимание, что и когда менялось. Не добавляйте в Git файлы с паролями и токенами — используйте .gitignore или переменные окружения через файл .env.

Файл .env для секретов

Создайте файл .env рядом с docker-compose.yml:

КопироватьMQTT_PASSWORD=supersecretpassword
INFLUXDB_PASSWORD=anothersecret

В docker-compose.yml:

yamlКопироватьenvironment:
  - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}

Docker Compose автоматически подставит значения из .env. Добавьте .env в .gitignore, чтобы секреты не попали в Git.

Один docker-compose.yml vs. несколько

Для домашнего сервера один файл — проще. Все сервисы в одной сети, одна команда для управления, один бэкап.

Если сервисов много (15+) и хочется группировать — можно разделить на несколько файлов в разных директориях. Но для начала — один файл на всё.

Что дальше

Docker установлен, базовая инфраструктура работает. Дальше — по потребностям:

• Frigate — добавьте в docker-compose.yml с пробросом GPU/Coral.
• Node-RED — визуальная автоматизация, если YAML не по душе.
• Uptime Kuma — мониторинг доступности сервисов.
• Watchtower / Diun — уведомления о доступных обновлениях.
• Nginx Proxy Manager — красивые адреса и HTTPS для всех сервисов.
• Резервное копирование — автоматизируйте через cron, Restic или Borg.

Каждый новый сервис — это ещё один блок в docker-compose.yml. Десять строк — и он работает. В этом сила Docker: вся инфраструктура умного дома описана в одном текстовом файле, который помещается на экран.

Статья подготовлена на основе официальной документации Docker и Docker Compose, а также практического опыта сообщества Home Assistant. Все команды проверены на Debian 12 и Ubuntu 24.04. Материал носит информационный характер и не является рекламой.

Блог о домашней инфраструктуре: умный дом, серверы, сети. Только реальный опыт и честные рекомендации.