ACLClouds
ACLClouds

Como usar o Docker Compose num VPS Ubuntu ou Debian?

Escrever um ficheiro compose.yaml, iniciar o WordPress e o MariaDB com docker compose up -d e depois gerir registos, atualizações, cópias de segurança e

O Docker Compose descreve vários contentores num único ficheiro, compose.yaml: imagens, portas, volumes, variáveis e ordem de arranque. Um só comando, docker compose up -d, cria ou atualiza toda a stack. Este guia parte de um VPS com o Docker já instalado, monta um exemplo concreto, WordPress com MariaDB, e depois detalha os comandos do dia a dia e os erros mais frequentes. Aplica-se tal como está ao Ubuntu 22.04 / 24.04 e ao Debian 12 / 13.

Procedimento passo a passo

  1. Verificar o Docker e o plugin Compose

    Execute docker compose version. Se a resposta for docker: 'compose' is not a docker command, instale o Docker a partir do repositório oficial com o pacote docker-compose-plugin, como no guia de instalação do Docker.

  2. Criar a pasta do projeto

    Crie uma pasta por aplicação, por exemplo /opt/wordpress, e entre nela. O Compose dá ao projeto o nome desta pasta e procura compose.yaml na pasta atual.

  3. Escrever o ficheiro .env e o compose.yaml

    Gere uma palavra-passe em .env, legível apenas pelo root, e copie o ficheiro compose.yaml abaixo. No arranque, o Compose substitui ${DB_PASSWORD} pelo valor lido em .env.

  4. Iniciar a stack

    Execute docker compose up -d. O Compose transfere as imagens, cria a rede e os volumes, espera que o MariaDB esteja pronto e depois inicia o WordPress. Em seguida, docker compose ps mostra os dois serviços em Up, com (healthy) para db.

  5. Testar e ler os registos

    A partir do VPS, curl -I http://127.0.0.1:8080 deve devolver um redirecionamento para a página de instalação do WordPress. Em caso de problema, docker compose logs -f --tail=100 mostra os registos de todos os serviços.

  6. Atualizar os contentores

    Para passar a uma nova versão, altere a tag da imagem em compose.yaml e execute docker compose pull e docker compose up -d: só são recriados os contentores cuja imagem ou configuração mudou, e os volumes mantêm-se.

Criar o projeto e a sua palavra-passe

mkdir -p /opt/wordpress
cd /opt/wordpress
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env

Ficheiro compose.yaml: WordPress e MariaDB

services:
  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: "1"
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:6.8-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - wp_data:/var/www/html

volumes:
  db_data:
  wp_data:

Iniciar e verificar

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs -f --tail=100

Comandos do Docker Compose do dia a dia

docker compose ps
docker compose logs --tail=50 wordpress
docker compose restart wordpress
docker compose exec db sh
docker compose stop
docker compose start
docker compose down
docker compose config --quiet
docker compose ls

Atualizar as imagens

cd /opt/wordpress
docker compose pull
docker compose up -d
docker image prune -f

Fazer cópia da base de dados MariaDB

cd /opt/wordpress
docker compose exec -T db sh -c 'mariadb-dump -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > wordpress-$(date +%F).sql

HTTPS com Caddy: compose.override.yaml

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Caddyfile

example.com {
    reverse_proxy wordpress:80
}

Antes de começar

Precisa de um VPS Linux com o Docker Engine e o plugin Compose, instalados a partir do repositório oficial do Docker: siga o guia « Como instalar o Docker no Debian 12 ou Ubuntu 24.04? » se ainda não o fez. Os comandos são executados como root; uma conta do grupo docker também os pode executar sem sudo.

  • O Compose v2 escreve-se docker compose, com um espaço. O antigo programa docker-compose (v1) deixou de ser mantido em 2023: não o instale nem com pip nem com apt.
  • O ficheiro chama-se compose.yaml; docker-compose.yml continua a ser lido nos projetos antigos. A linha version: no início do ficheiro está obsoleta e já não serve para nada.
  • O WordPress e o MariaDB cabem em 1 a 2 GB de RAM; preveja mais assim que várias stacks correrem no mesmo VPS.

Compreender o ficheiro compose.yaml

Cada entrada de services torna-se um contentor. O Compose cria também uma rede privada para o projeto: os serviços comunicam nela pelo nome, daí WORDPRESS_DB_HOST: db. Nenhuma porta do MariaDB é publicada, por isso a base de dados fica invisível a partir da Internet.

  • image: a imagem e a sua tag. Fixe uma versão (mariadb:11.4) em vez de latest para saber o que está a atualizar.
  • ports: "127.0.0.1:8080:80" publica a porta 80 do contentor na porta 8080 do VPS, apenas em local. Sem 127.0.0.1, a porta fica aberta à Internet, mesmo que o UFW a bloqueie.
  • volumes: um volume com nome (db_data) conserva os dados quando o contentor é recriado. Só é apagado por docker compose down -v ou docker volume rm.
  • environment e .env: os segredos ficam em .env, fora do ficheiro que partilha ou coloca sob controlo de versões.
  • restart: unless-stopped volta a iniciar os contentores após uma falha ou um reinício do VPS, exceto os que parou manualmente.
  • depends_on com condition: service_healthy espera que o healthcheck do MariaDB seja bem-sucedido antes de iniciar o WordPress.

Colocar o site online em HTTPS

Para servir o site num nome de domínio, aponte um registo A para o IPv4 do VPS, abra as portas 80 e 443 e adicione o Caddy num ficheiro compose.override.yaml, que o Compose lê automaticamente juntamente com o compose.yaml. Substitua example.com pelo seu domínio no Caddyfile: o Caddy obtém e renova sozinho o certificado Let’s Encrypt.

Depois, conclua a instalação do WordPress a partir do endereço https do seu domínio, não a partir de 127.0.0.1: o WordPress guarda o endereço usado durante a instalação.

Cópias de segurança e atualizações da stack

Um volume não é uma cópia de segurança: desaparece com o VPS ou com um down -v executado por engano. Exporte a base de dados com mariadb-dump (bloco acima), copie a pasta do projeto e o conteúdo dos volumes e envie tudo para fora do VPS.

  • docker compose pull transfere as novas imagens das tags indicadas, docker compose up -d recria os contentores afetados e docker image prune -f liberta o espaço das imagens antigas.
  • Antes de mudar de versão principal do MariaDB ou do PostgreSQL, faça uma exportação SQL: a nova versão pode exigir uma migração dos dados.
  • docker system df indica o espaço ocupado pelas imagens, pelos contentores e pelos volumes.

Que VPS escolher para o Docker Compose?

O Docker precisa de um verdadeiro kernel Linux: um VPS KVM serve, um alojamento partilhado não. Na ACLClouds, a 16 de novembro de 2026, o VPS Mini (2 vCPU, 8 GB de RAM, 40 GB de armazenamento) custa 4,99 € por mês sem fidelização, ou 3,99 € por mês com um compromisso de um ano: corre várias stacks Compose pequenas. O VPS Essentiel (4 vCPU, 16 GB de RAM, 80 GB), a 9,99 € por mês, é adequado a uma base de dados com muita carga ou ao n8n ao lado de um site.

A opção -v de docker compose down apaga os dados

docker compose down -v apaga também os volumes com nome do projeto, ou seja, a base de dados MariaDB e os ficheiros do WordPress. Faça uma exportação antes de qualquer comando com -v.

Verificação rápida

  • docker compose version responde sem erros.
  • docker compose ps mostra db em (healthy) e wordpress em Up.
  • A porta 8080 só está publicada em 127.0.0.1.
  • .env está no modo 600 e não está em nenhum repositório Git.
  • Uma exportação SQL recente está guardada fora do VPS.

Perguntas frequentes

Porque aparece no configuration file provided: not found?

O Compose não encontra nem compose.yaml nem docker-compose.yml na pasta atual. Entre na pasta do projeto com cd /opt/wordpress, ou indique o ficheiro com docker compose -f /opt/wordpress/compose.yaml up -d.

O Compose mostra « the attribute version is obsolete »: é grave?

Não, é apenas um aviso. O Compose v2 ignora a linha version: "3.8" no início do ficheiro: apague-a para o aviso desaparecer, o resto do ficheiro não muda.

Porque aparece port is already allocated ou address already in use no arranque?

Outro contentor já publica essa porta, ou um serviço do VPS (nginx, Apache) está à escuta nela. Encontre-o com docker ps --filter publish=80 e ss -tlnp | grep :80, e depois pare-o ou altere a porta da esquerda em ports, por exemplo "8081:80".

Porque aparece docker: 'compose' is not a docker command?

O plugin Compose v2 não está instalado. Com o repositório oficial do Docker, execute apt install docker-compose-plugin. Os pacotes docker.io e docker-compose das distribuições estão desatualizados ou só fornecem o antigo comando com hífen.

Porque é que as minhas alterações ao compose.yaml não são aplicadas?

docker compose restart reinicia os contentores sem voltar a ler o ficheiro. Execute docker compose up -d: o Compose compara a configuração e recria os serviços alterados. Verifique primeiro o ficheiro com docker compose config.

Os meus dados desapareceram depois de docker compose down?

Não: docker compose down remove os contentores e a rede, não os volumes com nome. Os dados só desaparecem com down -v, ou se eram escritos no contentor sem volume. docker volume ls lista os volumes, com o nome do projeto como prefixo, por exemplo wordpress_db_data.

O que corrigir depois de yaml: line 8: mapping values are not allowed in this context?

O ficheiro YAML está mal indentado: uma tabulação em vez de espaços, ou um nível desalinhado. Use apenas espaços (dois por nível), coloque entre aspas os valores que contêm :, como as portas, e verifique com docker compose config.