Часті питання щодо спільної роботи ServBay і Docker (FAQ)

Під час локальної Web-розробки за допомогою ServBay ви можете бажати використовувати його разом із Docker для роботи у контейнеризованому середовищі. Цей розділ FAQ дає відповіді на типові питання, які виникають під час взаємодії ServBay та Docker на macOS, включно з питаннями доступу до сайтів і сервісів ServBay із контейнера Docker, а також використання ServBay як зворотного проксі для застосунків у Docker.

Q1: Чому ServBay змінює мій системний файл `hosts`? Чи можна це вимкнути?

ServBay додає записи у ваш системний файл hosts (наприклад, mysite.servbay.demo 127.0.0.1), щоб ви могли зручно користуватись власними локальними доменами (наприклад, mysite.servbay.demo) для доступу до веб-сайтів, які працюють у вас на комп’ютері за адресою 127.0.0.1.

Однак через механіку роботи Docker, котрий зчитує hosts-файл із macOS-хоста, запис mysite.servbay.demo теж вказує на 127.0.0.1 у контейнері, і Docker-аплікація може звертатись не до хоста, а до самої себе.

Суть питання:

Коли ви створюєте новий сайт у ServBay із певним доменом (наприклад, example.servbay.demo), ServBay автоматично направляє цей домен на адресу 127.0.0.1.
Це є типовим підходом для роботи з дружніми доменами на локальному сервері. Без змін у hosts-файлі доступ буде лише через адресу на кшталт http://127.0.0.1:PORT, а не через зручний домен.

Чи можна це вимкнути?

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

Для більшості локальних сценаріїв розробки автоматичне керування файлом hosts — це очікувана й потрібна поведінка, яка значно спрощує роботу розробника.

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

Це дуже поширене питання, яке потребує коректного підходу, щоб уникнути помилок. Коли ServBay керує сайтом на вашому macOS (наприклад, mysite.servbay.demo та направляє його на 127.0.0.1), то всередині Docker-контейнера адреса 127.0.0.1 буде означати сам контейнер, а не хост.

Помилковий шлях: напряму використовувати host.docker.internal у рядку URL для звернення до сайта ServBay

Docker Desktop для Mac (та Windows) надає спеціальне ім'я DNS host.docker.internal, що дозволяє контейнеру звертатись до IP-адреси хоста. Але дуже не рекомендується напряму підставляти це ім’я в URL при доступі до сайтів ServBay (наприклад, не варто очікувати, що http://host.docker.internal/ автоматично потрапить на ваш локальний домен mysite.servbay.demo).

Причина: коли ви так робите, у запиті до сервера ServBay (Caddy або Nginx) в полі HTTP-заголовка Host буде міститись host.docker.internal. Сервер ServBay (як і переважна більшість веб-серверів) ідентифікує сайти саме за цим хедером. Якщо в заголовку Host міститься не mysite.servbay.demo, а інше ім’я (наприклад, host.docker.internal), він не зможе маршрутизувати ваш запит до потрібного сайту. У випадку HTTPS така помилка також викличе SNI (Server Name Indication) помилку, оскільки SSL-сертифікат виданий для mysite.servbay.demo, а не для host.docker.internal.

Правильне рішення: додати extra_hosts при старті Docker-контейнера

Щоб аплікації у контейнері могли використовувати оригінальний домен сайта ServBay (наприклад, mysite.servbay.demo) і коректно відправляти HTTP-запити з правильним заголовком 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-адресу хоста.
Запит потрапить на той самий веб-сервер ServBay, який працює на вашому Mac.
Поле HTTP Host буде дорівнювати домену mysite.servbay.demo, тому ServBay зможе правильно віддати відповідний сайт і SSL-сертифікат (у разі HTTPS).

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

На відміну від веб-доменів, для підключення до бази даних чи іншого TCP-сервісу, який не залежить від SNI, рекомендовано і цілком коректно використовувати ім’я хоста host.docker.internal.

Алгоритм підключення:

Переконайтеся, що база даних (або інший сервіс) у ServBay запущений і дозволяє підключення із хоста (для локального розвитку стандартна конфігурація це підтримує).
У ваших налаштуваннях усередині контейнера пропишіть підключення:
- Host: host.docker.internal
- Port: той, що використовується ServBay (наприклад, MySQL — 3306, PostgreSQL — 5432)
- Username/Password: ваші облікові дані з налаштувань бази у ServBay.

Приклад для MySQL: Якщо MySQL у ServBay працює на стандартному порту 3306, то ваші налаштування або строка підключення повинна містити:

Хост: host.docker.internal
Порт: 3306
Користувач: your_db_user
Пароль: your_db_password

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

Якщо ви вже використовуєте рекомендації з Q2 — наприклад, прописали у Docker-контейнері, що secure.servbay.demo вказує на host-gateway, і цей сайт у ServBay має SSL-сертифікат, виданий ServBay User CA, то, як правило, контейнер не довіряє такій CA за замовченням, та SSL-з’єднання не встановиться.

Де знайти файли CA на Mac (хості):

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

Загальний огляд шляхів вирішення:

Є кілька способів змусити контейнер довіряти кастомній CA:

Спосіб 1: Додати CA під час побудови Docker-образу (Dockerfile) — оптимально, якщо ви контролюєте побудову образу.
Спосіб 2: Довіряти CA на рівні окремої аплікації через змонтований том та змінну середовища — якщо лише конкретна аплікація потребує довіри й не хочеться оновлювати образ.
Спосіб 3: Оновити довіру до CA на системному рівні під час запуску контейнера, без зміни образу — найбільш універсальний варіант, якщо потрібна системна довіра.

Спосіб 1: Додати CA під час побудови Docker-образу (Dockerfile)

Під час створення Docker-образу CA-сертифікат копіюється до системного трестстору образу.

Скопіюйте кореневий CA-файл у робочу папку з Dockerfile.

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/*

Dockerfile для 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

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # каталог має містити Dockerfile та CA-сертифікат
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Спосіб 2: Довіряти CA лише певній аплікації (на рівні програми)

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=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Переконайтеся, яку змінну потрібно використовувати саме для вашої програми.

Спосіб 3: Оновлення списку довірених CA на системному рівні контейнера під час запуску

Об’єднує монтування CA-сертифікату і запуск оновлення довіри через кастомну команду.

Приклад docker-compose.yml (базується на Ubuntu/Debian):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # або інший, який підтримує update-ca-certificates
    volumes:
      # Мапимо локальний CA-файл
      - /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"]
    # Щоб виконати update-ca-certificates, потрібно мати root-права у контейнері

Зауваження:

Командний рядок: Якщо образ запускатиме складну аплікацію, інколи потрібно скоригувати entrypoint.
Права: Зазвичай потрібні root-права для update-ca-certificates.
Пакети: Має бути встановлено ca-certificates і відповідна утиліта.
Alpine: Замість цього використовуйте apk add --no-cache ca-certificates && update-ca-certificates.

Який спосіб обрати?

Якщо ви будуєте власний образ і потрібна системна довіра — спосіб 1.
Якщо потрібна довіра лише для однієї програми — спосіб 2.
Якщо не хочете змінювати Dockerfile — спосіб 3.

Для сайтів із сертифікатами від загально відомих CA (наприклад, Let's Encrypt): Якщо сайт у ServBay має сертифікат, виданий через ACME (наприклад, Let's Encrypt), у більшості випадків базові Docker-образи вже довіряють таким CA і нічого додаткового робити не потрібно.

Q5: Як налаштувати у ServBay домен та зворотний проксі для застосунку в Docker-контейнері?

Припустимо, ви запускаєте у Docker-контейнері застосунок (наприклад, Node.js, котрий слухає порт 3000 усередині контейнера) і хочете надати йому зручний домен (myapp.servbay.demo) для доступу з браузера, користуючись тим самим SSL-менеджментом ServBay.

Послідовність дій:

Запустіть Docker-контейнер із пробросом порта на локальний інтерфейс 127.0.0.1: Переконайтеся, що порт контейнера відображено на локальну адресу Mac, щоб уникати відкриття порта для всієї мережі.
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.
- Тип сайту: обирайте “Reverse Proxy”.
- IP-адреса: вкажіть 127.0.0.1.
- Порт: порт, на який проброшено Docker-контейнер (наприклад, 3001).
- Натисніть “Зберегти” або “Додати”.
(Опційно) Налаштуйте SSL: Після додавання сайту увімкніть SSL у його налаштуваннях. ServBay може автоматично отримувати сертифікати від Let's Encrypt (ACME), або використовувати ServBay User/Public CA. Усі SSL-запити будуть оброблятися саме ServBay як проксі, а з’єднання від ServBay до вашої аплікації всередині Docker може залишатися незашифрованим (HTTP).
Перевірте роботу: Після налаштувань ви зможете відкрити http://myapp.servbay.demo або https://myapp.servbay.demo (якщо увімкнуте SSL) у вашому браузері. ServBay буде виступати у ролі зворотного проксі для застосунку у контейнері.

Типова схема роботи: Браузер користувача -> https://myapp.servbay.demo -> ServBay (обробляє SSL, проксірує) -> http://127.0.0.1:3001 (локальний порт Mac) -> застосунок Docker.

Підсумок

ServBay значно спрощує локальну web-розробку на macOS. При роботі у комбінації з Docker:

Для доступу до сайтів ServBay із Docker-контейнера використовуйте extra_hosts або --add-host для прив’язки домену до host-gateway, що гарантує правильний заголовок Host і уникнення SNI-проблем.
Для доступу до бази даних чи інших TCP-сервісів використовуйте host.docker.internal як hostname.
Якщо контейнеру потрібно довіряти власній CA ServBay (SSL) — потрібно доставити CA в контейнер і додати її до списку довірених.
Для публікації Docker-застосунків із використанням домену та SSL через ServBay додавайте сайт як “Reverse Proxy”, перенаправляючи на локальний порт Mac.

Усі необхідні пакети у ServBay (веб-сервери, БД тощо) та Docker-контейнери мають бути належно налаштовані і запущені.

Часті питання щодо спільної роботи ServBay і Docker (FAQ) ​

Q1: Чому ServBay змінює мій системний файл hosts? Чи можна це вимкнути? ​

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

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

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

Спосіб 1: Додати CA під час побудови Docker-образу (Dockerfile) ​

Спосіб 2: Довіряти CA лише певній аплікації (на рівні програми) ​

Спосіб 3: Оновлення списку довірених CA на системному рівні контейнера під час запуску ​

Q5: Як налаштувати у ServBay домен та зворотний проксі для застосунку в Docker-контейнері? ​

Підсумок ​

Часті питання щодо спільної роботи ServBay і Docker (FAQ)

Q1: Чому ServBay змінює мій системний файл `hosts`? Чи можна це вимкнути?

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

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

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

Спосіб 1: Додати CA під час побудови Docker-образу (Dockerfile)

Спосіб 2: Довіряти CA лише певній аплікації (на рівні програми)

Спосіб 3: Оновлення списку довірених CA на системному рівні контейнера під час запуску

Q5: Як налаштувати у ServBay домен та зворотний проксі для застосунку в Docker-контейнері?

Підсумок