FAQ Sobre Integração ServBay e Docker

Ao desenvolver aplicações web localmente com o ServBay, é comum utilizá-lo junto com Docker para criar ambientes containerizados. Este FAQ esclarece dúvidas frequentes sobre a integração entre ServBay e Docker, suportando macOS e Windows, incluindo acesso aos serviços ServBay via Docker e uso do proxy reverso do ServBay para aplicações rodando dentro de contêineres Docker.

Q1: Por que o ServBay modifica o arquivo `hosts` do meu sistema? Posso impedir isso?

O ServBay adiciona entradas no arquivo hosts do sistema (por exemplo, mysite.servbay.demo 127.0.0.1) para permitir que você acesse sites de desenvolvimento usando domínios personalizados (como mysite.servbay.demo). Esses sites estão realmente hospedados no endereço local 127.0.0.1.

No entanto, por causa do funcionamento do Docker, o arquivo hosts do sistema (macOS ou Windows) é lido dentro dos contêineres, fazendo com que mysite.servbay.demo seja resolvido para 127.0.0.1, direcionando o acesso do Docker para o próprio contêiner ao invés do serviço correto.

Como funciona:

Ao criar um novo site no ServBay e definir um domínio (ex: example.servbay.demo), o ServBay automaticamente aponta esse domínio para 127.0.0.1.
Esse tipo de configuração é comum para facilitar o acesso por domínios amigáveis durante o desenvolvimento. Caso o arquivo hosts não seja modificado, você só conseguiria acessar usando o formato http://127.0.0.1:PORT, sem o domínio personalizado.

É possível impedir?

Tecnicamente, você pode remover manualmente as entradas criadas pelo ServBay no arquivo hosts, mas isso impossibilita acesso por domínio personalizado, anulando o propósito de facilitar o desenvolvimento local. Um dos principais objetivos do ServBay é criar e acessar sites locais de forma simples. Se não deseja que o ServBay gerencie o domínio no arquivo hosts, evite criar sites com esse domínio no ServBay.

Para quase todos os casos de desenvolvimento local, o gerenciamento automático do arquivo hosts pelo ServBay é o comportamento ideal, pois simplifica muito o processo.

Q2: Como meu contêiner Docker pode acessar corretamente, por domínio, o site hospedado pelo ServBay na máquina host (por exemplo, `mysite.servbay.demo`)?

Essa necessidade é comum, mas precisa ser resolvida corretamente. Quando um site do ServBay está rodando na máquina host (macOS ou Windows) como mysite.servbay.demo (que resolve para 127.0.0.1), dentro do contêiner Docker o IP 127.0.0.1 refere-se ao próprio contêiner, não à máquina host.

Erro comum: Usar diretamente host.docker.internal como hostname na URL para acessar sites ServBay

Apesar do Docker Desktop para Mac (e Windows) fornecer o hostname especial host.docker.internal para acessar o IP da máquina host, não é recomendado utilizá-lo diretamente na URL para acessar sites ServBay (ex: acessar http://host.docker.internal/ esperando que resolva para mysite.servbay.demo).

Isso porque, ao fazer isso, o header HTTP Host enviado ao servidor web ServBay (como Caddy ou Nginx) será host.docker.internal em vez de mysite.servbay.demo. O servidor web ServBay depende desse header para roteamento ao site correto. Se o header for host.docker.internal e não mysite.servbay.demo, o servidor não irá rotear a requisição corretamente. Com HTTPS, isso provoca erro de SNI (Server Name Indication), pois o certificado fornecido é para mysite.servbay.demo, e não para host.docker.internal.

Solução correta: configurar extra_hosts ao iniciar o contêiner Docker

Para que aplicações dentro do Docker possam usar o domínio original ServBay (ex: mysite.servbay.demo) e enviem o header Host correto, é preciso adicionar esse domínio no /etc/hosts do contêiner, apontando para o IP da máquina host. Isso é feito com extra_hosts (no docker-compose.yml) ou com --add-host (usando docker run), apontando para host.docker.internal ou, preferencialmente, para host-gateway.

Usando docker run:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway é um valor especial; o Docker substitui pelo IP interno da máquina host. No Docker 20.10+, isso equivale a um alias mais baixo nível de host.docker.internal.)

Usando docker-compose.yml:

yaml

version: '3.8' # ou superior
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # ou "mysite.servbay.demo:host.docker.internal"
    # ... outras configurações

Depois de configurado, dentro do seu contêiner Docker:

Ao tentar acessar http://mysite.servbay.demo ou https://mysite.servbay.demo, o domínio será resolvido para o IP da máquina host.
O pedido é enviado ao servidor web ServBay que está rodando localmente.
O header HTTP Host será mysite.servbay.demo, permitindo o roteamento correto e servindo o certificado SSL válido (se estiver usando HTTPS).

Q3: Como o contêiner Docker pode se conectar ao banco de dados gerenciado pelo ServBay (ex: MySQL, PostgreSQL) ou a outros serviços não HTTP?

Diferente do acesso a serviços web por domínios, ao conectar bancos de dados ou outros serviços TCP que não usam SNI, usar host.docker.internal como hostname do servidor é recomendado e funciona bem.

Passos:

Certifique-se de que o banco de dados (ou outro serviço) está rodando no ServBay e configurado para aceitar conexões locais (normalmente a configuração padrão já é suficiente).
No contêiner Docker, configure a conexão (ex: banco de dados) usando:
- Hostname/Servidor: host.docker.internal
- Porta: Use a porta configurada no ServBay (ex: MySQL costuma ser 3306, PostgreSQL 5432)
- Usuário/Senha: Use as credenciais criadas no ServBay

Exemplo (MySQL no ServBay): Se o MySQL está rodando na porta padrão 3306, no aplicativo do contêiner:

Host: host.docker.internal
Porta: 3306
Usuário: your_db_user
Senha: your_db_password

Q4: Ao acessar sites HTTPS do ServBay por domínio (com configuração `extra_hosts`), como faço o contêiner Docker confiar na ServBay User CA?

Suponha que você já seguiu as dicas do Q2, configurando o domínio (ex: secure.servbay.demo) para apontar para host-gateway. Se esse domínio utiliza certificado SSL gerado pela ServBay User CA, por padrão o contêiner Docker não confia nessa CA, resultando em falha no handshake SSL.

Caminhos para os arquivos da CA do ServBay:

Root CA do 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
Arquivo PEM com ServBay User CA, Public CA e Mozilla CA:
- 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

Visão geral das soluções:

Há algumas formas de fazer o contêiner Docker confiar na ServBay User CA:

Opção 1: Confiança sistêmica no build (via Dockerfile) — para cenários onde é possível personalizar o build do container.
Opção 2: Confiança por aplicação em runtime (via volume e variáveis de ambiente) — para confiar na CA apenas para aplicações específicas, sem modificar a imagem.
Opção 3: Confiança sistêmica em runtime (via volume e comando customizado) — confiando no sistema inteiro durante execução, sem alterar a imagem.

Opção 1: Confiança sistêmica no build (Dockerfile)

Neste caso, o certificado da CA é integrado ao sistema do container durante o build da imagem.

Prepare o arquivo da CA: copie o root da ServBay User CA para o diretório contexto do Docker (junto com o Dockerfile):
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt

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

Exemplo de 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 com build:

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # diretório com Dockerfile + ServBay-Private-CA-ECC-Root.crt
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Opção 2: Confiança por aplicação em runtime (via volume e variáveis de ambiente)

O certificado é montado via volume e a aplicação é configurada para utilizá-lo via variável de ambiente.

Exemplo no docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # Exemplo para macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Exemplo para Windows (ajuste conforme o sistema)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Exemplo Node.js:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Exemplo Python (requests):
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Exemplo genérico SSL_CERT_FILE:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Consulte a documentação do seu aplicativo para a variável de ambiente correta.

Opção 3: Confiança sistêmica em runtime (via volume e comando customizado)

Combina montagem de volume com comando para atualizar certificados do sistema no início do container.

Exemplo no docker-compose.yml (imagem Debian/Ubuntu):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # Ou outra imagem que suporte update-ca-certificates
    volumes:
      # Monte o certificado no local esperado do sistema
      # Exemplo macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Exemplo Windows (ajuste conforme necessário)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Command customizado para atualizar CA e iniciar app
    # O container deve rodar como root ou possuir permissão
    command: >
      sh -c "
        echo 'Atualizando certificados 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 'Certificados CA atualizados.'
        else
          echo 'Comando update-ca-certificates não encontrado, pulando atualização de CA.'
        fi &&
        echo 'Iniciando aplicação...' &&
        exec your_original_application_command_here # Substitua pelo comando de inicialização do seu app
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Se precisar rodar como root apenas para atualizar CA, realize o ajuste necessário no entrypoint
    # user: root # Opcional para obter permissões

Observações:

Complexidade: Modificar o comando de inicialização pode ser trabalhoso, especialmente em imagens oficiais.
Permissões: update-ca-certificates normalmente exige permissão root.
Dependências: É necessário o pacote ca-certificates e o comando update-ca-certificates no container, o script acima tenta instalar caso falte.
Tempo de inicialização: Executar a atualização toda vez pode aumentar o tempo de startup.
Alpine Linux: O comando neste caso é apk add --no-cache ca-certificates && update-ca-certificates.

Qual método escolher?

Se puder construir uma imagem customizada e deseja confiança sistêmica, Opção 1 normalmente é a melhor.
Se não quer modificar a imagem e só precisa confiar CA para aplicações específicas, Opção 2 é prática.
Se não quer build customizado e precisa confiança sistêmica apenas em runtime, Opção 3 é ideal.

Para certificados por CA pública (ex: Let's Encrypt): Se o site ServBay usa certificado público (via ACME de Let's Encrypt), a maioria das imagens Docker já confia nessas CAs, não exigindo ações extra.

Q5: Como configurar um domínio e proxy reverso no ServBay para uma aplicação rodando dentro do Docker?

Suponha que você tem uma aplicação rodando em um contêiner Docker (ex: serviço Node.js na porta interna 3000) e deseja acessar pelo navegador via domínio amigável (ex: myapp.servbay.demo) usando ServBay, aproveitando também o gerenciamento de SSL.

Passos:

Execute o contêiner Docker mapeando a porta para o 127.0.0.1 local da máquina: Certifique-se de mapear a porta do contêiner para o endereço local do host, tornando o serviço acessível somente localmente e evitando exposição pública.
bash
```
# Exemplo: aplicação escuta na porta 3000 do contêiner, mapeia para 127.0.0.1:3001 na máquina host
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Neste exemplo, a aplicação pode ser acessada em http://127.0.0.1:3001 no host.
Adicione um novo site como proxy reverso no ServBay:
- Abra o painel de controle do ServBay.
- Clique em "Adicionar site".
- Domínio: escolha o domínio desejado, por exemplo myapp.servbay.demo.
- Tipo de site: escolha “Proxy reverso”.
- Endereço IP: insira 127.0.0.1.
- Porta: utilize a porta mapeada do Docker, ex: 3001.
- Salve as configurações.
(Opcional) Configure SSL: Após criar o site, habilite SSL caso deseje. O ServBay pode solicitar certificado da Let's Encrypt via ACME, ou utilizar o ServBay User CA/Public CA. O ServBay faz a terminação SSL; do ServBay para o Docker, a comunicação pode ser HTTP (http://127.0.0.1:3001).
Teste o acesso: Após configurar, acesse http://myapp.servbay.demo ou https://myapp.servbay.demo (se SSL estiver ativo). O ServBay irá redirecionar a requisição para a aplicação rodando no contêiner Docker.

Fluxo de funcionamento: Navegador do usuário -> https://myapp.servbay.demo -> ServBay (SSL, regras de proxy reverso) -> http://127.0.0.1:3001 (porta local) -> Aplicação dentro do container Docker.

Resumo

O ServBay facilita muito o desenvolvimento web local em macOS e Windows. Ao integrá-lo com Docker:

Para acessar sites ServBay via contêiner Docker, utilize extra_hosts ou --add-host apontando o domínio para host-gateway, garantindo repasse correto do header Host e evitando problemas de SNI.
Para acessar bancos de dados ou serviços não HTTP no ServBay pelo Docker, use host.docker.internal como hostname.
Para confiar nos certificados SSL gerados pela ServBay User CA no Docker, copie o CA para o container e adicione aos certificados confiáveis do sistema.
Para usar ServBay como proxy reverso para aplicações Docker, configure o tipo "Proxy reverso" e direcione para o IP 127.0.0.1 na porta mapeada pelo Docker.

Sempre verifique se os pacotes relevantes no ServBay (servidor web, banco de dados, etc.), assim como seus containers Docker, estão configurados e ativos.

FAQ Sobre Integração ServBay e Docker ​

Q1: Por que o ServBay modifica o arquivo hosts do meu sistema? Posso impedir isso? ​

Q2: Como meu contêiner Docker pode acessar corretamente, por domínio, o site hospedado pelo ServBay na máquina host (por exemplo, mysite.servbay.demo)? ​

Q3: Como o contêiner Docker pode se conectar ao banco de dados gerenciado pelo ServBay (ex: MySQL, PostgreSQL) ou a outros serviços não HTTP? ​

Q4: Ao acessar sites HTTPS do ServBay por domínio (com configuração extra_hosts), como faço o contêiner Docker confiar na ServBay User CA? ​

Opção 1: Confiança sistêmica no build (Dockerfile) ​

Opção 2: Confiança por aplicação em runtime (via volume e variáveis de ambiente) ​

Opção 3: Confiança sistêmica em runtime (via volume e comando customizado) ​

Q5: Como configurar um domínio e proxy reverso no ServBay para uma aplicação rodando dentro do Docker? ​

Resumo ​

FAQ Sobre Integração ServBay e Docker

Q1: Por que o ServBay modifica o arquivo `hosts` do meu sistema? Posso impedir isso?

Q2: Como meu contêiner Docker pode acessar corretamente, por domínio, o site hospedado pelo ServBay na máquina host (por exemplo, `mysite.servbay.demo`)?

Q3: Como o contêiner Docker pode se conectar ao banco de dados gerenciado pelo ServBay (ex: MySQL, PostgreSQL) ou a outros serviços não HTTP?

Q4: Ao acessar sites HTTPS do ServBay por domínio (com configuração `extra_hosts`), como faço o contêiner Docker confiar na ServBay User CA?

Opção 1: Confiança sistêmica no build (Dockerfile)

Opção 2: Confiança por aplicação em runtime (via volume e variáveis de ambiente)

Opção 3: Confiança sistêmica em runtime (via volume e comando customizado)

Q5: Como configurar um domínio e proxy reverso no ServBay para uma aplicação rodando dentro do Docker?

Resumo