Часті питання щодо інтеграції ServBay і Docker (FAQ)

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

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

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

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

Механізм роботи:

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

Чи можна це зупинити?

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

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

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

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

Неправильний варіант: використовувати host.docker.internal як hostname у URL для доступу до сайту ServBay

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

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

Правильний варіант: додати записи у /etc/hosts контейнера через extra_hosts

Щоб Docker-застосунки всередині контейнера могли надсилати запити по оригінальному домену сайту (наприклад, mysite.servbay.demo) із правильним заголовком Host, слід додати у /etc/hosts контейнера відповідний запис, що направить цей домен на IP-адресу хоста. Зробити це можна через extra_hosts (у docker-compose.yml) або опцію --add-host (у команді docker run). Для IP рекомендується використовувати 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, домен резолвиться до IP хоста.
Запит проходить на веб-сервер ServBay на хості.
Заголовок HTTP Host буде коректним (mysite.servbay.demo), тому ServBay зможе правильно обробити запит і видати вірний SSL-сертифікат при HTTPS.

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

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

Порядок дій:

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

Приклад (підключення до MySQL у ServBay): Припустімо, MySQL працює на порті 3306. У контейнері використовуйте наступне:

host: host.docker.internal
port: 3306
user: your_db_user
password: your_db_password

Q4: Контейнер Docker при доступі по HTTPS до сайту в ServBay (із Extra_hosts) і власним CA: як змусити контейнер довіряти цьому CA?

Припустимо, ви зробили відповідні налаштування, і домен secure.servbay.demo у контейнері резолвиться на хост. Якщо сайт використовує сертифікат від ServBay User CA, Docker-контейнер за замовчуванням не довіряє цьому CA, у результаті чого виникають помилки SSL.

Шляхи до ServBay CA:

Сертифікат кореня ServBay User CA:
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
PEM-файл із ServBay User CA, Public CA та коренями Mozilla:
- macOS (ARM): /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- macOS (Intel): /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
- Windows: C:\ServBay\package\common\openssl\3.3\cacert.pem

Рішення:

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

Метод 1: Додати CA на етапі збірки образу (Dockerfile) — оптимально, якщо потрібна системна довіра і є можливість редагувати Dockerfile.
Метод 2: Локальна довіра на рівні застосунку (volume+env) — підходить для окремих застосунків або якщо не бажаєте змінювати образ.
Метод 3: Системна довіра на етапі запуску (volume+custom command) — корисно, якщо немає можливості редагувати образ, але потрібна довіра для всього контейнера.

Метод 1: Додавання CA на етапі збірки образу (Dockerfile)

CA додається до системного trust store на етапі збірки образу.

Підготуйте файл CA: Скопіюйте кореневий сертифікат ServBay User CA до каталогу з Dockerfile:
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\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/*

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:

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # тут розташовано Dockerfile та ServBay-Private-CA-ECC-Root.crt
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Метод 2: Довіра до CA лише для застосунку (volume+env)

CA підключається через volume, а застосунок підключає CA через змінні середовища.

Приклад у docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Windows (адаптуйте під свою ОС)
      # - C:\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:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Потрібно уточнити в документації вашого застосунку, яку змінну середовища використати.

Метод 3: Довіра до CA на системному рівні при запуску (volume+custom command)

CA підключається через volume, а команда запуску оновлює системний trust store. В цьому випадку не треба ребілдити образ, але запуск може ускладнитися.

Приклад у docker-compose.yml (Debian/Ubuntu):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # або інший з update-ca-certificates
    volumes:
      # macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Windows (змінити під свою ОС)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # заміна команди для оновлення CA і запуску програми
    command: >
      sh -c "
        echo 'Оновлення сертифікатів CA...' &&
        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 сертифікати оновлено.'
        else
          echo 'Команда update-ca-certificates не знайдена, пропуск оновлення CA.'
        fi &&
        echo 'Запуск програми...' &&
        exec your_original_application_command_here # замінить на вашу команду запуску
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Якщо потрібні root-права для update-ca-certificates, але сама програма працює не під root — потрібен складніший entrypoint.
    # user: root # тимчасово запускати як root, або у entrypoint надати права

Зверніть увагу:

Складність: Перезапис команди або entrypoint може ускладнити запуск особливо для офіційних образів із нетривіальним запуском.
Права: update-ca-certificates зазвичай потребує root. Якщо дефолтний користувач не root — потрібна ескалація прав.
Додаткові залежності: В контейнері мають бути ca-certificates та update-ca-certificates. Приклад встановлює їх, якщо система на apt.
Час запуску: При кожному старті контейнера ця перевірка і оновлення трохи збільшують час запуску.
Alpine Linux: Для Alpine треба запускати apk add --no-cache ca-certificates && update-ca-certificates.

Який метод обрати?

Якщо можете редагувати Dockerfile і потрібно системну довіру — метод 1.
Якщо не хочете модифікувати образ, а потрібна довіра тільки всередині застосунку — метод 2.
Якщо не треба модифікувати образ, але потрібна системна довіра — метод 3.

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

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

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

Інструкція:

Запустити Docker-контейнер із пробросом порту на хост 127.0.0.1: Переконайтеся, що порт контейнера відображений на IP 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. SSL-термінація відбувається на боці ServBay, а запит до контейнера йде звичайним HTTP (http://127.0.0.1:3001).
Перевірити доступ: Після налаштування відкривайте у браузері http://myapp.servbay.demo чи https://myapp.servbay.demo (якщо SSL є). ServBay проксіює запит на Docker-контейнер.

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

Висновок

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

Для доступу до сайтів ServBay із контейнера Docker використовуйте додавання домену через extra_hosts або --add-host із IP host-gateway — це гарантує правильний заголовок Host і уникнення SNI-проблем.
Для підключення з Docker-контейнера до бази даних чи інших сервісів без SNI використовуйте host.docker.internal як hostname — це просто і ефективно.
Щоб контейнер довіряв SSL-сертифікатам ServBay User CA, додайте CA у образ або використовуйте volumee та змінні середовища.
Щоб налаштувати зворотний проксі від ServBay до застосунку у контейнері, створіть сайт із типом "Зворотний проксі" і направте на локальний порт, проброшений із контейнера.

Завжди переконайтеся, що відповідні пакети в ServBay (web-сервер, база даних тощо) і ваш Docker-контейнер правильно налаштовано та запущено.

Часті питання щодо інтеграції ServBay і Docker (FAQ) ​

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

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

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

Q4: Контейнер Docker при доступі по HTTPS до сайту в ServBay (із Extra_hosts) і власним CA: як змусити контейнер довіряти цьому CA? ​

Метод 1: Додавання CA на етапі збірки образу (Dockerfile) ​

Метод 2: Довіра до CA лише для застосунку (volume+env) ​

Метод 3: Довіра до CA на системному рівні при запуску (volume+custom command) ​

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

Висновок ​

Часті питання щодо інтеграції ServBay і Docker (FAQ)

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

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

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

Q4: Контейнер Docker при доступі по HTTPS до сайту в ServBay (із Extra_hosts) і власним CA: як змусити контейнер довіряти цьому CA?

Метод 1: Додавання CA на етапі збірки образу (Dockerfile)

Метод 2: Довіра до CA лише для застосунку (volume+env)

Метод 3: Довіра до CA на системному рівні при запуску (volume+custom command)

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

Висновок