Часто задаваемые вопросы о совместной работе ServBay и Docker (FAQ)

При локальной веб-разработке с помощью ServBay вы можете захотеть использовать контейнеризированную среду с Docker. Этот FAQ поможет решить типовые вопросы при совместном использовании ServBay и Docker, особенно в macOS: от доступа к сервисам ServBay из Docker-контейнеров до настройки обратного проксирования через ServBay для приложений в контейнерах.

Q1: Почему ServBay изменяет системный файл `hosts`? Можно ли этого избежать?

ServBay добавляет записи в системный файл hosts (например, mysite.servbay.demo 127.0.0.1), чтобы вы могли открывать ваши сайты локальной разработки по удобным кастомным доменам (например, mysite.servbay.demo). Эти сайты на самом деле запускаются на 127.0.0.1 на вашем Mac.

Однако из-за особенностей Docker, контейнеры могут считывать ваш hosts-файл из macOS, из-за чего mysite.servbay.demo будет разрешаться в 127.0.0.1, но в этом случае это будет адрес самого контейнера, а не хоста. В итоге из контейнера запрос попадёт не туда.

Ключевой механизм:

Когда вы создаёте новый сайт в ServBay и задаёте для него домен (например, example.servbay.demo), система автоматически прописывает привязку этого домена к 127.0.0.1.
Это стандартный способ предоставить локальный и привычный адрес для разработки. Без изменения файла hosts вы могли бы обращаться только по http://127.0.0.1:PORT, а не по своему домену.

Можно ли это запретить?

Теоретически вы можете вручную удалить записи, добавленные ServBay, но тогда вы не сможете открывать ваши сайты по доменам, которые настраивает ServBay — что противоречит идеологии удобной локальной разработки. Одна из ключевых функций ServBay — сделать создание и доступ к сайтам максимально простым. Если вы не хотите, чтобы ServBay управлял определённым доменом в hosts, просто не создавайте для него сайт в интерфейсе ServBay.

Для большинства сценариев локальной разработки автоматическое управление hosts-файлом со стороны ServBay — ожидаемое поведение, значительно упрощающее процесс разработки.

Q2: Как Docker-контейнеру правильно получить доступ к сайту, управляемому ServBay на macOS (например, `mysite.servbay.demo`) по домену?

Это популярный кейс, требующий правильных настроек. На macOS сайт под управлением ServBay (например, mysite.servbay.demo) работает и резолвится на хосте в 127.0.0.1. Однако внутри Docker-контейнера адрес 127.0.0.1 — это уже сам контейнер, а не ваш Mac.

Ошибочное решение: обращаться в ServBay через URL с host.docker.internal

Хотя Docker Desktop для Mac (и Windows) даёт специальное имя host.docker.internal, которое из контейнера указывает на хостовую машину, настоятельно не рекомендуется использовать его напрямую в URL для доступа к ServBay-сайтам (например, подключаться по http://host.docker.internal/ и ожидать, что так работает домен mysite.servbay.demo).

Причина в том, что в таком запросе HTTP Host-заголовок будет host.docker.internal, а ServBay (будь то Caddy или Nginx) идентифицирует сайт именно по заголовку Host. Если Host — это не mysite.servbay.demo, а host.docker.internal, сервак не сможет правильно сопоставить сайт или, при HTTPS, возникнет ошибка SNI (Server Name Indication), потому что SSL-сертификат выдан для домена mysite.servbay.demo, а не для host.docker.internal.

Правильное решение: использовать extra_hosts при запуске контейнера

Чтобы приложения внутри контейнера могли корректно обращаться к сайту ServBay по исходному домену и отправлять правильный Host-заголовок, домен следует добавить в /etc/hosts контейнера и указать, что он резолвится в адрес хоста. Это делается через опцию extra_hosts (в docker-compose.yml) или через --add-host при docker run, направляя домен либо на host.docker.internal, либо (лучше) на host-gateway.

Вариант с docker run:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway — специальное значение, которое docker сам заменит на внутренний IP-адрес хоста. В Docker 20.10+ это более надёжно и низкоуровнево, чем host.docker.internal.)

Вариант с docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # либо "mysite.servbay.demo:host.docker.internal"
    # ... другие настройки

В итоге:

Приложение в контейнере обращается к http://mysite.servbay.demo или https://mysite.servbay.demo.
Внутри контейнера /etc/hosts резолвит домен в IP хоста.
В HTTP-заголовке Host передаётся корректное имя mysite.servbay.demo, что позволяет ServBay правильно определить сайт и выдать нужный SSL-сертификат.

Q3: Как контейнеру Docker подключиться к базе данных (MySQL, PostgreSQL) или другому не-HTTP сервису под управлением ServBay?

В отличие от доступа к сайтам, для подключения к базе данных или иному TCP-сервису, который не использует SNI, рекомендуется использовать host.docker.internal в качестве имени сервера.

Шаги:

Убедитесь, что нужный сервис (например, MySQL или PostgreSQL) в ServBay запущен и сконфигурирован так, чтобы разрешать локальные подключения (по умолчанию это обычно так).
В контейнере Docker, прописывайте следующие параметры соединения:
- Hostname/Server: host.docker.internal
- Порт: тот, что настроен в ServBay (обычно MySQL — 3306, PostgreSQL — 5432)
- Имя пользователя и пароль: ваши креды из настроек ServBay
Пример (подключение к MySQL ServBay):
- Хост: host.docker.internal
- Порт: 3306
- User: your_db_user
- Пароль: your_db_password

Q4: Как Docker-контейнеру доверять пользоватeльскому CA-сертификату ServBay (User CA) при доступе через домен (с помощью extra_hosts) по HTTPS?

Если вы настроили extra_hosts/--add-host так, чтобы, например, secure.servbay.demo резолвился через host-gateway, а SSL-сертификат на этом сайте выдан вашим ServBay User CA, то по умолчанию Docker-контейнер не будет ему доверять — и соединения по HTTPS дадут ошибку handshake.

Где искать CA-файлы на Mac:

Корневой сертификат ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
PEM-файл со всеми корнями (User CA, Public CA, Mozilla):
- Для ARM Mac: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- Для Intel Mac: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Способы решения:

Вариант 1: Раздача CA на уровне системы при построении образа (Dockerfile) — рекомендовано для случаев, когда вы контролируете билд образа.
Вариант 2: Доверие на уровне приложения при запуске (volume + переменные окружения) — для отдельных приложений или когда не хотите пересобирать образ.
Вариант 3: Доверие на уровне системы при запуске контейнера (volume + собственная startup-команда) — если нужен system-wide trust, но не хотите билдить новый образ.

Вариант 1: Доверие на этапе сборки контейнера (через Dockerfile)

В этом варианте CA-файл помещается в доверенное хранилище при билде контейнера.

Подготовьте CA-файл: скопируйте /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt в директорию сборки рядом с Dockerfile.

Для Debian/Ubuntu:

dockerfile

# Dockerfile
FROM ubuntu:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
    update-ca-certificates && \
    rm -rf /var/lib/apt/lists/*

Для Alpine:

dockerfile

# Dockerfile
FROM alpine:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apk add --no-cache ca-certificates && update-ca-certificates

docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # папка с Dockerfile и CA-файлом
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Вариант 2: Доверие на уровне приложения (volume + переменные окружения)

Здесь вы монтируете сертификат в контейнер и указываете переменной окружения, чтобы конкретное приложение доверяло этому CA.

Пример docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Для Node.js:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Для Python (requests):
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Для универсальной переменной SSL_CERT_FILE:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Проверяйте документацию вашего приложения для точных переменных окружения.

Вариант 3: Доверие на системном уровне при запуске контейнера (volume + startup-команда)

Тут сертификат монтируется, и update-ca-certificates запускается при старте, после чего запускается нужное приложение.

Пример docker-compose.yml (для образов Debian/Ubuntu):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest
    volumes:
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    command: >
      sh -c "
        echo 'Attempting to update CA certificates...' &&
        if command -v update-ca-certificates > /dev/null; then
          if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
          update-ca-certificates &&
          echo 'CA certificates updated.'
        else
          echo 'update-ca-certificates command not found, skipping CA update.'
        fi &&
        echo 'Starting application...' &&
        exec your_original_application_command_here
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Если нужно запускать от root — добавьте user: root

Важные нюансы:

Сложность: если старт вашего приложения сложный, возможно, потребуется отдельный entrypoint-скрипт.
Права: update-ca-certificates требует root-доступа.
Зависимости: Требуется установленный пакет ca-certificates и сама утилита.
Задержка запуска: при старте будет небольшая задержка из-за обновления сертификатов.
Для Alpine: используйте аналогичную команду, подставив apk add --no-cache ca-certificates && update-ca-certificates.

Какой способ выбрать:

Если можете билдить образ и нужно system-wide доверие ко всем приложениям — используйте Вариант 1.
Если не хотите менять образ и нужен trust только для одного приложения — Вариант 2.
Если не планируете билдить образ, но нужен системный trust — Вариант 3.

Если используется публичный CA (например, Let's Encrypt): Если сайт ServBay использует сертификат публичного CA (ACME/Let's Encrypt), то почти все Docker-образы уже по умолчанию доверяют этим CA. Никаких особых действий обычно не требуется.

Q5: Как настроить домен и обратный прокси ServBay для приложения в Docker-контейнере?

Допустим, ваше приложение (например, Node.js-сервис) работает в контейнере на порту 3000 и вы хотите, чтобы оно было доступно по красивому домену (например, myapp.servbay.demo) через браузер на хосте, с SSL-сертификатом, управляемым ServBay.

Что делать:

Запустите контейнер с пробросом порта на 127.0.0.1 хоста: Важно пробросить нужный порт с привязкой к 127.0.0.1, чтобы сервис доступен был только локально и не светился наружу.
bash
```
# Пример: контейнер слушает 3000, порт проброшен на 127.0.0.1:3001 хоста
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Теперь приложение из контейнера можно открыть через http://127.0.0.1:3001.
Добавьте новый сайт в ServBay, настроив обратный прокси:
- Откройте панель управления ServBay.
- Нажмите "Добавить сайт".
- Домен: введите желаемое имя, например myapp.servbay.demo.
- Тип сайта: в выпадающем списке выберите "Обратный прокси".
- IP-адрес: укажите 127.0.0.1.
- Порт: напишите порт, проброшенный на хост (например, 3001).
- Сохраните изменения.
(Опционально) Включите SSL: После добавления сайта зайдите в его настройки и активируйте SSL. ServBay может автоматически получать сертификаты Let’s Encrypt (или других CA через ACME), либо использовать ваш собственный User CA/Public CA. SSL завершается на уровне ServBay, а трафик от ServBay до контейнера может идти по обычному HTTP (http://127.0.0.1:3001).
Проверьте доступность: После настройки вы сможете открыть http://myapp.servbay.demo или https://myapp.servbay.demo (если включен SSL) в браузере. ServBay будет проксировать ваши запросы в приложение внутри контейнера.

Сценарий работы: Браузер пользователя ⟶ https://myapp.servbay.demo ⟶ ServBay (SSL-терминация, определение правил прокси) ⟶ http://127.0.0.1:3001 (локальный порт хоста) ⟶ приложение в Docker-контейнере.

Резюме

ServBay значительно облегчает локальную разработку веб-проектов на macOS. При использовании с Docker:

Для доступа к сайтам ServBay из контейнеров, используйте extra_hosts или --add-host для направления домена на host-gateway и сохранения правильного Host-заголовка (во избежание SNI-проблем).
Для доступа к базам данных или другим non-HTTP сервисам на ServBay, используйте host.docker.internal в качестве имени сервера — это просто и надёжно.
Чтобы контейнер доверял User CA ServBay при HTTPS, скопируйте CA-сертификат в образ или настройте доверие через монтирование volume и update-ca-certificates.
Для обратного прокси с доменом через ServBay, выберите в веб-интерфейсе тип "Обратный прокси" и настройте проксирование на приватный порт, проброшенный на 127.0.0.1 хоста.

Всегда проверяйте, что нужные пакеты в ServBay (веб-сервер, база данных и др.) и ваши Docker-контейнеры корректно настроены и запущены.

Часто задаваемые вопросы о совместной работе ServBay и Docker (FAQ) ​

Q1: Почему ServBay изменяет системный файл hosts? Можно ли этого избежать? ​

Q2: Как Docker-контейнеру правильно получить доступ к сайту, управляемому ServBay на macOS (например, mysite.servbay.demo) по домену? ​

Q3: Как контейнеру Docker подключиться к базе данных (MySQL, PostgreSQL) или другому не-HTTP сервису под управлением ServBay? ​

Q4: Как Docker-контейнеру доверять пользоватeльскому CA-сертификату ServBay (User CA) при доступе через домен (с помощью extra_hosts) по HTTPS? ​

Вариант 1: Доверие на этапе сборки контейнера (через Dockerfile) ​

Вариант 2: Доверие на уровне приложения (volume + переменные окружения) ​

Вариант 3: Доверие на системном уровне при запуске контейнера (volume + startup-команда) ​

Q5: Как настроить домен и обратный прокси ServBay для приложения в Docker-контейнере? ​

Резюме ​

Часто задаваемые вопросы о совместной работе ServBay и Docker (FAQ)

Q1: Почему ServBay изменяет системный файл `hosts`? Можно ли этого избежать?

Q2: Как Docker-контейнеру правильно получить доступ к сайту, управляемому ServBay на macOS (например, `mysite.servbay.demo`) по домену?

Q3: Как контейнеру Docker подключиться к базе данных (MySQL, PostgreSQL) или другому не-HTTP сервису под управлением ServBay?

Q4: Как Docker-контейнеру доверять пользоватeльскому CA-сертификату ServBay (User CA) при доступе через домен (с помощью extra_hosts) по HTTPS?

Вариант 1: Доверие на этапе сборки контейнера (через Dockerfile)

Вариант 2: Доверие на уровне приложения (volume + переменные окружения)

Вариант 3: Доверие на системном уровне при запуске контейнера (volume + startup-команда)

Q5: Как настроить домен и обратный прокси ServBay для приложения в Docker-контейнере?

Резюме