Entenda Docker Compose no Alpine Linux 3.22: instalação

Docker Compose no Alpine Linux 3.22 é o plugin oficial da CLI Docker (pacote docker-cli-compose) que orquestra vários containers a partir de um YAML. O Compose só funciona com o daemon Docker ativo no OpenRC; não substitui o motor. Para instalar, siga estes passos:

1. Confira e habilite o repositório community no apk, se ainda estiver comentado.
2. Atualize o índice de pacotes e instale docker junto com docker-cli-compose.
3. Habilite o serviço docker no OpenRC e inicie o daemon.
4. Valide com docker compose version e docker info.
5. Suba um compose.yml mínimo com docker compose up -d e confira docker compose ps.

Pré-requisitos para Docker Compose no Alpine Linux 3.22

O repositório community do apk é a base desta instalação: sem ele o Alpine não lista o plugin Compose. Trabalhe como root (ou com um usuário que consiga elevar privilégio), em uma instância Alpine Linux 3.22 com rede estável até os mirrors oficiais. O Compose não sobe sozinho: ele fala com o socket do daemon, então o pacote docker precisa estar presente e o serviço precisa iniciar no OpenRC. Reserve espaço em disco para imagens e volumes; um YAML simples puxa camadas na primeira execução. Se o acesso for remoto, use SSH com chave e confirme o login antes de editar repositórios — o artigo Acessando servidores VPS Linux da AviraHost descreve o caminho até o terminal. Em ambiente compartilhado, alinhe quem pode falar com o socket: o grupo docker evita rodar compose como root no dia a dia, mas a instalação inicial continua privilegiada. Tenha um editor (vi ou nano) para /etc/apk/repositories e para o compose.yml de teste. Não misture o binário legado docker-compose (hífen) com o plugin docker compose (espaço); no 3.22 o caminho suportado é o plugin via apk.

• Alpine Linux 3.22 com acesso root e rede até dl-cdn.alpinelinux.org.
• Repositório community habilitado em /etc/apk/repositories.
• Pacotes docker e docker-cli-compose (plugin CLI, não o binário isolado).
• OpenRC disponível para rc-update e rc-service; systemd não é requisito.
• Porta de teste livre (exemplo: 8080) se for expor um serviço no YAML.

Como instalar o plugin CLI com apk e community

O pacote docker-cli-compose entra pelo apk depois que o community está ativo; essa é a diferença prática em relação a distros que entregam o plugin só pelo repositório do vendor. Abra /etc/apk/repositories e localize a linha v3.22/community. Se estiver comentada com #, descomente. Evite duplicar URLs: uma linha community válida basta. Em muitos templates a linha se parece com https://dl-cdn.alpinelinux.org/alpine/v3.22/community. Em seguida atualize o índice para o apk enxergar docker, a CLI e o plugin.

Docker Compose no Alpine Linux 3.22: conferir repositórios apk

Ao listar o arquivo, você deve ver main e community apontando para a série 3.22. Se community faltar, o search não devolve docker-cli-compose e a instalação para no meio.

cat /etc/apk/repositories
apk update
apk search docker

Output esperado: linhas de repositório v3.22/main e v3.22/community, seguido de nomes como docker, docker-cli e docker-cli-compose no search.

Com o índice atualizado, instale o motor e o plugin na mesma transação. Assim a CLI já carrega o subcomando compose sem baixar binário solto em /usr/local/bin.

apk add docker docker-cli-compose

Output esperado: o apk resolve dependências, instala os pacotes e termina com uma linha OK indicando que a transação concluiu.

Confirme o plugin antes mesmo de subir containers. Se a CLI responder ao subcomando, o pacote está no lugar certo.

docker compose version

Output esperado: uma linha Docker Compose version seguida da versão empacotada pelo apk da 3.22.

Se aparecer “compose is not a docker command”, o plugin não entrou no caminho da CLI: revise apk info docker-cli-compose e não tente o hífen docker-compose como atalho. Quem administra o host também pode consultar o artigo Compreendendo o Servidor VPS: O que é e Como Funciona! para dimensionar CPU e disco antes de puxar imagens grandes.

Iniciar o daemon Docker com OpenRC

O OpenRC é o init do Alpine: sem rc-service no docker, o Compose falha ao conectar no socket mesmo com o plugin instalado. Habilite o serviço no runlevel default para sobreviver a reboot e só então suba o daemon. Não procure unit systemd; systemctl não faz parte deste fluxo.

rc-update add docker default
rc-service docker start
rc-service docker status

Output esperado: docker added to runlevel default; started; status indicando que o serviço está em execução.

Valide o motor, não só o init. docker info consulta o daemon via socket Unix (em geral /var/run/docker.sock). Se a conexão recusar, o Compose também recusará.

docker info

Output esperado: bloco Server com informações do motor; ausência da mensagem Cannot connect to the Docker daemon.

Para operar compose sem root no cotidiano, inclua o usuário no grupo docker e recarregue a sessão SSH. A permissão do socket é o que libera docker compose up sem sudo. Se a sessão antiga continuar sem o grupo, feche o login e entre de novo. Problemas de chave ou sessão estão cobertos em Como solucionar problemas de acesso SSH no VPS Linux: Guia Completo. Em host recém-provisionado, troque a senha de root antes de expor portas de teste; o procedimento está em Como trocar a senha do usuário root do servidor VPS ou Dedicado.

addgroup usuario docker

Substitua usuario pelo login real. O Compose continua sendo apenas o orquestrador: quem cria redes, volumes e containers é o daemon já ativo no OpenRC.

Validar a orquestração com um compose.yml mínimo

Um arquivo YAML de stack prova que o plugin conversa com o daemon e que pull, rede e container sobem de ponta a ponta. Crie um diretório só para o teste, evite misturar com dados de produção e use um serviço curto, por exemplo Nginx na imagem alpine, publicado em 8080 no host. O nome compose.yml (ou docker-compose.yml) é o que o subcomando procura no diretório corrente.

mkdir -p /opt/compose-teste
cat > /opt/compose-teste/compose.yml << 'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
EOF
cd /opt/compose-teste
docker compose up -d
docker compose ps

Output esperado: pull da imagem se ainda não existir, container criado na rede do projeto, estado running e mapeamento 0.0.0.0:8080->80/tcp.

Teste o HTTP local com wget ou um cliente na própria máquina. Em firewall restritivo, libere 8080 só para o IP de documentação da sua rede de gestão (por exemplo 203.0.113.10). Não use domínio de exemplo como se fosse o hostname real do servidor; em produção o YAML apontará para seudominio.com.br nos labels ou no proxy, não neste teste mínimo.

wget -qO- http://127.0.0.1:8080 | head

Output esperado: trecho HTML padrão da página inicial do Nginx.

Para encerrar o teste sem apagar o YAML:

docker compose down

Isso remove o container e a rede do projeto. Volumes nomeados só saem com down -v; neste exemplo não há volume persistente. A partir daqui, o mesmo fluxo serve para stacks com banco, fila e proxy: um arquivo, um diretório, docker compose up -d depois que o daemon estiver saudável.

Problemas comuns e como resolver

Sintoma: apk search não lista docker-cli-compose

Causa: o repositório community está ausente, comentado ou a série no URL não é v3.22, então o índice do apk não contém o plugin.
Solução: edite /etc/apk/repositories, garanta a linha community da 3.22, rode apk update e apk search docker de novo. Sem community o Alpine não oferece vários pacotes Docker.

Sintoma: Cannot connect to the Docker daemon ou erro de socket

Causa: o serviço docker não está no ar no OpenRC, ou o usuário atual não tem permissão em /var/run/docker.sock.
Solução: rc-service docker start, confira rc-service docker status e docker info. Inclua o usuário no grupo docker e reinicie a sessão SSH. O Compose não inicia o daemon sozinho.

Sintoma: comando docker-compose (com hífen) não encontrado

Causa: no Alpine Linux 3.22 o caminho usual é o plugin docker compose (espaço) via docker-cli-compose, não o binário legado isolado.
Solução: use docker compose version. Se precisar do hífen por script antigo, ajuste o script para o subcomando oficial em vez de baixar binário avulso.

Sintoma: compose up baixa imagem mas a porta não responde

Causa: conflito em 8080, serviço ainda criando, ou firewall filtrando o bind.
Solução: docker compose ps, docker compose logs e ss -lnt | grep 8080. Troque a porta no YAML se 8080 já estiver ocupada. Confirme que o teste usa 127.0.0.1 antes de abrir o serviço na internet.

Perguntas frequentes sobre Docker Compose no Alpine Linux 3.22

Como instalar Docker Compose no Alpine Linux 3.22?

Atualize o apk, habilite a community se necessário, instale docker e docker-cli-compose e inicie o daemon Docker. Confirme com docker compose version. No Alpine o Compose costuma ser o plugin CLI, não o binário docker-compose isolado. Sem o daemon no OpenRC, o plugin instala mas não orquestra nada. Depois da versão, um compose.yml mínimo com up -d fecha a validação.

Qual a diferença entre docker-compose e docker compose no Alpine?

docker compose (com espaço) é o plugin oficial da CLI. docker-compose (hífen) é o binário legado. No Alpine Linux 3.22 o caminho usual é o pacote docker-cli-compose, invocado como docker compose. Scripts que chamam o hífen quebram até serem atualizados. Não instale os dois em paralelo sem necessidade: a CLI unificada evita PATH confuso.

Preciso de systemd para o Docker Compose no Alpine 3.22?

Não. O Alpine usa OpenRC. Habilite e inicie o serviço docker com rc-update e rc-service. O Compose só orquestra stacks depois que o daemon Docker estiver ativo. Procurar systemctl enable docker neste sistema não substitui o runlevel default. O status do serviço e o docker info são a prova de que o socket está pronto.

Como validar se o Compose está funcionando após a instalação?

Rode docker info e docker compose version. Crie um diretório com um compose.yml mínimo, execute docker compose up -d e confira docker compose ps. Se o daemon não estiver no ar, o Compose falha ao conectar no socket. Um wget em 127.0.0.1 na porta publicada confirma que o proxy de porta do motor está ativo. Encerre o teste com docker compose down.

O que fazer se o apk não achar o pacote docker-cli-compose?

Verifique /etc/apk/repositories com community habilitada, rode apk update e busque com apk search docker. Sem o repositório community o Alpine não lista vários pacotes Docker. Confirme que a URL é da série v3.22, não de outra branch. Depois do update, apk add docker docker-cli-compose deve resolver o plugin junto com o motor.

Conclusão

• Deixe community ativo, instale docker e docker-cli-compose e trate docker compose (espaço) como o comando padrão na 3.22.
• Suba o daemon com OpenRC antes de qualquer YAML; o plugin não substitui rc-service docker start.
• Valide sempre com version, info, up -d e ps em um diretório de teste, e só então leve o mesmo padrão ao stack de produção.

Leia também

• Otimizar Docker Compose no Debian 12: rede, volumes e RAM
• Guia Alpine Linux 3.22: instalar Node-RED para automação DevOps
• Entenda Docker Compose build sem cache no CentOS 9

Precisa de ajuda com Docker Compose no Alpine Linux 3.22?

Um VPS com Alpine bem dimensionado reduz atrito na hora de instalar o plugin, manter o daemon no OpenRC e publicar stacks com Compose. A equipe pode ajudar a escolher recursos alinhados ao volume de imagens e ao tráfego esperado.

Ver planos de Servidor VPS