Устанавливаем Open WebUI в Docker: Windows и WSL2

В уроке о выборе схемы установки мы сравнивали два подхода к запуску контейнера: прямую команду docker run и конфигурацию Docker Compose. Вам не нужно проходить оба варианта на одном компьютере: если вы уже развернули сервис через Compose, переходить к этому уроку не требуется. Здесь мы продолжаем маршрут для тех, кто выбрал быстрый запуск через docker run и уже завершил подготовку Windows, WSL2, Ubuntu и Docker Desktop.

Docker Desktop работает в Windows в режиме Linux-контейнеров, а управлять им мы будем из терминала Ubuntu благодаря интеграции WSL2. Устанавливать отдельный Docker Engine внутри самой Ubuntu не нужно, как не понадобятся для команд этого урока PowerShell или классическая командная строка Windows. Все команды выполняем в Ubuntu, а готовый интерфейс откроем в обычном браузере Windows.

Этот сценарий рассчитан на новую локальную установку на вашем рабочем компьютере, а не на публичный Linux-сервер. Настройку первой учётной записи администратора и подключение языковых моделей мы разберём на следующих шагах.

Подготовим Docker и постоянный ключ

Перед началом установки убедимся, что Docker Desktop запущен в Windows, а из терминала Ubuntu можно обращаться к демону Docker. Одновременно проверим, не остались ли в системе контейнеры или тома от прежних запусков Open WebUI:

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

Разберём результаты всех трёх команд по порядку:

• В выводе docker version должны присутствовать секции Client и Server без ошибок подключения. Блок Server подтверждает, что движок Docker Desktop активен и отвечает на запросы из WSL2.
• Команда docker ps -a показывает все контейнеры, включая остановленные. Поскольку фильтр --filter name=open-webui ищет совпадение по подстроке, смотрите на точное имя в столбце NAMES. Если там уже есть контейнер open-webui, перед вами существующая установка. Создавать её заново по шагам этого урока не нужно: в разделе разбора ошибок ниже мы покажем, как запустить уже имеющийся контейнер.
• Команда docker volume ls выводит список именованных томов Docker. Здесь фильтр также работает по подстроке, поэтому проверяйте точное значение open-webui в колонке VOLUME NAME. Именованный том живёт независимо от контейнера и сохраняется даже после его удаления. Если том open-webui уже существует, остановитесь и не продолжайте чистую установку: внутри могут находиться ваши прежние данные, для работы с которыми нужен старый секретный ключ. Сам том сохраняем и не перегенерируем ключ поверх существующего хранилища.

Если в обоих списках нет open-webui, переходим к чистой установке. Создадим в домашнем каталоге Ubuntu папку, в которой будем хранить файл окружения с секретным ключом, и перейдём в неё:

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

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

Сгенерируем случайный ключ с помощью утилиты OpenSSL. Сначала проверим, установлена ли она в Ubuntu:

openssl version

Если в терминале появилась строка с версией OpenSSL, переходите к созданию файла ключа. Если Ubuntu выводит сообщение command not found, установите пакет через штатный менеджер пакетов:

sudo apt update
sudo apt install openssl

Эти команды устанавливают OpenSSL только внутри дистрибутива Ubuntu в WSL2; в самой Windows ничего дополнительно устанавливать не нужно.

Теперь запишем новый секретный ключ в файл open-webui.env в текущей папке ~/projects/open-webui:

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.
• Сгенерированный 64-символьный шестнадцатеричный ключ сразу записывается в файл и не выводится на экран терминала. Не публикуйте этот файл в открытых репозиториях или чатах и сохраняйте его для будущих обновлений контейнера.

Загрузим образ Open WebUI

При установке в контейнере все файлы приложения и необходимые библиотеки уже упакованы в готовый образ Docker, поэтому настраивать Python или Node.js в системе не требуется.

Скачаем официальный образ из руководства Quick Start:

docker pull ghcr.io/open-webui/open-webui:main

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

Мы используем тег main, который предложен в официальном руководстве быстрого старта. Важно учитывать, что main указывает на обновляемую сборку основной ветки. Это не тег фиксированного стабильного выпуска: со временем его содержимое в реестре обновляется. Если вы разворачиваете сервис для постоянной работы, где важна строгая предсказуемость версий, лучше выбрать тег конкретного релиза. При этом выбранный тег должен совпадать и в команде docker pull, и в последующей команде docker run.

Запустим контейнер и разберём параметры

Когда образ скачан, создадим и запустим контейнер. Выполните следующую команду из каталога ~/projects/open-webui, где лежит файл open-webui.env:

docker run -d \
  -p 127.0.0.1:3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  --env-file ./open-webui.env \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Символ обратной косой черты (\) в конце строк позволяет разбить одну длинную команду на наглядные строчки. Вставим и выполним весь блок целиком.

Разберём назначение каждого флага в этой команде docker run:

• -d запускает контейнер в фоновом режиме (detached). Docker создаст контейнер, выведет в терминал его длинный идентификатор и сразу освободит командную строку.
• -p 127.0.0.1:3000:8080 связывает порт 8080 внутри контейнера с портом 3000 на локальном интерфейсе 127.0.0.1 вашего компьютера. Благодаря такой привязке веб-интерфейс будет доступен из браузера Windows на этом же компьютере по адресу http://localhost:3000. В этом уроке интерфейс предназначен для работы на том же компьютере. Общий доступ с других устройств потребует отдельной настройки.
• --add-host=host.docker.internal:host-gateway добавляет во внутренний список хостов контейнера специальное имя host.docker.internal. Через него изолированный контейнер сможет обращаться к сервисам, работающим на хост-системе, как описано в документации по сети Docker Desktop. Этот параметр пригодится позже, если мы будем подключать локальную Ollama, однако сам по себе он не устанавливает Ollama и не гарантирует автоматического подключения к моделям.
• --env-file ./open-webui.env считывает переменные из нашего файла окружения и передаёт WEBUI_SECRET_KEY внутрь контейнера без отображения секрета в истории команд.
• -v open-webui:/app/backend/data подключает именованный том Docker с именем open-webui к папке /app/backend/data внутри контейнера. Если тома ещё нет, Docker создаст его автоматически. В этом томе хранятся база данных, учётные записи, чаты и настройки. Том размещается во внутреннем хранилище Docker (а не в нашей папке ~/projects/open-webui) и сохраняется даже при удалении контейнера. Помните, что при дальнейшем обслуживании нужно беречь и том open-webui, и файл open-webui.env, а само наличие тома не заменяет регулярных резервных копий.
• --name open-webui задаёт контейнеру постоянное понятное имя, по которому к нему удобно обращаться при просмотре логов, остановке и запуске.
• --restart always включает автоматический перезапуск контейнера при сбое процесса или при старте демона Docker. Учитывайте, что это правило работает только тогда, когда запущен сам Docker Desktop в Windows: саму программу Docker Desktop этот флаг не включает.

Проверим приложение в браузере

То, что команда docker run завершилась без ошибок и вывела идентификатор, означает лишь успешное создание и старт процесса контейнера. Проверим текущее состояние контейнера:

docker ps --filter name=open-webui

В строке контейнера open-webui статус в колонке STATUS должен начинаться со слова Up, а в колонке PORTS отобразится проброс 127.0.0.1:3000->8080/tcp. При этом сам статус Up говорит о том, что контейнер запущен, но внутренние службы Open WebUI при первом старте могут ещё выполнять миграции базы данных и подготовку окружения.

Чтобы убедиться, что веб-сервер внутри контейнера готов принимать запросы, посмотрим последние 50 строк его системного журнала с помощью docker logs:

docker logs --tail 50 open-webui

В документации Quick Start признаком полной готовности приложения служит сообщение Application startup complete. Если в выводе пока видны только промежуточные шаги инициализации, включите режим наблюдения за новыми строками журнала в реальном времени:

docker logs -f open-webui

Когда увидите сообщение о завершении запуска, нажмите комбинацию клавиш Ctrl+C. Она остановит только просмотр журнала в терминале Ubuntu, а сам контейнер продолжит работать в фоновом режиме.

Теперь откройте обычный браузер в Windows на этом же компьютере и перейдите по адресу http://localhost:3000. На чистой установке вас встретит стартовая страница регистрации первой учётной записи. Первый зарегистрированный пользователь в Open WebUI получает права администратора. Само создание аккаунта и начальные настройки безопасности мы подробно разберём в следующем уроке про первого администратора, а сейчас достаточно убедиться, что страница интерфейса загрузилась.

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

Перед переходом дальше сверим, что отвечает за сохранение данных при пересоздании контейнера. База данных и чаты сохраняются в именованном томе open-webui, подключённом к /app/backend/data. Неизменный ключ из open-webui.env нужен для пользовательских сеансов и доступа к зашифрованным данным. Параметр -p отвечает за сетевой порт, а --name задаёт имя контейнера.

Если запуск не получился

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

1. Docker сообщает об ошибке подключения к демону или команда docker не найдена. Проверьте, запущен ли Docker Desktop в Windows, и дождитесь его полной готовности. Затем повторите docker version в терминале Ubuntu. Если сам терминал не распознаёт команду docker, вернитесь к настройке интеграции WSL2 в предыдущем уроке.

2. Ошибка конфликта имени: контейнер open-webui уже существует. Команда docker run всегда пытается создать новый контейнер, поэтому она остановится, если имя open-webui уже занято (например, от предыдущей попытки запуска). Посмотрим список всех подходящих контейнеров, включая остановленные:

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

Проверьте точное имя open-webui в колонке NAMES. Если это ваша существующая установка и контейнер находится в статусе Exited или Created, не нужно запускать docker run повторно. Запустите уже созданный контейнер со всеми его прежними параметрами и данными:

docker start open-webui

Если контейнер уже в статусе Up, переходите сразу к проверке логов и браузера. Если же после docker start open-webui контейнер через несколько секунд снова останавливается, выполните docker logs --tail 50 open-webui, чтобы прочитать текст ошибки приложения без удаления контейнера и тома.

3. Ошибка open ./open-webui.env: no such file or directory. Docker ищет файл окружения относительно той папки, в которой вы находитесь в момент ввода команды. Перейдите в каталог проекта и проверьте текущий путь:

cd ~/projects/open-webui
pwd

Если файл open-webui.env уже лежит в этой папке, просто повторите команду запуска отсюда, не генерируя новый ключ. Если файла ещё нет, вернитесь к шагу создания ключа в первом разделе урока.

4. Ошибка привязки порта: порт 3000 уже занят. Если порт 3000 на вашем компьютере удерживает другая программа, которую можно закрыть, остановите её. У Docker есть особенность, которую стоит учесть: даже если docker run завершился ошибкой привязки порта, Docker мог уже успеть создать сам контейнер open-webui в остановленном состоянии. Поэтому после освобождения порта проверьте список через docker ps -a --filter name=open-webui и запустите созданный контейнер командой docker start open-webui.

Если порт 3000 необходим другой программе постоянно и вы ещё не создали контейнер open-webui, в команде docker run для нового контейнера можно заменить проброс порта на -p 127.0.0.1:3001:8080 и открывать в браузере http://localhost:3001. Однако если контейнер с именем open-webui уже успел создаться, повторный вызов docker run с портом 3001 приведёт к конфликту имён. Безопасное пересоздание существующего контейнера с новыми параметрами при сохранении тома и ключа мы подробно разберём в уроке об обновлении и резервных копиях.

5. Контейнер запущен (Up), но браузер не открывает страницу. Сверьте адрес http://localhost:3000 с портом в выводе docker ps --filter name=open-webui и проверьте логи через docker logs --tail 50 open-webui. Возможно, приложению ещё нужно время для завершения первого запуска. Также убедитесь, что вы открываете браузер на том же компьютере с Windows, где работает Docker Desktop: локальный адрес 127.0.0.1 (localhost) не предназначен для подключения с других компьютеров.

Перейдём к первому входу

Если проверки прошли, результат урока выглядит так: в Docker Desktop работает контейнер open-webui, данные приложения вынесены в независимый именованный том open-webui, постоянный секретный ключ сохранён в файле ~/projects/open-webui/open-webui.env, а веб-интерфейс откликается в браузере Windows по адресу http://localhost:3000.

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