Podman Compose: Uma alternativa sem raiz ao Docker Compose

Digamos que você tem um arquivo docker-compose.yml que está funcionando há meses. Mas agora, você deve usar o Podman em vez do Docker e não tem certeza se precisa editar o arquivo ou começar do zero. Seu ambiente de desenvolvimento local depende desse arquivo Compose, e reconstruir toda a sua configuração não é exatamente algo para o qual você tem tempo.

A boa notícia é que o Podman Compose permite que você execute arquivos Compose existentes com o Podman em vez do Docker. É uma camada de compatibilidade baseada em Python que transforma suas definições do Compose em comandos do Podman, pra você continuar usando o fluxo de trabalho com vários contêineres que já conhece.

Neste artigo, vou mostrar o que é o Podman Compose, como instalá-lo e como rodar sua primeira aplicação com vários contêineres usando ele. Se você não conhece alguns dosconceitos de mencionados neste artigo, inscreva-se em nosso Conceitos de conteinerização e virtualização para entender o básico.

O que é o Podman Compose?

O Podman Compose é uma ferramenta baseada em Python que lê seus arquivos docker-compose.yml e os traduz em comandos Podman.

Você ainda escreve um arquivo padrão Docker Compose padrão com serviços, redes e volumes. O Podman Compose analisa esse arquivo e executa os comandos equivalentes do podman para iniciar seus contêineres. Ele faz o trabalho de tradução por você, assim você não precisa converter manualmente a sintaxe do Compose em comandos da CLI do Podman.

É importante notar que o Podman Compose não é um substituto direto do Docker Compose.

É uma camada de compatibilidade. Algumas funcionalidades do Docker Compose funcionam direitinho, outras precisam de ajustes e algumas nem funcionam. A ferramenta busca compatibilidade, mas não replica todos os comportamentos do Docker Compose.

Aqui vai outra maneira de pensar sobre isso: O Docker Compose fala direto com o daemon do Docker. O Podman Compose fala com a CLI do Podman, que então gerencia os contêineres sem um daemon. O resultado final parece parecido, mas a mecânica por trás é diferente.

Isso quer dizer que você pode reutilizar a maioria dos seus arquivos Compose existentes, mas vai precisar entender onde estão as diferenças.

Por que usar o Podman Compose?

O Podman Compose permite que você execute aplicativos com vários contêineres sem precisar instalar o Docker.

Quando comparado com o Docker, você obtém contêineres sem root por padrão. O Podman roda contêineres sem precisar de privilégios de root. Em linguagem simples, há menos risco se um contêiner for comprometido. O Docker precisa que o daemon rode como root, mesmo se você estiver usando contêineres sem root em cima dele.

Isso faz com que o Podman Compose seja mais adequado para ambientes focados em segurança. Se você estiver trabalhando em servidores Linux bloqueados ou ambientes onde não é permitido executar um daemon de nível raiz, o Podman Compose oferece o fluxo de trabalho com vários contêineres de que você precisa.

Também é útil para desenvolvimento e testes. Você pode criar ambientes locais, testar configurações de contêineres e validar seus arquivos Compose sem precisar instalar o Docker. É ideal para implementações leves, onde você não precisa de uma orquestração completa.

Mas vale a pena notar que o Podman Compose não é ideal para todas as situações.

Se você estiver executando cargas de trabalho de produção em grande escala, vai preferir usar o Kubernetes ou o Docker Swarm. O Podman Compose também tem um suporte mais fraco no macOS e no Windows em comparação com o Linux, então sua experiência de desenvolvimento multiplataforma não vai ser tão tranquila. E se sua equipe já está envolvida no ecossistema Docker com plug-ins e ferramentas personalizadas, mudar para o Podman Compose significa reconstruir partes desse fluxo de trabalho.

Para terminar, use o Podman Compose quando precisar de contêineres sem root, ambientes que priorizam a segurança ou uma configuração de desenvolvimento sem Docker.

Instalando o Podman Compose

O Podman Compose funciona melhor no Linux, onde o Podman roda nativamente.

Você pode instalar no macOS e no Windows, mas primeiro precisa rodar o Podman dentro de uma máquina virtual. Isso torna tudo mais complicado e não é tão tranquilo quanto no Linux. Se você estiver usando macOS ou Windows, espere etapas extras de configuração e possíveis problemas de rede.

Instalando no Linux

A maneira mais fácil de instalar o Podman Compose é pelo site pip.

pip install podman-compose

Instalando o Podman compose no Linux

Isso instala a versão mais recente do PyPI. Você não precisa se preocupar com o gerenciamento da versão do Python — se você tiver o Python 3 instalado, está tudo certo.

Algumas distribuições Linux também incluem o Podman Compose em seus repositórios. No Fedora, RHEL e CentOS, você pode usar:

sudo dnf install podman-compose

Nos sistemas Ubuntu e Debian, execute o seguinte:

sudo apt install podman-compose

As versões do gerenciador de pacotes costumam ficar pra trás em relação ao PyPI, então talvez você não consiga as funcionalidades mais recentes na hora.

Instalando no macOS e Windows

No macOS e no Windows, primeiro você precisa configurar o Podman Desktop ou usar o podman machine para criar uma VM Linux. Depois que estiver funcionando, instale o Podman Compose com o comando ` pip ` dentro desse ambiente.

Então, o primeiro passo é conectar-se à máquina:

podman machine ssh

Conectando-se via SSH à VM do Podman

Como a VM é baseada no Fedora, você pode usar esse comando para instalar o Podman Compose:

sudo dnf install podman-compose

Instalando o Podman Compose

Esse processo de duas etapas significa que você não está executando o Podman Compose diretamente no seu sistema operacional host, mas sim dentro da VM Linux criada pelo Podman.

Verificando a instalação

Execute este comando para verificar se o Podman Compose foi instalado corretamente:

podman-compose --version

Verificando a instalação do Podman Compose

Você deve ver o número da versão impresso no terminal. Se você receber um erro “comando não encontrado”, certifique-se de que o diretório Python bin esteja no seu PATH.

É só isso que você precisa para começar a usar o Podman Compose.

Executando um arquivo Compose com o Podman Compose

Você já tem o Podman Compose instalado — agora vou te mostrar como rodar um aplicativo de verdade.

Usando um arquivo Docker Compose que já existe

O Podman Compose lê arquivos padrão docker-compose.yml. Você não precisa renomear nada nem mudar o formato.

Aqui está um aplicativo FastAPI simples definido em um arquivo Compose:

services:
  web:
    image: python:3.14-slim
    container_name: fastapi-app
    working_dir: /src
    volumes:
      - ./src:/src
    ports:
      - "8000:8000"
    command: bash -c "pip install fastapi uvicorn && uvicorn main:app --host 0.0.0.0 --port 8000"

Com o código do aplicativo em src/main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from FastAPI"}

@app.get("/health")
def health_check():
    return {"status": "healthy"}

A maioria dos recursos do Docker Compose funciona direto com o Podman Compose. Isso inclui:

• Extração de imagens e criação de contêineres
• Mapeamentos de portas
• Montagens de volume (tanto volumes nomeados quanto montagens de ligação)
• Variáveis de ambiente
• Rede básica entre serviços

Mas algumas funcionalidades precisam de ajustes. Se o seu arquivo Compose usa plug-ins específicos do Docker, drivers de rede personalizados ou argumentos de compilação avançados, provavelmente você precisará modificar essas seções.

O Podman Compose também lida com a rede de forma diferente — os serviços não se resolvem automaticamente uns aos outros pelo nome do serviço, como o Docker Compose faz.

Comandos básicos do Podman Compose

Agora você pode iniciar seus serviços com este comando:

podman-compose up

Isso pega as imagens, cria contêineres e inicia tudo o que está definido no seu arquivo Compose. Adicione -d para rodar no modo destacado se você não quiser que os registros sejam enviados para o seu terminal.

Saída do Podman

Agora você pode abrir o aplicativo na porta 8000 na sua máquina (ou em uma instância remota do Ubuntu, como a que estou usando). Você vai ver o seguinte:

Aplicativo FastAPI rodando pelo Podman

Para parar os serviços em execução, execute o seguinte:

podman-compose down

Isso interrompe e remove os contêineres. Os volumes continuam lá, a menos que você adicione --volumes para removê-los também.

Para conferir seus registros de serviço, use este comando:

podman-compose logs

Adicione -f para acompanhar os registros em tempo real ou especifique um nome de serviço para ver os registros apenas desse contêiner.

Para limpar tudo, incluindo contêineres, redes e volumes, execute isto:

podman-compose down --volumes

Os comandos refletem a sintaxe do Docker Compose, então, se você já conhece o docker-compose, vai se sentir em casa.

Podman Compose vs. Docker Compose e outros

O Podman Compose e o Docker Compose têm o mesmo objetivo, mas funcionam de maneira diferente. Deixa eu te explicar como.

Execução sem raiz

O Docker Compose precisa que o daemon do Docker esteja rodando como root. Mesmo quando você configura contêineres sem root, o próprio daemon precisa de privilégios elevados. O Podman Compose funciona totalmentesem acesso root por padrão. Seus contêineres começam como seu usuário, não como um serviço do sistema, o que reduz as opções de ataque e torna o Podman Compose mais seguro em ambientes com vários usuários.

Comportamento em redes

O Docker Compose cria uma rede bridge padrão para seus serviços. Os contêineres podem se comunicar automaticamente pelo nome do serviço.

O Podman Compose usa redes baseadas em pods. Todos os contêineres no seu arquivo Compose são agrupados em um único pod do Podman e compartilham o mesmo namespace de rede. Isso quer dizer que os contêineres se comunicam por meio de um localhost, em vez de nomes de serviço, o que pode surpreender os usuários do Docker.

Se o seu aplicativo espera acessar um banco de dados em db:5432, você precisará alterar isso para localhost:5432 ao executar com o Podman Compose.

Agrupamento baseado em módulos

O Docker Compose cuida dos contêineres individuais. O Podman Compose cria umpod , que é um agrupamento inspirado no Kubernetes, onde os contêineres compartilham a rede e podem compartilhar o armazenamento. Esse modelo de pod alinha o Podman Compose com os padrões do Kubernetes, facilitando a migração de cargas de trabalho posteriormente, caso você precise de orquestração.

integração com o systemd

O Podman se integra ao systemd para gerenciar contêineres como serviços do sistema. Você pode criar arquivos de unidade systemd a partir de contêineres em execução e gerenciá-los como qualquer outro serviço Linux. O Docker não oferece integração nativa com o systemd no nível do contêiner.

Outras opções

Se o Podman Compose não atender às suas necessidades, você tem estas alternativas:

• Podman nativo com systemd permite que você gerencie contêineres como serviços sem precisar usar arquivos Compose.
• O Kubernetes te dá uma orquestração completa se você estiver rodando cargas de trabalho de produção em escala, embora seja bem mais pesado do que as ferramentas do tipo Compose.

O Podman Compose está em algum lugar entre comandos simples de contêiner e orquestração completa. Ele oferece fluxos de trabalho com vários contêineres sem a necessidade do daemon do Docker.

Rede e volumes no Podman Compose (o que mudou)

Os usuários do Docker que mudam para o Podman Compose geralmente reclamam de duas coisas: rede e volumes. Nesta seção, vou falar sobre as diferenças.

Comunicação entre serviços

No Docker Compose, você se conecta a outros serviços pelo nome deles. Se você tem um serviço web e um serviço de banco de dados chamado db, seu aplicativo se conecta a db:5432.

O Podman Compose coloca todos os serviços em um único pod. Os contêineres no mesmo pod compartilham um namespace de rede, o que significa que todos eles usam localhost. A sua string de conexão com o banco de dados muda de db:5432 para localhost:5432.

Isso pega as pessoas de surpresa. Seu aplicativo inicia, tenta se conectar a db:5432 e falha porque esse nome de host não é resolvido. Você vai precisar atualizar suas cadeias de conexão ou variáveis de ambiente para usar localhost.

Redes padrão

O Docker Compose cria uma rede bridge para seus serviços. Cada contêiner recebe seu próprio endereço IP nessa rede, e o resolvedor DNS do Docker lida com as pesquisas de nomes de serviços.

O Podman Compose não cria redes separadas por padrão. O modelo pod significa que os contêineres compartilham a rede em um nível mais baixo. Se você definir redes personalizadas no seu arquivo Compose, o Podman Compose vai tentar criá-las, mas o comportamento pode não ser exatamente igual ao do Docker.

Comportamento de montagem de volume e ligação

Os volumes e as montagens vinculadas funcionam basicamente da mesma maneira entre o Docker Compose e o Podman Compose. Você define-os no seu arquivo Compose, e o Podman cria-os.

Mas tem um porém com as permissões.

O Podman funciona sem privilégios de root por padrão, então a propriedade e as permissões dos arquivos podem se comportar de maneira diferente. Uma montagem vinculada que funciona bem no Docker pode apresentar erros de permissão no Podman porque o usuário do contêiner não corresponde ao UID do usuário do host.

Você também vai notar que os locais de volume são diferentes. O Docker guarda os volumes em /var/lib/docker/volumes/, enquanto o Podman guarda em ~/.local/share/containers/storage/volumes/ para contêineres sem root.

As correções são fáceis de implementar se você souber o que está acontecendo. Então, basta ajustar as cadeias de conexão para a rede e verificar as permissões dos arquivos para ver se tem algum problema de volume.

Limitações comuns e armadilhas

O Podman Compose funciona bem para configurações básicas com vários contêineres, mas tem algumas limitações que você deve conhecer antes de se comprometer com ele.

Recursos do Compose não suportados

Nem todos os recursos do Docker Compose funcionam no Podman Compose. Construir contextos com argumentos complexos muitas vezes dá errado ou funciona de forma diferente. Os plug-ins e extensões do Docker Compose não vão funcionar. Recursos como GPU passthrough, verificações avançadas de integridade e alguns modos de rede não funcionam ou precisam de soluções alternativas.

Se o seu arquivo Compose usa bastante os recursos do docker-compose.yml versão 3.x, prepare-se para algumas tentativas e erros.

Expectativas de rede diferentes do Docker

Os serviços não se comunicam pelo nome do serviço - eles usam localhost em vez disso. Isso faz com que os aplicativos que codificam nomes de serviços nas cadeias de conexão deixem de funcionar.

As redes de ponte personalizadas não funcionam da mesma forma que o Docker. A resolução DNS funciona de forma diferente por causa do modelo de pod.

Prepare-se para gastar um tempinho atualizando as configurações e variáveis de ambiente para combinar com o modelo de rede do Podman, mas isso é só uma vez.

Limitações da plataforma no macOS/Windows

O Podman Compose funciona melhor no Linux. No macOS e no Windows, você está executando tudo dentro de uma VM Linux, o que adiciona camadas de complexidade. A sincronização de arquivos entre o seu host e a VM pode ser mais lenta. A rede entre o seu host e os contêineres precisa de uma configuração extra.

Se sua equipe usa máquinas macOS ou Windows para desenvolvimento, o Docker Compose geralmente é a opção mais tranquila.

Maturidade das ferramentas e lacunas no ecossistema

O Podman Compose é mais recente que o Docker Compose. A comunidade é menor, então encontrar respostas para problemas específicos exige mais pesquisa. Ferramentas e integrações de terceiros são criadas primeiro para o Docker e depois para o Podman (se for o caso). O suporte IDE e as ferramentas GUI ficam para trás em relação ao ecossistema do Docker.

Você não vai encontrar muitas respostas no Stack Overflow ou questões no GitHub sobre problemas com o Podman Compose.

Essas limitações não tornam o Podman Compose inutilizável, mas são algo a se pensar antes de se comprometer. Os usuários do Docker Compose não precisam se preocupar com esses problemas.

Melhores práticas para usar o Podman Compose

Veja como evitar os problemas mais comuns do Podman Compose.

• Comece com arquivos Compose simples. Não migre primeiro a sua configuração mais complexa do Docker. Comece com um aplicativo de serviço único, veja se ele funciona e, em seguida, adicione mais alguns. Isso permite que você identifique os problemas assim que eles aparecerem.

• Teste a rede sem raiz logo no começo. Inicie um aplicativo multisserviço e veja se os contêineres conseguem se comunicar por localhost. Mude suas cadeias de conexão de nomes de serviço para localhost. Se a rede não funcionar como você espera, você vai perceber na hora.

• Seja bem claro sobre volumes e portas. Não confie nas configurações padrão. Especifique os caminhos completos para as montagens de ligação. Defina os mapeamentos de porta. Defina as permissões de arquivo explicitamente se você estiver montando diretórios do host. O modelo sem raiz do Podman significa que as suposições que funcionavam no Docker podem falhar aqui.

• Use o Podman Compose principalmente para desenvolvimento e produção leve. Ele lida bem com ambientes de desenvolvimento locais e pequenas implantações. Para produção em escala, você vai precisar do Kubernetes ou de outra plataforma de orquestração. O Podman Compose não foi feito pra clusters de alta disponibilidade ou malhas de serviço complexas.

Conclusão

O Podman Compose oferece uma maneira prática de executar aplicativos com vários contêineres usando o Podman em vez do Docker. Ele lê seus arquivos Compose existentes e os traduz em comandos Podman, assim você não precisa aprender um fluxo de trabalho totalmente novo. Mas não é uma cópia perfeita do Docker Compose. A rede funciona de forma diferente, alguns recursos não são suportados e você vai precisar ajustar as cadeias de conexão e configurações para se adequarem ao modelo baseado em pods do Podman.

Por fim, recomendo que você leia sobre as diferenças entre o Docker e o Podman para saber mais sobre suas respectivas abordagens arquitetônicas e compatibilidade.