FAQ: Dúvidas Frequentes sobre a Integração do ServBay com Docker

Ao utilizar o ServBay para desenvolvimento web local, talvez você queira trabalhar com ambientes de containers usando Docker. Este FAQ tem como objetivo responder às dúvidas mais comuns que surgem ao integrar ServBay com Docker, especialmente em ambientes macOS, incluindo acesso do Docker aos serviços do ServBay e a utilização do proxy reverso do ServBay para aplicativos em containers Docker.

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

O ServBay adiciona entradas ao arquivo hosts do sistema (por exemplo, mysite.servbay.demo 127.0.0.1) para permitir que você acesse sites de desenvolvimento local usando domínios personalizados, como mysite.servbay.demo. Esses sites, na prática, rodam no endereço 127.0.0.1 da sua máquina.

Entretanto, devido ao funcionamento do Docker, o arquivo hosts do macOS é lido pelo container, o que faz com que mysite.servbay.demo resolva para 127.0.0.1 dentro do container, levando o Docker a acessar o próprio container e não o serviço correto no anfitrião.

Mecanismo por trás:

Ao criar um novo site no ServBay e definir um domínio (exemplo: example.servbay.demo), o ServBay aponta esse domínio para 127.0.0.1.
Esta é uma prática padrão para possibilitar o acesso por domínios amigáveis no desenvolvimento local. Sem alterar o arquivo hosts, você só poderia acessar via http://127.0.0.1:PORT, sem usar o domínio customizado.

É possível impedir?

Em teoria, você pode remover manualmente as entradas adicionadas pelo ServBay, mas isso impede o acesso ao seu site local via o domínio configurado, contrariando a proposta do ServBay, que é facilitar o desenvolvimento local. Uma das principais funções do ServBay é justamente simplificar a criação e o acesso a sites locais. Caso não queira que o ServBay gerencie determinada entrada no hosts, o recomendado é não criar um site com esse domínio pelo ServBay.

Para a maioria dos cenários de desenvolvimento local, o gerenciamento automático do arquivo hosts pelo ServBay é o comportamento esperado e facilita muito o fluxo de trabalho.

Q2: Como meu container Docker acessa corretamente, por domínio, um site gerenciado pelo ServBay no macOS (ex: `mysite.servbay.demo`)?

Essa é uma necessidade comum, mas requer algumas configurações corretas para evitar problemas. Quando o ServBay roda um site no seu macOS (exemplo: mysite.servbay.demo, resolvendo para 127.0.0.1 no anfitrião), o 127.0.0.1 dentro do container Docker se refere ao próprio container, não ao seu Mac.

Abordagem errada: acessar diretamente o site do ServBay usando host.docker.internal como hostname

Embora o Docker Desktop para Mac (e Windows) forneça o endereço DNS especial host.docker.internal para acessar o IP do anfitrião de dentro do container, não é recomendado usar esse valor como hostname na URL do site ServBay (por exemplo, acessar http://host.docker.internal/ esperando que direcione para mysite.servbay.demo).

Isso acontece porque, ao fazer isso, o cabeçalho HTTP Host enviado ao servidor web do ServBay (como Caddy ou Nginx) será host.docker.internal, e não mysite.servbay.demo. O ServBay depende desse cabeçalho para saber qual site deve ser direcionado. Se o cabeçalho for host.docker.internal, o web server não conseguirá rotear para o site correto ou, no caso de HTTPS, poderá causar erro de SNI (Server Name Indication), já que o certificado SSL será para mysite.servbay.demo e não para host.docker.internal.

Solução correta: adicionar extra_hosts ao iniciar o container

Para que aplicações dentro do Docker consigam usar o domínio original do site do ServBay (ex: mysite.servbay.demo) e enviar o cabeçalho Host correto, inclua uma entrada no /etc/hosts do container que mapeia o domínio ao IP do anfitrião. Isso pode ser feito usando extra_hosts (em docker-compose.yml) ou --add-host (com docker run), apontando o domínio para host.docker.internal ou, preferencialmente, para host-gateway.

Com docker run:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway é um valor especial que o Docker substitui pelo IP interno do anfitrião. No Docker 20.10+, geralmente corresponde ao alias mais baixo nível de host.docker.internal.)

Com 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

Após a configuração, dentro do container:

Quando sua aplicação tentar acessar http://mysite.servbay.demo ou https://mysite.servbay.demo, o /etc/hosts do container resolve esse domínio para o IP do anfitrião Mac.
O pedido é enviado ao servidor Web do ServBay rodando no Mac.
O cabeçalho HTTP Host será corretamente mysite.servbay.demo, permitindo que o ServBay faça o roteamento correto e entregue o certificado SSL apropriado (em conexões HTTPS).

Q3: Como meu container Docker conecta a bancos de dados (MySQL, PostgreSQL) ou outros serviços não-HTTP gerenciados pelo ServBay?

Diferente do acesso a sites via domínio, para conectar a bancos de dados ou outros serviços TCP não dependentes de SNI, o recomendado e mais prático é usar host.docker.internal como hostname do servidor.

Passos:

Certifique-se de que o pacote do banco de dados (ou outro serviço) no ServBay está ativo e configurado para aceitar conexões vindas do anfitrião (a configuração padrão normalmente já libera para uso local).
Dentro do container Docker, ao configurar a conexão:
- Hostname/Servidor: host.docker.internal
- Porta: Utilize a porta configurada no ServBay para esse banco/serviço (por exemplo, MySQL padrão é 3306, PostgreSQL é 5432).
- Usuário/Senha: Use as credenciais cadastradas no ServBay.

Exemplo (conexão com MySQL gerenciado pelo ServBay): Supondo MySQL rodando na porta padrão 3306. A string/configuração de conexão do app no container seria:

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

Q4: Como faço para o container Docker confiar no certificado da User CA do ServBay ao acessar sites HTTPS (com domínio via `extra_hosts`)?

Se você já configurou, conforme Q2, o domínio secure.servbay.demo com extra_hosts ou --add-host apontando para host-gateway, mas o site usa um certificado SSL emitido pela ServBay User CA, o container do Docker não confiará nesse CA por padrão, o que ocasiona falha de handshake SSL.

Caminho do arquivo CA do ServBay (no Mac):

Certificado raiz da ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
Arquivo PEM contendo ServBay User CA, Public CA e raízes Mozilla:
- Mac ARM: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- Mac Intel: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Visão geral das soluções:

Há várias maneiras de fazer o container confiar na CA do ServBay:

Opção 1: confiança de sistema em build (via Dockerfile) – indicada para casos onde o CA deva ser aceito globalmente e o build da imagem pode ser customizado.
Opção 2: confiança por aplicação em tempo de execução (via volume e variável ambiente) – útil se só um app específico precisa do CA ou se não quer customizar a imagem.
Opção 3: confiança de sistema em runtime (via volume e comando customizado) – para quando precisa do CA no sistema todo mas não quer reconstruir a imagem.

Opção 1: Confiança de sistema em build (via Dockerfile)

Neste método, o CA é adicionado ao repositório de certificados durante o build da imagem.

Prepare o arquivo CA: Copie /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt para o contexto do Docker build (no mesmo diretório do Dockerfile, por exemplo).

Exemplo 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 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

Build com Docker Compose:

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # diretório deve conter Dockerfile e 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ável ambiente)

Monte o arquivo CA no container e configure o app para usá-lo via variável de ambiente.

Exemplo 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:
      # Exemplo para Node.js:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Exemplo para Python (requests):
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Exemplo genérico:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Consulte a documentação do aplicativo para saber a variável adequada.

Opção 3: Confiança de sistema em runtime (via volume e comando customizado)

Monte o CA e, ao iniciar o container, execute atualização do repositório de certificados no sistema, sem rebuild da imagem.

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

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # ou outra imagem com update-ca-certificates
    volumes:
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Sobrescreva o comando para fazer a atualização e iniciar sua aplicaçã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.'
        fi &&
        echo 'Iniciando aplicação...' &&
        exec your_original_application_command_here # Substitua pelo CMD real da sua app
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # user: root # Defina se quiser garantir permissão, ou ajuste via entrypoint customizado

Atenção:

Complexidade: Modificar o command ou entrypoint pode ser complicado, principalmente em imagens oficiais que já têm lógica de inicialização própria. Tenha certeza de chamar o CMD original de sua aplicação.
Permissão: Atualizar certificados geralmente exige acesso root. Se o container já roda como não-root, talvez precise elevar a permissão temporariamente.
Dependências: O container deve ter o pacote ca-certificates e o comando update-ca-certificates. O script acima tentará instalar, se necessário (para containers baseados em apt).
Tempo de inicialização: A cada start, essas checagens aumentam um pouco o tempo de subida do container.
Alpine Linux: No Alpine, use apk add --no-cache ca-certificates && update-ca-certificates no lugar do comando apt.

Qual opção escolher?

Se pode customizar a imagem e quer aceitação global do CA, Opção 1 é a ideal.
Se só precisa que apps específicos confiem, sem alterar a imagem, Opção 2 é rápida.
Se não quer rebuild, quer confiança total no sistema, Opção 3 é mais adequada.

E certificados de CAs públicas (Ex: Let's Encrypt): Se seu site ServBay usa certificação pública via ACME (como Let's Encrypt), quase todos os contêineres já reconhecem esses CAs por padrão, sem necessidade de configuração extra.

Q5: Como uso o ServBay para atribuir domínio e proxy reverso para aplicações rodando em containers Docker?

Suponha que você tenha um app rodando no container Docker (por exemplo, um serviço Node.js ouvindo na porta 3000 interna), e quer atribuir um domínio amigável como myapp.servbay.demo usando o ServBay como proxy reverso, além de aproveitar o gerenciamento de SSL.

Passo a passo:

Rode o container mapeando a porta para o 127.0.0.1 do anfitrião: Garanta que o container está mapeando a porta do app para um port do Mac, apenas pelo 127.0.0.1 para restringir o acesso local e proteger do acesso externo direto.
bash
```
# Exemplo: App escuta 3000 no Docker, mapeando para 127.0.0.1:3001 no Mac
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Agora, o app interno (porta 3000) pode ser acessado pelo host via http://127.0.0.1:3001.
Adicione um novo site no ServBay e configure o proxy reverso:
- Abra o painel de gerenciamento do ServBay.
- Clique em “Adicionar Site”.
- Domínio: Escolha o domínio desejado, como myapp.servbay.demo.
- Tipo de Site: Selecione “Proxy Reverso”.
- Endereço IP: Digite 127.0.0.1.
- Porta: Informe o número da porta que o container exportou, ex: 3001.
- Clique em “Salvar” ou “Adicionar”.
(Opcional) Ative o SSL: Depois de criar o site, edite as configurações para ativar o SSL no domínio. O ServBay irá configurar SSL automaticamente via CA pública (como Let's Encrypt) usando ACME, ou pode usar o ServBay User/Public CA. O ServBay trata o fim SSL, enquanto a comunicação com o Docker permanece HTTP (http://127.0.0.1:3001).
Faça o teste de acesso: Após salvar as configurações, acesse pelo navegador http://myapp.servbay.demo ou https://myapp.servbay.demo (se habilitou SSL). O ServBay faz o proxy do pedido até a aplicação rodando no Container Docker.

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

Resumo

O ServBay simplifica drasticamente o desenvolvimento web local no macOS. Ao integrá-lo ao Docker:

Para acessar sites do ServBay a partir de containers Docker, utilize extra_hosts ou --add-host mapeando o domínio para host-gateway e garanta o correto envio do cabeçalho Host e funcionamento do SNI.
Para acessar bancos de dados ou outros serviços não-HTTP gerenciados pelo ServBay, use sempre host.docker.internal como hostname.
Para fazer o container confiar em certificados SSL da ServBay User CA, copie/import o arquivo CA para o container e atualize o repositório de CAs dele.
Para usar o ServBay como proxy reverso para apps de containers Docker, crie um novo site no ServBay do tipo "Proxy Reverso" apontando para a porta mapeada no 127.0.0.1 do host.

Certifique-se sempre de que os serviços relevantes no ServBay (como Web Server e bancos de dados) e seus containers Docker estejam corretamente configurados e rodando.

FAQ: Dúvidas Frequentes sobre a Integração do ServBay com Docker ​

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

Q2: Como meu container Docker acessa corretamente, por domínio, um site gerenciado pelo ServBay no macOS (ex: mysite.servbay.demo)? ​

Q3: Como meu container Docker conecta a bancos de dados (MySQL, PostgreSQL) ou outros serviços não-HTTP gerenciados pelo ServBay? ​

Q4: Como faço para o container Docker confiar no certificado da User CA do ServBay ao acessar sites HTTPS (com domínio via extra_hosts)? ​

Opção 1: Confiança de sistema em build (via Dockerfile) ​

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

Opção 3: Confiança de sistema em runtime (via volume e comando customizado) ​

Q5: Como uso o ServBay para atribuir domínio e proxy reverso para aplicações rodando em containers Docker? ​

Resumo ​

FAQ: Dúvidas Frequentes sobre a Integração do ServBay com Docker

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

Q2: Como meu container Docker acessa corretamente, por domínio, um site gerenciado pelo ServBay no macOS (ex: `mysite.servbay.demo`)?

Q3: Como meu container Docker conecta a bancos de dados (MySQL, PostgreSQL) ou outros serviços não-HTTP gerenciados pelo ServBay?

Q4: Como faço para o container Docker confiar no certificado da User CA do ServBay ao acessar sites HTTPS (com domínio via `extra_hosts`)?

Opção 1: Confiança de sistema em build (via Dockerfile)

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

Opção 3: Confiança de sistema em runtime (via volume e comando customizado)

Q5: Como uso o ServBay para atribuir domínio e proxy reverso para aplicações rodando em containers Docker?

Resumo