Подготовка Docker для macOS

В этом уроке мы подготовим среду для запуска контейнера Open WebUI на компьютере Mac с помощью Docker Desktop. Мы проверим архитектуру процессора и совместимость системы, установим Docker Desktop, убедимся в работе его фоновой службы и плагина Docker Compose в штатном приложении «Терминал», проверим наличие утилиты OpenSSL и подготовим рабочий каталог для будущего проекта.

Этот материал продолжает шаг с выбором способа установки для пользователей macOS. Если вы работаете на Mac, вам не нужно проходить урок по настройке Windows и WSL2: здесь мы сразу подготовим родное окружение macOS перед переходом к непосредственному запуску приложения.

Разберём, как устроен Docker на macOS

Перед установкой разберём роли между вашей операционной системой и контейнерами. Контейнеры, с которыми мы будем работать, рассчитаны на ядро Linux. Поскольку macOS использует собственное ядро, Docker Desktop на Mac запускает демон Docker и сами контейнеры внутри лёгкой виртуальной машины Linux, а не напрямую на ядре вашей системы.

При этом вам не нужно отдельно настраивать эту виртуальную машину или устанавливать второй дистрибутив вроде Ubuntu:

• Docker Desktop управляет фоновой виртуальной машиной Linux, включает в себя демон (серверную часть Docker Engine), клиент командной строки (docker) и плагин docker compose.
• Штатное приложение «Терминал» (Terminal) в macOS служит вашей рабочей командной строкой. Команды docker и docker compose, которые вы вводите в Терминале Mac, обращаются к демону внутри виртуальной машины Docker Desktop.
• Права внутри контейнера и на Mac различаются: права администратора (root) внутри контейнера или виртуальной машины Linux не равняются правам root на самом Mac. Поэтому запускать клиентские команды Docker через sudo в терминале macOS не нужно.

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

Проверим чип Mac и системные требования

Установщик Docker Desktop для macOS выпускается в двух вариантах: для чипов Apple Silicon и для процессоров Intel. Чтобы скачать подходящий пакет, нужно точно определить архитектуру вашего компьютера. Проверять её только консольной командой uname -m ненадёжно: если терминал запущен через транслятор Rosetta, команда может показать архитектуру x86_64 даже на компьютере с чипом Apple.

Проверить конфигурацию можно через системное меню по инструкции Apple:

1. Нажмите на значок Apple () в левом верхнем углу экрана и выберите пункт «Об этом Mac» (About This Mac).
2. Посмотрите на строку с описанием процессора в открывшемся окне:
   • Если вы видите пункт «Чип» (Chip), за которым следует название вроде Apple M1, M2, M3 или M4, у вас компьютер с Apple Silicon.
   • Если вы видите пункт «Процессор» (Processor) с названием Intel Core, у вас компьютер на базе Intel.

Заодно сверьтесь с системными требованиями Docker Desktop для Mac:

• Версия macOS: поддерживаются текущий основной релиз macOS и два предыдущих основных выпуска.
• Оперативная память: для работы самого Docker Desktop требуется не менее 4 ГБ RAM. Это минимум для Docker Desktop. Ресурсы Open WebUI и выбранной локальной модели оцениваются отдельно.
• Rosetta 2 на компьютерах с Apple Silicon: в актуальных версиях Docker Desktop установка Rosetta 2 больше не является строгим обязательным условием для работы. Она может понадобиться, если вы будете запускать отдельные инструменты, собранные исключительно под архитектуру AMD64 (x86_64). Принудительно устанавливать Rosetta 2 заранее не требуется.

Установим и запустим Docker Desktop

Когда архитектура чипа известна, установим приложение:

1. Откройте официальную страницу установки Docker Desktop на Mac и скачайте установочный образ Docker.dmg для вашего компьютера (Docker Desktop for Mac with Apple silicon или Docker Desktop for Mac with Intel chip).
2. Дважды нажмите на скачанный файл Docker.dmg в папке «Загрузки», чтобы подключить образ диска, и в открывшемся окне перетащите значок Docker.app в папку Applications («Программы»).
3. Откройте папку «Программы» (Applications) и запустите приложение Docker.

Поведение при первом запуске зависит от версии программы, поэтому ориентируйтесь на то, что показывает интерфейс на вашем экране:

• На шаге с условиями обслуживания (Docker Subscription Service Agreement) внимательно прочитайте лицензионное соглашение. Docker Desktop бесплатен не для всех категорий использования (например, для крупных компаний действуют отдельные условия подписки), поэтому не используйте ключи автоматического принятия лицензии и примите соглашение в окне программы только после ознакомления.
• В актуальных версиях Docker Desktop при выборе стандартных настроек конфигурация по умолчанию не требует ввода пароля администратора macOS: ссылки на инструменты командной строки (docker и сопутствующие утилиты) создаются в вашем пользовательском каталоге ~/.docker/bin, который автоматически добавляется в переменную PATH вашей оболочки.
• В более старых выпусках (версии 4.88 и более ранних) мастер первого запуска с выбором Use recommended settings запрашивал пароль администратора. В современных версиях запрос пароля появляется только в том случае, если вы сами решите выбрать расширенные системные настройки (например, размещение ссылок в системном каталоге /usr/local/bin через раздел Settings → Advanced). Для нашей работы штатного пользовательского режима без прав администратора полностью достаточно.

Дождитесь, пока приложение завершит инициализацию: в верхней строке меню macOS появится значок Docker (кит с контейнерами), а в самом окне Docker Desktop статус движка перейдёт в рабочее состояние (Engine running).

Проверим Docker CLI, демон и Docker Compose в Терминале

Теперь убедимся, что команды управления контейнерами доступны из командной строки и подключены именно к локальному Docker Desktop. Как описано в руководстве по работе с Терминалом на Mac, откройте приложение «Терминал» (Terminal) через поиск Spotlight или из папки «Программы» → «Утилиты» (Applications → Utilities). При копировании команд из урока не вводите символ приглашения оболочки ($ или %), если он отображается в начале строки в вашем окне.

Как указано в документации по установке Docker Compose, Docker Desktop для Mac уже включает в себя и клиент docker, и движок Docker Engine, и плагин docker compose, поэтому устанавливать Compose отдельно не нужно. Проверим связь с демоном и версию плагина.

Выполните в среде «Терминал macOS»:

docker version
docker compose version

Посмотрим на результат выполнения первой команды. В отличие от короткого флага docker --version, который показывает только номер версии клиента, команда docker version опрашивает и клиентскую часть, и фоновый сервер:

• В выводе должны присутствовать два раздела: Client: и Server: Docker Desktop, без сообщений об ошибках подключения.
• В результате второй команды терминал должен показать версию плагина Docker Compose version v2... (или новее).

Даже если блок Server отобразился, полезно убедиться, что ваш клиент Docker общается именно с локальным Docker Desktop, а не со старым сторонним движком или удалённым сервером, если вы когда-то настраивали Docker на этом компьютере раньше. Проверим список контекстов с помощью команды docker context ls.

Выполните в среде «Терминал macOS»:

docker context ls

Текущий активный контекст отмечен звёздочкой (*) в колонке NAME. При работе через Docker Desktop для Mac активным должен быть контекст desktop-linux (или default, если в его колонке DOCKER ENDPOINT указан сокет внутри вашего домашнего каталога .docker/run/docker.sock, а описание указывает на Docker Desktop). Если звёздочка стоит напротив другого окружения (например, другого локального рантайма или удалённого хоста), не переключайте контекст и не сбрасывайте переменные окружения вслепую: сначала проверьте, не запущены ли в том окружении нужные вам контейнеры, и только затем переключитесь на локальный Docker Desktop, когда будете уверены, что это не затронет текущую работу.

Что делать, если Терминал пишет command not found: docker:

1. Если окно Терминала было открыто ещё до установки Docker Desktop, просто закройте его и откройте новое окно Терминала, чтобы оболочка перечитала обновлённые настройки PATH.
2. Если в новом окне команда по-прежнему не находится, откройте окно Docker Desktop, перейдите в настройки (Settings → Advanced) и проверьте, как настроена установка инструментов CLI (в пользовательский каталог ~/.docker/bin или в системный /usr/local/bin).
3. Если файлы в каталоге ~/.docker/bin уже созданы, но ваша текущая сессия оболочки их не видит, вы можете временно добавить эту папку в PATH для текущего окна Терминала.

Для такой временной проверки выполните в среде «Терминал macOS»:

export PATH="$HOME/.docker/bin:$PATH"

Эта команда действует только до закрытия текущего окна Терминала и позволяет сразу проверить docker version, если бинарные файлы уже лежат в ~/.docker/bin. Устанавливать второй экземпляр Docker через пакетные менеджеры или запускать его через sudo при этом не нужно.

Проверим OpenSSL для будущей генерации ключа

На следующем этапе курса, когда мы перейдём к запуску Open WebUI, нам понадобится сгенерировать случайный секретный ключ WEBUI_SECRET_KEY для защиты пользовательских сессий с помощью команды openssl rand -hex 32. Сам ключ создадим при новой установке Open WebUI; при обновлении сохраняют прежний ключ. Сейчас проверим, доступна ли утилита openssl в вашей системе.

Обычно в macOS уже предустановлена системная утилита openssl (часто на базе библиотеки LibreSSL). Для нашей задачи не имеет значения, используется ли в системе штатная сборка LibreSSL от Apple или OpenSSL 3: главное, чтобы команда откликалась и поддерживала генерацию случайной строки openssl rand -hex 32.

Проверим наличие и версию утилиты openssl version. Выполните в среде «Терминал macOS»:

openssl version

Если в ответ терминал вывел строку с версией (например, LibreSSL ... или OpenSSL ...), дополнительная установка не нужна. Можно переходить к папке проекта.

Если команда openssl не найдена

Только в том редком случае, если терминал сообщил об отсутствии команды (command not found: openssl), её можно установить через менеджер пакетов Homebrew. Сначала проверим, установлен ли сам Homebrew на вашем Mac.

Выполните в среде «Терминал macOS» (только если openssl отсутствует):

brew --version

Если команда вернула версию Homebrew ..., менеджер пакетов уже есть. Если команда brew не найдена, сначала откроем новое окно Терминала. Если Homebrew уже устанавливался, проверим его настройку PATH, вместо повторной установки. Установить отсутствующий Homebrew поможет официальная инструкция Homebrew (на этой же странице перечислены стандартные требования к системе и средствам командной строки Xcode, которые установщик при необходимости предложит загрузить автоматически).

Для установки Homebrew в случае его отсутствия выполните в среде «Терминал macOS»:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Никогда не запускайте установщик Homebrew через sudo. Скрипт сам объяснит, какие каталоги он собирается создать (/opt/homebrew на компьютерах с Apple Silicon или /usr/local на Mac с процессором Intel), и при необходимости попросит ввести пароль вашей учётной записи. Когда установка завершится, внимательно найдём в конце вывода раздел ==> Next steps:. Поскольку пути на Apple Silicon и Intel различаются, выполните именно те команды из блока Next steps, которые установщик вывел для вашей архитектуры, чтобы добавить brew в PATH.

Когда команда brew доступна, установим пакет openssl@3 и подключим его в текущем окне терминала, используя автоматическое определение пути $(brew --prefix openssl@3), которое одинаково корректно работает и на Apple Silicon, и на Intel.

Выполните в среде «Терминал macOS» (только если системный openssl отсутствовал):

brew install openssl@3
export PATH="$(brew --prefix openssl@3)/bin:$PATH"
openssl version

Первая команда скачает и установит пакет, вторая добавит папку с исполняемым файлом в переменную PATH вашей текущей сессии терминала, а третья подтвердит, что утилита openssl теперь откликается и готова к работе.

Подготовим рабочую папку на Mac

Создадим в вашем домашнем каталоге macOS отдельную папку, в которой на следующем шаге курса мы будем хранить файлы конфигурации и ключ окружения проекта. Обратите внимание на разницу путей между операционными системами: в macOS домашний каталог пользователя (~) располагается по пути /Users/<имя_пользователя>, а не в /home/..., как в Linux и Ubuntu внутри WSL2.

Этот каталог находится прямо в файловой системе вашего Mac, а не внутри виртуальной машины Docker. Рабочая папка проекта предназначена для конфигурационных файлов (таких как compose.yaml и файл с секретным ключом), тогда как база данных и история чатов самого Open WebUI при стандартной контейнерной установке хранятся в отдельном именованном томе под управлением Docker.

Создадим общую папку projects (если её ещё нет), перейдём в неё и проверим полный путь. Выполните в среде «Терминал macOS»:

mkdir -p ~/projects && cd ~/projects
pwd

Команда pwd должна вывести путь вида /Users/<ваше_имя_пользователя>/projects. В следующем уроке при выборе варианта с Docker Compose мы создадим внутри этого каталога папку конкретного сервиса, а при выборе варианта с docker run сможем использовать эту же структуру для аккуратного хранения вспомогательных файлов.

В macOS очень удобно переходить из командной строки в графический интерфейс Finder. Чтобы открыть текущую папку Терминала в окне Finder, выполните в среде «Терминал macOS»:

open .

Точка (.) указывает на текущий рабочий каталог. После ввода команды на экране откроется окно Finder с папкой projects, где вы в любой момент сможете посмотреть или отредактировать файлы проекта в привычном текстовом редакторе.

Разберём частые заминки и проверим готовность к запуску

Если на каком-то из шагов проверка в Терминале дала сбой, не спешите переустанавливать систему, сбрасывать настройки Docker Desktop до заводских (Factory Reset) или запускать команды очистки данных вроде docker system prune. Сначала проверим доступность команды и связь с Docker Desktop. Сброс и очистка могут затронуть существующие проекты. Пройдёмся по основным симптомам:

• Команда docker version выводит блок Client, но вместо Server сообщает Cannot connect to the Docker daemon.... Клиентская утилита доступна, но не может связаться с выбранным сервером. Сначала проверим, запущен ли Docker Desktop и готов ли его движок. Откройте приложение Docker Desktop из папки «Программы» (Applications), дождитесь готовности движка и повторите команду docker version.
• Команда docker version показывает Server, но это не Docker Desktop, или команды ведут себя неожиданно. Выполните docker context ls и посмотрите, какой контекст отмечен звёздочкой *. Если раньше на компьютере устанавливались альтернативные среды запуска контейнеров или настраивалось подключение к внешнему серверу, клиент может обращаться к ним. Убедитесь, что Docker Desktop запущен и в выводе присутствует контекст desktop-linux.
• В новом окне Терминала пропадает доступ к командам docker или установленному через Homebrew openssl. Команда export PATH=..., введённая вручную в окно Терминала, действует только внутри текущей сессии. Для Docker убедитесь, что приложение Docker Desktop было запущено и завершило начальную настройку путей в ~/.docker/bin. Для Homebrew проверим команды из Next steps: они делают доступной саму команду brew. Если OpenSSL установлен через Homebrew и мы открыли новый Терминал, ещё раз выполним строку export PATH="$(brew --prefix openssl@3)/bin:$PATH" из раздела установки OpenSSL. Она добавляет именно OpenSSL в текущую сессию.

Сверим результаты подготовки. Основная подготовка для следующего шага завершена, если одновременно выполняются четыре условия:

1. Приложение Docker Desktop запущено на Mac, и вы ознакомились с его лицензионным соглашением и приняли его.
2. Команды docker version и docker compose version в штатном Терминале macOS возвращают версии клиента, плагина Compose и работающего сервера Docker Desktop (в контексте локального Docker Desktop) без ошибок соединения.
3. Команда openssl version возвращает номер версии установленной утилиты (штатной системной или установленной через Homebrew).
4. В домашнем каталоге пользователя создан и проверен рабочий каталог ~/projects (/Users/<имя_пользователя>/projects).

Теперь перейдём к установке Open WebUI через Docker Compose. В начале этого урока выберем macOS и продолжим работу в том же Терминале: сохраним конфигурацию, создадим постоянный ключ и откроем интерфейс в браузере на Mac. Повторять подготовку Windows или Linux не требуется.