Windows: WSL2 и Docker Desktop для Open WebUI

В предыдущем уроке мы выбрали способ развёртывания Open WebUI. Если вы остановились на Docker и работаете в Windows, перед запуском самого приложения нужно подготовить рабочую среду. В этом уроке мы шаг за шагом разберём, как устроена связка WSL2, Ubuntu и Docker Desktop, проверим готовность всех утилит и создадим рабочую папку проекта.

При таком подходе Windows остаётся вашей основной операционной системой, а перезагружать компьютер для переключения в другую систему (dual boot) не требуется. Запускать полноценное окружение Linux прямо внутри Windows позволяет встроенная подсистема Windows Subsystem for Linux (WSL). В WSL мы установим Ubuntu. Это один из дистрибутивов Linux со своими файлами, программами и учётной записью пользователя.

Команды Linux из следующих уроков будем вводить в терминале Ubuntu. Команды настройки WSL выполняются в PowerShell в Windows; перед каждым блоком будет указано нужное окно. У подсистемы WSL есть два режима работы, и для контейнеров нам нужен именно WSL2, который использует встроенную виртуализацию для запуска настоящего ядра Linux. Сам Docker Desktop мы установим как обычную программу для Windows: он использует собственный бэкенд на базе WSL2 и отвечает за запуск контейнеров. Хотя Docker Desktop не требует обязательной установки Ubuntu и позволяет вводить команды из терминала Windows, в нашем курсе мы включим интеграцию с Ubuntu. Это даст нам единое и предсказуемое окружение Linux: не нужно устанавливать отдельный Docker Engine внутрь самой Ubuntu, потому что команды из терминала Ubuntu будут напрямую управлять движком Docker Desktop.

Сначала мы проверим системные требования и подготовим Ubuntu в режиме WSL2, затем свяжем её с Docker Desktop, проверим утилиту OpenSSL и создадим каталог для будущих файлов. Сам Open WebUI установим в следующем уроке. Для этого выберем запуск через docker run или Docker Compose.

Что понадобится для работы с Docker Desktop

Инструкция в этом уроке рассчитана на компьютеры под управлением Windows 11 с 64-разрядным процессором Intel или AMD (на странице загрузки Docker эта архитектура обозначена как x86_64). Редакция Windows 11 Home полностью подходит, так как мы будем работать с контейнерами Linux. Системы Windows на архитектуре Arm в рамки этого урока не входят, а на Windows Server установить Docker Desktop по этой инструкции не получится, поскольку программа официально не поддерживает серверные выпуски Windows.

Согласно системным требованиям Docker Desktop для Windows (проверено 14 октября 2026 года), на компьютере должны выполняться следующие условия:

• поддерживаемая версия Windows 11;
• не менее 8 ГБ оперативной памяти;
• 64-разрядный процессор с поддержкой SLAT (Second Level Address Translation), технологии адресации для виртуализации;
• включённая аппаратная виртуализация в настройках компьютера;
• установленный пакет WSL версии 2.1.5 или новее (его установку и обновление мы проверим на следующем шаге).

Установщики и образы будем скачивать из интернета. Для настройки WSL понадобится PowerShell с правами администратора.

Эти требования относятся к Docker Desktop. Если помимо веб-интерфейса вы планируете запускать локальные языковые модели на этом же компьютере, им понадобятся дополнительные память и вычислительные ресурсы. Нужна ли видеокарта, зависит от выбранной модели и способа её запуска. Заранее оценить нагрузку поможет урок о требованиях к Open WebUI. Если ваш компьютер соответствует базовым требованиям, можно переходить к установке WSL2.

Подготовим WSL2 и Ubuntu

Если вы уже установили Ubuntu в WSL раньше, переустанавливать её не нужно: пропустите первый шаг и сразу переходите к проверке версий ниже. Если же WSL и Ubuntu на компьютере ещё не настроены, откройте меню «Пуск», найдите PowerShell, нажмите на него правой кнопкой мыши и выберите запуск от имени администратора.

Чтобы одновременно включить нужные компоненты WSL и скачать дистрибутив Ubuntu, выполните команду из руководства Microsoft по установке WSL. PowerShell в Windows от имени администратора:

wsl --install -d Ubuntu

Эта команда включает компоненты подсистемы Linux и загружает дистрибутив Ubuntu, который по умолчанию сразу настраивается на работу в режиме WSL2. Когда процесс в консоли завершится, обязательно перезагрузите Windows, чтобы изменения вступили в силу.

После перезагрузки найдите приложение Ubuntu в меню «Пуск» и запустите его. Откроется окно терминала для первичной настройки системы. Ubuntu попросит задать имя пользователя и пароль. Эта учётная запись действует только внутри вашей среды Ubuntu и не привязана к паролю входа в Windows. При вводе пароля в терминале Linux не появляются ни буквы, ни звёздочки. Введём пароль и нажмём Enter. Он понадобится позже для команд с повышенными правами через sudo.

Когда вы увидите приглашение командной строки Linux, базовая установка Ubuntu завершена. Теперь проверим две важные детали: версию самого пакета WSL в Windows и режим работы установленного дистрибутива Ubuntu. Для этого вернёмся в окно PowerShell в Windows и выполним команды из справочника основных команд WSL:

wsl --version
wsl -l -v

Важно не путать результаты этих двух команд, так как они проверяют разные вещи:

1. Команда wsl --version выводит версию самой подсистемы WSL в Windows. В первой строке (WSL version) должно быть значение 2.1.5 или новее, иначе Docker Desktop может отказаться запускаться.
2. Команда wsl -l -v показывает таблицу всех установленных дистрибутивов Linux и режим каждого из них. Найдите в списке строку со своей системой (обычно она называется Ubuntu) и посмотрите на столбец VERSION. Там должна стоять цифра 2. Цифра 2 в этом столбце означает лишь то, что дистрибутив работает на архитектуре WSL2, но сама по себе она не заменяет проверку версии пакета через wsl --version.

Если обе проверки сразу показали нужные значения (пакет WSL не старее 2.1.5 и у Ubuntu стоит VERSION 2), два следующих шага с обновлением и конвертацией можно пропустить.

Если же первая проверка показала, что пакет WSL старее версии 2.1.5, или команда wsl --version вовсе не распознаётся старой версией компонента, обновим пакет WSL. PowerShell в Windows от имени администратора:

wsl --update

Дождитесь окончания загрузки и установки обновления.

Второй шаг нужен, если Ubuntu была установлена давно и в таблице wsl -l -v напротив неё в столбце VERSION стоит 1. Прежде чем переводить такой дистрибутив в режим WSL2, обязательно сохраните резервную копию важных файлов из этой Ubuntu в надёжное место, так как операция преобразования файловой системы иногда может завершиться ошибкой. После сохранения данных выполните в PowerShell в Windows от имени администратора:

wsl --set-version Ubuntu 2

Здесь Ubuntu указывает имя дистрибутива из столбца NAME в выводе wsl -l -v. Если ваш ранее установленный дистрибутив называется, например, с номером выпуска, подставьте в команду его точное имя из списка. Преобразование может занять несколько минут. Если вы выполняли обновление пакета или смену версии дистрибутива, после них ещё раз запустите wsl --version и wsl -l -v, чтобы убедиться, что теперь оба условия выполнены.

Открывать терминал Ubuntu для работы можно как через ярлык Ubuntu в меню «Пуск», так и прямо из окна PowerShell в Windows специальной командой:

wsl --distribution Ubuntu

Здесь также используется точное имя дистрибутива из списка wsl -l -v. После ввода команды приглашение строки изменится: вы окажетесь внутри оболочки Linux. Чтобы дальше по ходу курса не путать окна, обращайте внимание на подписи перед блоками кода: команды с пометкой PowerShell в Windows вводятся в оболочке Windows, а команды с пометкой «Терминал Ubuntu» выполняем внутри Linux-среды.

Когда Ubuntu нормально открывается, версия пакета WSL не ниже 2.1.5, а в столбце VERSION для Ubuntu стоит 2, переходим к установке и настройке Docker Desktop.

Подключим Ubuntu к Docker Desktop

Теперь установим Docker Desktop в Windows и подключим к нему нашу Ubuntu. Благодаря этому вам не нужно устанавливать отдельный движок Docker внутрь самой Ubuntu: команда docker, вызванная в терминале Ubuntu, будет обращаться к движку Docker Desktop, работающему в Windows.

Перед установкой обратите внимание на важную деталь для тех, кто уже пользовался Ubuntu раньше. Если когда-то вы вручную устанавливали собственный Docker Engine или Docker CLI прямо внутри Ubuntu через менеджер пакетов Linux, они могут конфликтовать с интеграцией Docker Desktop. В документации по настройке WSL для Docker Desktop рекомендуется не использовать параллельно старый Linux-движок, однако удалять его вслепую нельзя: вместе со старым Docker Engine в Ubuntu могут храниться ваши прежние контейнеры и тома с данными. Если у вас есть такая старая установка в Ubuntu, сначала проверьте и сохраните нужные данные отдельно; автоматическое удаление прежних сред в этот урок не входит.

Для чистой установки откройте страницу загрузки Docker Desktop для Windows и скачайте установщик для архитектуры x86_64. Запустите скачанный файл Docker Desktop Installer.exe. В окне настроек установщика ориентируйтесь на штатные параметры:

• выберите рекомендуемый режим установки per-user (для текущего пользователя);
• если установщик предлагает выбрать бэкенд виртуализации, убедитесь, что отмечено использование WSL 2 (Use WSL 2 instead of Hyper-V).

Дождитесь завершения установки и запустите Docker Desktop через меню «Пуск». При первом старте программа покажет условия подписки и лицензионного соглашения (Docker Subscription Service Agreement). Docker Desktop бесплатен не для всех категорий использования (например, для коммерческого применения в компаниях с определённым штатом или оборотом требуется платная подписка), поэтому внимательно прочитайте условия на экране и убедитесь, что они подходят для вашего сценария, прежде чем принимать их.

Когда главное окно Docker Desktop запустится и его движок перейдёт в рабочее состояние, свяжем его с нашей средой Ubuntu:

1. Откройте настройки программы (значок шестерёнки в верхней панели) и перейдите в раздел Settings → General. Убедитесь, что включена опция Use the WSL 2 based engine (или Use WSL 2 based engine). В некоторых версиях и конфигурациях Windows этот режим активен по умолчанию, а сам переключатель скрыт или недоступен для выключения. В этом случае режим уже выбран.
2. Перейдите в раздел Settings → Resources → WSL Integration. В списке доступных дистрибутивов найдите свою Ubuntu (ориентируйтесь на точное имя из вывода wsl -l -v) и переведите переключатель рядом с ней во включённое положение.
3. Нажмите кнопку применения настроек внизу окна (Apply или Apply & restart; точная подпись зависит от версии программы) и дождитесь, пока Docker Desktop перезапустит подсистему интеграции.

Если после этого вы снова посмотрите список систем в PowerShell через wsl -l -v, вы заметите там дополнительный дистрибутив docker-desktop. Это внутренняя служебная система самого Docker Desktop: трогать её или пытаться открывать в ней терминал не нужно. Все рабочие команды мы будем по-прежнему вводить в нашей основной Ubuntu.

Плагин Docker Compose уже входит в состав Docker Desktop, поэтому скачивать его отдельно не придётся. Оставьте приложение Docker Desktop запущенным в фоновом режиме и переключитесь в терминал Ubuntu, чтобы проверить связь.

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

Убедитесь, что Docker Desktop запущен в Windows, и выполните в терминале Ubuntu проверку версий клиента, сервера и плагина Compose:

docker version
docker compose version

Как устроен вывод команды docker version и на что здесь смотреть:

• В блоке Client указана версия утилиты командной строки, которую мы вызвали в терминале. Однако наличие только блока Client ещё не означает, что Docker готов к работе.
• Следом обязательно должен отобразиться блок Server (Docker Engine) без сообщений об ошибках подключения. Секция Server подтверждает, что терминал Ubuntu успешно связался с работающим фоновым демоном Docker Desktop.
• Вторая команда (docker compose version) должна вывести номер версии установленного плагина Docker Compose.

Если в выводе docker version присутствуют и Client, и Server, а docker compose version показывает версию, интеграция работает исправно. Если же команда не найдена или вместо секции Server появилась ошибка связи, сначала проверим возможные причины в следующем разделе урока.

Для следующего урока также понадобится OpenSSL. Проверим, доступна ли эта утилита в Ubuntu. В нашем курсе и при запуске через одиночную команду docker run, и при развёртывании через Docker Compose мы создаём постоянный ключ WEBUI_SECRET_KEY с помощью openssl. Его сохраняют при пересоздании контейнера. Это относится к обеим практическим веткам курса. Сам ключ мы создадим уже на этапе установки Open WebUI, а сейчас убедимся, что утилита доступна в вашей системе.

Выполните в терминале Ubuntu:

openssl version

Если OpenSSL установлен, команда покажет его версию. Если версия отобразилась, установка OpenSSL не нужна. Можно переходить к папке проекта.

И только в том случае, если терминал ответил ошибкой command not found, установим утилиту через стандартный менеджер пакетов APT. Терминал Ubuntu:

sudo apt update
sudo apt install openssl

Команда sudo apt update обновляет локальный список доступных пакетов из репозиториев Ubuntu, а sudo apt install openssl загружает и устанавливает саму программу. Поскольку команды выполняются с префиксом sudo (с правами администратора Linux), терминал попросит ввести пароль учётной записи Ubuntu, заданный при первом запуске. При вводе символы не отображаются. Перед установкой APT покажет список пакетов, которые собирается добавить: просмотрите его и подтвердите действие. После завершения ещё раз выполните openssl version, чтобы убедиться, что программа заработала.

В завершение подготовки создадим в Ubuntu каталог, где будут храниться файлы наших будущих проектов. При работе из терминала WSL2 Microsoft рекомендует размещать рабочие файлы проекта в файловой системе Linux, а не на дисках Windows (/mnt/c/...), для работы из Linux-терминала. Это помогает избежать потери производительности при обращении к файлам на диске Windows.

Создадим общую папку projects в домашнем каталоге пользователя, перейдём в неё и проверим текущий путь. Терминал Ubuntu:

mkdir -p ~/projects
cd ~/projects
pwd

Символ тильды (~) в Linux обозначает домашний каталог текущего пользователя. Флаг -p позволяет создать папку projects без ошибки, даже если она уже существовала. Команда cd переводит терминал внутрь этого каталога, а команда pwd (print working directory) выводит полный путь к текущей папке. Ожидаем строку вида /home/<ваше_имя_пользователя>/projects. Именно из этой папки мы продолжим работу в следующем уроке, когда будем создавать файлы для Open WebUI.

Хотя папка находится внутри файловой системы Ubuntu, к ней легко обращаться и из графического интерфейса Windows. Чтобы открыть текущий каталог Linux в обычном Проводнике Windows, выполните в терминале Ubuntu:

explorer.exe .

Обратите внимание на пробел и точку (.) в конце команды: точка в Linux указывает на текущую рабочую папку. На экране откроется окно Проводника Windows со списком файлов внутри вашей ~/projects, а сам терминал останется в этом же каталоге.

Если среда не запускается

Если на каком-то из предыдущих шагов команда выдала ошибку, не спешите переустанавливать систему или удалять дистрибутив Ubuntu. Сообщение об ошибке поможет выбрать следующую проверку.

1. При первой установке загрузка Ubuntu зависает на 0.0%. Если загрузка не продвигается, документация Microsoft по установке WSL советует добавить флаг прямой загрузки из интернета --web-download. Выполните в PowerShell в Windows от имени администратора:

wsl --install --web-download -d Ubuntu

После завершения скачивания и установки перезагрузите компьютер и продолжите первичную настройку Ubuntu.

2. Docker Desktop при запуске сообщает, что версия WSL устарела. Такое сообщение связано с версией системного пакета WSL в Windows, а не с цифрой 2 в списке дистрибутивов wsl -l -v. Обновите пакет и сразу проверьте его итоговую версию в PowerShell в Windows от имени администратора:

wsl --update
wsl --version

Убедитесь, что после обновления строка WSL version показывает значение 2.1.5 или новее, после чего перезапустите Docker Desktop.

3. При запуске Ubuntu или установке WSL2 появляется ошибка 0x80370102. Согласно руководству Microsoft по устранению неполадок WSL, при ошибке 0x80370102 сначала проверяют компонент Windows Virtual Machine Platform («Платформа виртуальной машины») и аппаратную виртуализацию в прошивке компьютера (UEFI/BIOS).

Сначала проверим компонент Windows:

• Нажмите «Пуск», введите в поиск «Включение или отключение компонентов Windows» (название в английском интерфейсе: Turn Windows features on or off) и откройте найденное окно.
• Прокрутите список до пункта Платформа виртуальной машины (Virtual Machine Platform). Если галочка снята, установите её, нажмите ОК и обязательно перезагрузите компьютер.

Если этот компонент уже был включён, но после перезагрузки ошибка 0x80370102 сохраняется, проверим, включена ли аппаратная виртуализация в настройках компьютера (UEFI). Открыть меню UEFI прямо из Windows можно по инструкции поддержки Microsoft: откройте Параметры (Settings) → Система (System) → Восстановление (Recovery) и рядом с пунктом Особые варианты загрузки (Advanced startup) нажмите Перезагрузить сейчас (Restart now). На синем экране после перезапуска выберите Поиск и устранение неисправностей (Troubleshoot) → Дополнительные параметры (Advanced options) → Параметры встроенного ПО UEFI (UEFI Settings) → Перезагрузить (Restart).

В интерфейсе UEFI точное название и расположение пункта виртуализации зависят от производителя компьютера или материнской платы (он может находиться в разделах процессора или конфигурации и называться Intel Virtualization Technology, VT-x, AMD-V или SVM Mode). Сверьтесь с документацией к вашей модели устройства, включите только эту настройку виртуализации, сохраните изменения и перезагрузите компьютер. Другие параметры прошивки менять не нужно.

4. В терминале Ubuntu при вызове docker появляется ошибка command not found или сообщение об отсутствии интеграции. Откройте окно Docker Desktop в Windows, перейдите в Settings → Resources → WSL Integration и проверьте, включён ли переключатель напротив вашей Ubuntu (и нажата ли кнопка Apply). Если в разделе Resources вообще нет вкладки WSL Integration, проверьте, в каком режиме контейнеров сейчас работает Docker Desktop: нажмите на значок Docker в системном трее Windows (около часов). Если в контекстном меню виден пункт Switch to Linux containers…, выберем его. В нашем маршруте Docker Desktop запускает контейнеры Linux.

5. Команда docker version выводит блок Client, но вместо Server пишет ошибку подключения к демону. Клиент Docker доступен, но пока не может связаться с сервером. Проверим, запущен ли Docker Desktop и готов ли его движок. Откройте приложение Docker Desktop в Windows, дождитесь готовности его движка, а затем повторите проверку в терминале Ubuntu:

docker version

Если в ответе появились Client и Server без ошибки соединения, связь с сервером Docker работает. Удалять саму Ubuntu или сбрасывать её файлы при таких ошибках связи не нужно.

Теперь можно переходить к Open WebUI

Сверим результаты подготовки перед установкой Open WebUI:

• терминал Ubuntu открывается и работает в режиме WSL2 (VERSION 2 в выводе wsl -l -v, а версия пакета WSL не ниже 2.1.5);
• Docker Desktop запущен в Windows с интеграцией для вашей Ubuntu;
• команда docker version в терминале Ubuntu выводит и Client, и Server без ошибок связи;
• команда docker compose version показывает версию Compose;
• команда openssl version возвращает версию установленного OpenSSL;
• команда pwd в терминале Ubuntu показывает подготовленную рабочую папку /home/<ваше_имя>/projects.

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

• В уроке установки Open WebUI через Docker запустим контейнер командой docker run и сохраним ключ в отдельном файле.
• В уроке установки Open WebUI через Docker Compose опишем запуск в файле compose.yaml.

Проходить оба этих урока подряд не нужно: это два альтернативных способа решить одну и ту же задачу. А если на этапе проверки выяснилось, что аппаратные требования Docker Desktop или виртуализация WSL2 не подходят для вашего компьютера, можно вернуться к уроку о выборе схемы установки и рассмотреть вариант запуска без Docker.