Установка Open WebUI через Docker Compose

Когда сервис запускают одной длинной командой docker run, параметры портов, томов и переменных окружения не собраны в отдельном файле проекта. Через месяц или при следующем обновлении приходится вспоминать, с какими флагами создавался контейнер и где лежат его настройки. Docker Compose решает эту задачу иначе: мы один раз записываем параметры в файл compose.yaml, выносим секретный ключ в отдельный файл окружения и дальше управляем проектом короткими предсказуемыми командами.

Этот урок рассчитан на чистую установку Open WebUI. Это альтернативный способ развёртывания, а не обязательный второй шаг после урока с docker run (сравнение подходов мы разбирали в материале о выборе способа установки). Если вы уже развернули Open WebUI другим способом и внутри есть нужные чаты, учётные записи или привязанный к ним секретный ключ, не создавайте поверх старых данных новый проект с новым ключом. Перенос существующей установки требует отдельного сценария, а здесь мы разберём запуск с нуля.

Дальше мы пройдём один и тот же запуск на трёх системах. В Windows контейнером управляет Docker Desktop, а команды выполняются в Ubuntu через WSL2. На Mac команды вводятся в Терминале macOS и обращаются к Docker Desktop. В Linux мы продолжаем маршрут с Docker Engine в Ubuntu 24.04. Конфигурация приложения одинакова; сначала выберем нужный терминал и проверим доступ к движку Docker.

Выберем свою среду

Если Docker ещё не подготовлен, начнём с урока для вашей системы. Остальные ветки можно пропустить.

Команды для файлов и папок ниже подходят для Bash в Ubuntu и стандартной оболочки Zsh в macOS. В Windows их вводим именно в Ubuntu WSL2. PowerShell и командная строка Windows используют другой синтаксис.

В Linux сохраним выбранный способ доступа к Docker. Если в подготовительном уроке вы проверяли движок через sudo docker, здесь тоже добавляем sudo перед каждой командой, начинающейся с docker. Например, docker compose up -d становится sudo docker compose up -d. Это относится и к проверке конфигурации, журналам и остановке проекта. Команды mkdir, cd и генерацию файла ключа выполняем от обычного пользователя. Если доступ без sudo уже настроен и проверен, команды можно вводить без изменений.

В этом уроке Docker и браузер находятся на одном компьютере. Для подключения к удалённому серверу адрес 127.0.0.1 в браузере не подойдёт: способ доступа к серверу разбирается отдельно.

Подготовим Docker и папку проекта

Проверим, что выбранный терминал видит движок Docker, плагин Compose и OpenSSL для генерации ключа. В Windows и macOS Docker Desktop должен быть запущен. В Ubuntu Linux работает системная служба Docker Engine. Устанавливать второй движок внутри Ubuntu WSL2 или на Mac поверх Docker Desktop не нужно.

Проверим версии и текущее подключение Docker:

docker version
docker compose version
docker context ls
openssl version

В выводе docker version ожидаем блоки Client и Server без ошибки соединения. Блок Server подтверждает, что клиент связался с движком. Остальные команды покажут версию Compose, доступные контексты и версию OpenSSL. В Linux при работе через sudo проверяем первые три команды с этим префиксом; OpenSSL проверяем без него.

В списке docker context ls звёздочкой отмечено выбранное подключение. Оно должно вести к локальному движку, который мы подготовили для своей ОС: Docker Desktop в Windows/macOS или Docker Engine в Ubuntu Linux. Если выбран удалённый Docker или другой движок, сначала вернёмся к подготовительному уроку. Иначе контейнер и том могут создаться не на том компьютере, в браузере которого вы собираетесь открыть интерфейс.

Если OpenSSL не найден, вернёмся к разделу его подготовки в уроке своей ОС. Команды установки пакетов Ubuntu не подходят для Терминала macOS.

Теперь проверим, нет ли в системе контейнеров или томов от предыдущих попыток установки Open WebUI. Это важная мера предосторожности: Docker Compose при запуске переиспользует существующий том с подходящим именем, и если сгенерировать новый секретный ключ поверх старой базы данных, доступ к зашифрованным настройкам и сессиям может нарушиться.

Проверим список контейнеров и томов с фильтром по строке open-webui:

docker ps -a --filter name=open-webui
docker volume ls --filter name=open-webui

Обратите внимание, что фильтр --filter name=open-webui ищет совпадение по подстроке, поэтому смотрите на точные значения в колонках NAMES и VOLUME NAME. Для чистой установки список контейнеров должен быть пустым, а среди томов не должно быть ни open-webui (такой том обычно остаётся после запуска через docker run), ни open-webui_open-webui (так называется том нашего проекта в Docker Compose). Если в выводе нашёлся старый контейнер или любой из этих двух томов, остановитесь на этом шаге. Удалять старые тома наугад здесь не нужно: сначала решите, нужны ли вам прежние данные, чтобы не потерять рабочую базу и не перезаписать ключ.

Когда убедились, что прежней установки нет, создадим отдельную папку ~/projects/open-webui. Знак ~ обозначает домашний каталог текущего пользователя. В Ubuntu и WSL2 путь обычно начинается с /home/, а на Mac с /Users/. В Windows оставим проект внутри файловой системы Ubuntu, а не на диске /mnt/c.

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

mkdir -p ~/projects
mkdir ~/projects/open-webui && cd ~/projects/open-webui

Команда mkdir -p ~/projects создаст общую папку для проектов, если её ещё нет, а вторая команда создаст вложенную папку open-webui и сразу сделает её текущим рабочим каталогом. Если папка ~/projects/open-webui уже существует, mkdir сообщит об этом, а переход после && не выполнится. Сначала посмотрим, что лежит в этой папке: прежние настройки и ключ перезаписывать не будем.

Для создания конфигурации можно открыть текущую папку в файловом менеджере. В Ubuntu WSL2 окно Проводника Windows открывается командой:

explorer.exe .

На Mac ту же задачу выполняет команда:

open .

В Ubuntu Linux папку можно открыть через файловый менеджер своей среды или работать в текстовом редакторе из терминала. Точка в приведённых командах обозначает текущий каталог. explorer.exe . относится только к WSL2, а open . к macOS; для запуска самого контейнера они не нужны.

Сохраним конфигурацию и постоянный ключ

В папке ~/projects/open-webui сохраним файл compose.yaml с конфигурацией ниже. Нужен обычный текстовый файл без добавочного расширения .txt. На Mac редактор тоже должен сохранять простой текст, а не документ RTF. Файл одинаков для всех трёх систем:

name: open-webui

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "127.0.0.1:3000:8080"
    volumes:
      - open-webui:/app/backend/data
    extra_hosts:
      - host.docker.internal:host-gateway
    env_file:
      - ./open-webui.env
    restart: unless-stopped

volumes:
  open-webui:

Мы намеренно не записываем секретный ключ прямо в compose.yaml, а подключаем для него отдельный файл ./open-webui.env через директиву env_file. Как указано в документации по переменным окружения Open WebUI, переменная WEBUI_SECRET_KEY используется для подписи токенов сессий и шифрования чувствительных данных. Штатный контейнер технически способен запуститься и без явно переданного ключа, но отдельный файл позволяет передавать тот же ключ после пересоздания контейнера. Смена ключа может завершить пользовательские сеансы и нарушить доступ к зашифрованным данным, поэтому сохраняем его вместе с настройками проекта.

Теперь сохраним случайный ключ в open-webui.env рядом с конфигурацией. Следующий блок выполняется в выбранном терминале от обычного пользователя, без sudo:

if [ ! -e open-webui.env ]; then
  (
    umask 077
    webui_key=$(openssl rand -hex 32) &&
    printf 'WEBUI_SECRET_KEY=%s\n' "$webui_key" > open-webui.env
  )
fi

Разберём, почему эта конструкция безопаснее ручного копирования ключа:

• Проверка if [ ! -e open-webui.env ] защищает от случайной перезаписи: если файл open-webui.env уже существует в текущей папке, команда ничего не изменит и ваш прежний ключ останется на месте.
• Команда umask 077 выполняется в подоболочке (внутри круглых скобок) и ограничивает права нового файла его владельцем. Это работает в Ubuntu и macOS и не меняет настройки текущей сессии терминала.
• Вызов openssl rand -hex 32 генерирует 32 случайных байта в шестнадцатеричном представлении (строку из 64 символов), а оператор && позволяет записать файл только в том случае, если генерация прошла успешно.

Разберём, что запускает Compose и где лежат данные

Прежде чем запускать проект, посмотрим, как каждая строчка в compose.yaml влияет на работу контейнера и хранение данных:

• name: open-webui в самом верху файла задаёт фиксированное имя проекта в Docker Compose. По умолчанию Compose берёт имя проекта из названия папки. Явное поле name сохраняет выбранное имя: даже если вы переименуете каталог в файловой системе, проект для Docker останется прежним. Не меняйте это поле в файле и не переопределяйте его флагом -p или переменной COMPOSE_PROJECT_NAME, иначе Compose будет использовать другое имя проекта и может подключить другое хранилище. Прежние данные при этом могут остаться в старом томе.
• image: ghcr.io/open-webui/open-webui:main указывает официальный образ из руководства быстрого старта Open WebUI. Тег :main является плавающим (rolling tag): его содержимое может измениться при следующем скачивании. Для воспроизводимой установки можно сохранить в конфигурации тег конкретного выпуска. Скачивание образа само по себе не обновляет работающий контейнер.
• ports: - "127.0.0.1:3000:8080" связывает порт 8080, который приложение слушает внутри контейнера, с портом 3000 на вашем компьютере. Привязка к локальному адресу 127.0.0.1 означает, что интерфейс предназначен для открытия в браузере на этом же компьютере, а не с телефона или соседних устройств в локальной сети. При этом нужно обновлять Docker Desktop или Docker Engine: в документации Docker по публикации портов отмечено, что в версиях Docker Engine до 28.0 привязка к loopback-интерфейсу не защищала от прямого обращения из локального сегмента сети (L2), поэтому мы не называем такую настройку абсолютной сетевой изоляцией.
• volumes: - open-webui:/app/backend/data в сочетании с нижней секцией volumes: open-webui: монтирует именованный том Docker в каталог /app/backend/data внутри контейнера. Именно в этой папке Open WebUI хранит базу данных, учетные записи, историю чатов и загруженные файлы. Поскольку Docker Compose автоматически добавляет к имени тома префикс проекта ({project}_{volume}), при проекте open-webui и ключе тома open-webui фактический том в системе получит имя open-webui_open-webui (правила именования подробно описаны в справочнике по томам Compose).
• extra_hosts: - host.docker.internal:host-gateway добавляет в контейнер запись, позволяющую обращаться из изолированной сети Docker к сервисам, запущенным на самой хост-машине (например, если позже вы решите подключить локальный сервер моделей вроде Ollama).
• env_file: - ./open-webui.env передаёт переменные из нашего файла окружения внутрь контейнера при его создании. Путь ./open-webui.env вычисляется относительно папки, в которой лежит compose.yaml.
• restart: unless-stopped задаёт политику автоматического перезапуска. Контейнер возвращается после перезапуска движка, если до этого вы не остановили его вручную. В Windows и macOS сначала должен запуститься Docker Desktop, а в Ubuntu Linux служба Docker Engine. Эта настройка не включает сам Docker Desktop.

Проверим конфигурацию и откроем Open WebUI

Проверим, что в compose.yaml нет синтаксических ошибок или нарушений отступов, а файл open-webui.env находится на своём месте и читается корректно:

docker compose config --quiet

Флаг --quiet в команде docker compose config позволяет проверить конфигурацию без печати итогового манифеста. Без этого флага в вывод попадут и подставленные переменные, включая WEBUI_SECRET_KEY. При успешной проверке с --quiet команда ничего не выводит и возвращает управление терминалу. Так мы проверяем структуру Compose и доступность файла окружения. Качество ключа и готовность самого приложения эта команда не подтверждает.

Теперь загрузим актуальный образ и запустим проект в фоновом режиме:

docker compose pull
docker compose up -d

Явная загрузка образа нужна перед запуском новой установки: если образ с плавающим тегом :main уже есть на компьютере, команда docker compose up может использовать локальную копию без проверки свежей сборки в реестре. Команда docker compose pull скачивает актуальный образ сервиса, но не запускает контейнер. Следующая команда docker compose up -d создаёт сеть проекта, том open-webui_open-webui и запускает контейнер в фоновом режиме (-d, detached). Первая загрузка образа может занять несколько минут в зависимости от скорости интернета.

Проверим статус запущенного контейнера проекта:

docker compose ps

Команда docker compose ps покажет таблицу сервисов текущего проекта. В колонке STATUS ожидаем работающий контейнер. Если отображается health: starting, встроенная проверка ещё ожидает готовности; отметка healthy означает, что она прошла. Сам по себе работающий контейнер пока не подтверждает доступность интерфейса.

При первом запуске Open WebUI выполняет начальную настройку и подготовку базы данных, поэтому веб-интерфейс может откликнуться не в первую же секунду. Чтобы увидеть, чем занято приложение прямо сейчас, откроем журнал контейнера в режиме реального времени:

docker compose logs --tail=100 -f open-webui

Команда docker compose logs с флагом --tail=100 показывает последние 100 строк журнала, а флаг -f (--follow) продолжает выводить новые сообщения по мере их появления. Ориентир готовности из Quick Start, Application startup complete, означает завершение запуска приложения. Чтобы закончить просмотр журнала, нажмите Ctrl+C. Это сочетание завершает только просмотр логов. Фоновый контейнер продолжит работать.

Теперь откроем http://127.0.0.1:3000 в браузере на том же компьютере с Windows, macOS или Ubuntu Linux. Для новой установки ожидаем стартовую страницу создания администратора. Если открылась прежняя установка с уже созданными пользователями, сначала уточним, к какому экземпляру и тому подключились.

Будем управлять проектом с сохранением данных

После первого запуска нам понадобятся команды для остановки, повторного старта и изменения конфигурации. Все команды docker compose выполняем из папки проекта ~/projects/open-webui, где лежит файл compose.yaml.

Если вам нужно временно освободить ресурсы компьютера (оперативную память и процессор), но вы не меняли конфигурацию, используйте остановку:

docker compose stop

Команда docker compose stop аккуратно останавливает работающий контейнер проекта, но не удаляет ни сам контейнер, ни том с данными.

Чтобы снова запустить ранее остановленный контейнер в том же виде, выполните:

docker compose start

У команды docker compose start есть важная особенность: она включает уже существующий контейнер со старыми параметрами и не применяет изменения, если вы успели отредактировать compose.yaml или open-webui.env.

Поэтому, если вы изменили настройки в compose.yaml или обновили переменные в open-webui.env, вместо start используйте команду:

docker compose up -d

При вызове docker compose up -d Compose сверит текущее состояние контейнера с файлами проекта, при необходимости пересоздаст контейнер с новой конфигурацией и подключит к нему тот же самый том open-webui_open-webui со всеми вашими данными.

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

docker compose down

Команда docker compose down без дополнительных флагов удаляет контейнер и сеть по умолчанию, но в нашей конфигурации сохраняет именованный том open-webui_open-webui и файлы compose.yaml и open-webui.env в папке проекта. Для следующего запуска используйте docker compose up -d, сохранив прежнее имя проекта, файл с ключом и сам том. Копирование двух файлов проекта не создаёт резервную копию данных: хранилище находится отдельно.

Отдельно предупредим об опасном флаге, который не нужно запускать на рабочей установке: если добавить к команде down флаг -v (--volumes), Docker удалит вместе с контейнером и именованный том проекта со всей базой данных, пользователями и историей чатов. Подробнее о том, как безопасно обновлять образ и делать резервные копии тома перед изменениями, мы поговорим в уроке про обновление и резервное копирование Open WebUI.

Разберём ошибки запуска и перейдём к первому входу

Если команды docker compose не срабатывают или страница http://127.0.0.1:3000 не открывается в браузере, проверим самые частые причины по шагам.

1. Терминал пишет no configuration file provided: not found. Docker Compose ищет файл compose.yaml в текущем рабочем каталоге. После повторного открытия терминала текущая папка может отличаться от папки проекта. Проверим текущий путь:

pwd

Вернёмся в папку проекта командой cd ~/projects/open-webui. В Ubuntu и WSL2 её полный путь обычно начинается с /home/, на Mac с /Users/. Затем проверим, что файл называется именно compose.yaml, а не compose.yaml.txt.

2. Ошибка чтения open-webui.env при проверке или запуске. Такое случается, если пропустить шаг генерации ключа или назвать файл окружения иначе. Проверьте, что файл open-webui.env лежит в той же папке ~/projects/open-webui, а в compose.yaml путь записан точно как ./open-webui.env. Если ключ уже использовался в этой установке, восстанавливаем прежний файл, а не генерируем новый.

3. Ошибка port is already allocated для порта 3000. Это сообщение означает, что локальный порт 3000 на компьютере уже занят другой программой или старым контейнером. Сначала выясним, что занимает порт. Если это прежняя установка Open WebUI, прервём новую установку и разберёмся с уже работающим экземпляром. Если порт нужен другой программе, для нового проекта можно задать в ports значение "127.0.0.1:3001:8080", применить его через docker compose up -d и открыть http://127.0.0.1:3001.

4. Команда docker compose сообщает, что не может подключиться к демону Docker. В Windows проверим, что Docker Desktop запущен и для Ubuntu включена интеграция WSL2. На Mac дождёмся готовности Docker Desktop. В Ubuntu Linux проверим состояние службы командой systemctl is-active docker. Если при обращении к сокету появляется permission denied, используем прежний способ доступа через sudo docker, описанный в начале урока. Если ранее работающий движок больше недоступен, вернёмся к проверкам подготовительного урока своей ОС.

5. Контейнер запустился, но страница в браузере не открывается или выдаёт ошибку. Если нужно посмотреть последние сообщения контейнера без включения бесконечного потока (-f), выведите последние 100 строк журнала и сразу вернитесь в командную строку:

docker compose logs --tail=100 open-webui

Журнал поможет понять, продолжает ли приложение запускаться или сообщает об ошибке. Если контейнер остановлен, docker compose ps -a покажет и остановленные контейнеры проекта. Том для этой диагностики удалять не нужно.

Когда интерфейс открылся по адресу http://127.0.0.1:3000 в браузере того же компьютера, установка через Docker Compose завершена. У нас есть папка с конфигурацией и постоянным ключом, а рабочие данные приложения сохраняются в именованном томе. Языковая модель подключается отдельно.

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