Оригинал: https://timofei-ermolaev.ru/courses/open-webui/install/docker-compose/ # Установка Open WebUI через Docker Compose Установим Open WebUI через Docker Compose на Windows, macOS или Ubuntu Linux. Сохраним настройки, постоянный ключ и данные, проверим запуск и разберём ошибки. [![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_Z1x8STQ.webp)]() [Тимофей Ермолаев]() Директор по информационным технологиям (CIO) **Опубликовано** 9 октября 2026 г. **Обновлено** 15 октября 2026 г. **На урок** 20 мин **Тема** [Установка Open WebUI]() ## После урока вы сможете - Создать Compose-файл для локальной установки Open WebUI - Разобраться в назначении образа, портов и постоянного тома - Запускать и останавливать проект с сохранением данных **Проверяемый результат:** Open WebUI открывается по адресу 127.0.0.1:3000 в браузере того же компьютера с Windows, macOS или Ubuntu Linux. Конфигурация и постоянный ключ сохранены в папке проекта, данные находятся в именованном томе Docker. Когда сервис запускают одной длинной командой `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 ещё не подготовлен, начнём с урока для вашей системы. Остальные ветки можно пропустить. | Система | Что уже должно работать | Где выполняем команды этого урока | | --- | --- | --- | | [Windows]() | Docker Desktop с контейнерами Linux и интеграцией с Ubuntu в WSL2 | В терминале Ubuntu, открытом через WSL2 | | [macOS]() | Локальный Docker Desktop | В приложении «Терминал» macOS | | [Ubuntu Linux]() | Локальная служба Docker Engine и плагин Compose | В обычном терминале Ubuntu 24.04 | Команды для файлов и папок ниже подходят для 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 завершена. У нас есть папка с конфигурацией и постоянным ключом, а рабочие данные приложения сохраняются в именованном томе. Языковая модель подключается отдельно. Первая учётная запись на новой установке получает права администратора. В следующем уроке пройдём [первый вход и базовые настройки доступа]() , после чего подключим выбранную модель. ## Материалы урока - [Open WebUI: официальный пример Docker Compose docs.openwebui.com]() - [Docker Compose: запуск проекта docs.docker.com]() - [Docker Compose: именованные тома docs.docker.com]() ## Отметить прохождение Отметьте урок после того, как получили проверяемый результат из практической части. Урок пройден ![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_2r7Nkv.webp) ## Об авторе ### Тимофей Ермолаев Директор по информационным технологиям (CIO) Пишу о больших языковых моделях, автоматизации и применении ИИ в бизнесе. В статьях разделяю личный опыт, выводы исследований и практические рекомендации. [Подробнее об авторе]()