> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://ajuda.streethosting.com.br/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Como hospedar API com Docker no VPS

# Como hospedar API com Docker no VPS: arquitetura simples e escalável

Publicar APIs em VPS com Docker é uma das formas mais eficientes de manter controle total sobre a infraestrutura sem a complexidade de serviços gerenciados. Este guia mostra uma arquitetura sólida para produção.

## Arquitetura recomendada

```
Internet → Nginx (SSL + proxy) → API Container → Database Container
                                                → Volumes persistentes
                                                → Backup off-site
```

Cada componente roda em container separado, orquestrado pelo Docker Compose.

## Exemplo completo de Docker Compose

```yaml
services:
  api:
    build: .
    env_file: .env
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:16-alpine
    env_file: .env
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
      interval: 10s
      timeout: 5s
      retries: 5

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - api
    restart: unless-stopped

volumes:
  pgdata:
```

## Protegendo segredos

Nunca coloque senhas diretamente no `docker-compose.yml`. Use arquivo `.env`:

```bash
# .env
POSTGRES_USER=api_user
POSTGRES_PASSWORD=senha_forte_aqui
POSTGRES_DB=api_db
API_SECRET_KEY=chave_secreta_aqui
```

Adicione `.env` ao `.gitignore` para nunca commitar segredos:

```bash
echo ".env" >> .gitignore
```

## Healthcheck: por que é essencial

O healthcheck permite que o Docker saiba se o container está saudável. Se falhar:
* O container é marcado como "unhealthy".
* Ferramentas de monitoramento podem alertar.
* Outros containers com `depends_on: condition: service_healthy` esperam antes de iniciar.

## Atualização sem downtime

Para atualizar a API sem interrupção:

```bash
# Baixar nova versão da imagem
docker compose pull api

# Recriar apenas o container da API
docker compose up -d --no-deps api
```

O Nginx continua respondendo enquanto o novo container sobe. A transição é quase instantânea.

Para aplicações críticas, considere blue-green deployment: suba o container novo em outra porta, valide, e só então redirecione o Nginx.

## Logs e observabilidade

```bash
# Logs de todos os serviços
docker compose logs -f

# Logs apenas da API
docker compose logs -f api

# Limitar saída
docker compose logs --tail=100 api
```

Para centralizar logs, considere enviar para uma stack de observabilidade (Loki + Grafana, ou Elasticsearch + Kibana).

## Perguntas frequentes (FAQ)

### Docker Compose aguenta tráfego alto?
Para a maioria dos projetos em VPS único, sim. Docker Compose orquestra containers de forma eficiente. Para alta disponibilidade multi-servidor, considere Docker Swarm ou Kubernetes.

### Preciso de Nginx se a API já responde HTTP?
Sim, recomendamos. Nginx lida melhor com SSL, compressão, rate limiting e servir arquivos estáticos. Sua API deve focar na lógica de negócio.

### Como faço rollback se a nova versão falhar?
Se você versionou as imagens (ex: `minha-api:v1.2`), basta alterar a tag no Compose e rodar `docker compose up -d` novamente com a versão anterior.

## Próximos passos

* Monte a stack base com [Docker no VPS](/pt/article/instalar-docker-no-vps-com-docker-compose)
* Proteja o servidor com [Hardening Linux](/pt/article/hardening-linux-para-vps)
* Planeje migrações com [Migrar sem downtime](/pt/article/migrar-site-para-vps-sem-downtime)