wg-easy v15 (2026): instalação com Docker Compose e painel blindado

Aviso de afiliação - Este guia liga à Contabo, o fornecedor de VPS que usa como exemplo. Se encomendar através do nosso link, ganhamos uma comissão sem custo adicional para si. Cada comando abaixo está documentado a partir do projeto oficial wg-easy e escrito para ser reproduzível na sua própria máquina. O link da Ultahost proposto como segundo fornecedor é um link de afiliado nas mesmas condições.

O wg-easy é uma imagem Docker gratuita que executa o WireGuard com um painel de administração web no seu próprio servidor: adiciona dispositivos, descarrega as configurações e mostra códigos QR no navegador em vez de editar wg0.conf. A versão 15 é a atual; precisa de um VPS com a porta UDP 51820 aberta. Este guia usa um Cloud VPS da Contabo como servidor de exemplo.

Ainda não escolheu o servidor? A nossa classificação dos VPS mais baratos para WireGuard compara o que cada fornecedor cobra de facto por um servidor utilizável.

O WireGuard é rápido e moderno, mas a instalação padrão são ficheiros e linha de comandos: gerar chaves, editar wg0.conf à mão, executar wg set por cada dispositivo, andar a mover configurações. Para um dispositivo, tudo bem. Para uma família, alguns portáteis e dois telemóveis, torna-se aborrecido - e é no aborrecido que surgem os erros (e as chaves que vazam). O wg-easy resolve exatamente isto: mantém o WireGuard real por baixo, intacto, e acopla-lhe um painel web limpo. Adicionar um cliente em dois cliques, mostrar um código QR para um telemóvel, ver quem está ligado e quanto transfere. Esta é a instalação completa de 2026, incluindo a mudança de palavra-passe que faz tropeçar toda a gente que atualiza.

Dica: se o túnel não liga, a causa é quase sempre a porta. Veja o nosso guia sobre a porta padrão do WireGuard (UDP 51820) e como abri-la, encaminhá-la ou alterá-la.

Sem copiar e colar: o gerador docker-compose do wg-easy, gratuito, escreve o docker-compose.yml da v15 para a sua instalação no navegador: painel de administração só em localhost ou em HTTPS no seu próprio domínio através do Caddy, e um primeiro arranque automático opcional.

# wg-easy v15 - generated on vpnsmith.com/en/tools/wg-easy-compose-generator
# Host: vpn.example.com - WireGuard port: 51820/udp - panel: https://wg.example.com

volumes:
  etc_wireguard:
  caddy_data:
  caddy_config:

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - PORT=80
      - TRUSTED_PROXIES=10.42.42.43,fdcc:ad94:bacf:61a3::2b
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"   # WireGuard: the only port clients need
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

  caddy:
    image: caddy:2-alpine
    container_name: caddy
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    networks:
      wg:
        ipv4_address: 10.42.42.43
        ipv6_address: fdcc:ad94:bacf:61a3::2b
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

wg.example.com {
	reverse_proxy wg-easy:80
}

# 1. Firewall: primeiro SSH, depois a porta do WireGuard
sudo ufw allow OpenSSH
sudo ufw allow 51820/udp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw enable
# Atenção: as portas publicadas pelo Docker contornam o ufw. Abra/feche-as também na firewall do fornecedor.

# 2. Crie a pasta e cole o ou os ficheiros gerados
sudo mkdir -p /etc/docker/containers/wg-easy
cd /etc/docker/containers/wg-easy
sudo nano docker-compose.yml
sudo nano Caddyfile

# 3. Arranque o wg-easy
sudo docker compose up -d
# Acompanhe os registos (Ctrl+C para sair)
sudo docker compose logs -f wg-easy

# 4. Abra o painel: https://wg.example.com

O que o wg-easy é de facto (e o que não é)

O wg-easy é um único contentor Docker que corre um servidor WireGuard e uma pequena aplicação web para o gerir. O importante a perceber já: não substitui nem reimplementa o WireGuard. O túnel continua a ser o mesmo WireGuard do núcleo, com as mesmas chaves e o mesmo protocolo no fio. O wg-easy é gestão, não uma VPN nova. Duas consequências:

• Sem penalização de velocidade. O débito e a latência são idênticos a uma configuração escrita à mão, porque o caminho dos dados nunca toca na aplicação web.
• A interface web é a superfície de ataque. O painel pode criar clientes, portanto quem o controla controla a sua VPN. Proteger esse painel é toda a história da segurança (mais abaixo).

O que recebe em troca: uma página de navegador que lista cada cliente, criar/desativar/eliminar a um clique, um código QR por cliente para os telemóveis e um contador de transferência ao vivo por par. Para integrar um punhado de dispositivos sem tocar no terminal, nada é mais rápido.

Antes de começar: o anfitrião de que precisa

O wg-easy é um contentor, por isso precisa de um anfitrião Linux capaz de correr Docker e com um IP público. Para uma VPN acessível de qualquer lugar, isso significa um VPS pequeno - o WireGuard é tão leve que uma instância de 4-6 €/mês satura a sua porta de rede muito antes de a CPU dar por isso. A Contabo serve aqui de exemplo pela relação preço/largura de banda, e o procedimento bare-metal está no nosso guia de WireGuard auto-hospedado na Contabo caso queira comparar com a via manual.

Obtém um VPS Contabo para correr o wg-easy →

Uma segunda opção se preferir um prazo de reembolso de 30 dias: o VPS Basic da Ultahost, lido em ultahost.com a 21 de outubro de 2026 a 5,52 $ por mês faturados por 24 meses (preço de tabela 9,19 $), com 1 núcleo de CPU, 1 GB de DDR5, 30 GB NVMe, um IPv4 dedicado e garantia de reembolso de 30 dias. 1 GB chega para o Docker e o contentor wg-easy numa VPN pessoal. O plano não publica velocidade de porta nem volume de tráfego, confirme-os antes de contar com ele para uso intensivo.

No anfitrião precisa do Docker e do plugin Compose instalados, do módulo de núcleo do WireGuard disponível (toda a distro moderna, Linux 5.6+, traz-no) e da capacidade de abrir o UDP 51820 tanto na firewall do anfitrião como no grupo de segurança do seu fornecedor.

O ficheiro docker-compose (wg-easy v15)

Verificação de versão (24 de outubro de 2026): a versão atual é a v15.5.0 (24 de outubro de 2026). A v15 é uma reescrita completa: WG_HOST, PASSWORD_HASH e a maioria das outras variáveis da v14 desapareceram, e as suas definições estão agora na interface web. Um tutorial v14 colado sobre a imagem :latest arranca um contentor que ignora em silêncio o host e a palavra-passe. Tudo o que se segue é o método v15, retirado do ficheiro compose e da documentação do projeto.

A v15.5.0 num minuto: inclui as correções de segurança do Node.js de outubro de 2026, por isso atualize mesmo que tudo funcione: sudo docker compose pull && sudo docker compose up -d (a etiqueta :15 usada abaixo segue a nova versão, e os seus clientes e chaves ficam no volume). Passa também o suporte integrado ao AmneziaWG para a versão 3.1, acrescenta WG_INTERFACE (por omissão wg0) para correr duas instâncias no mesmo host e TRUSTED_PROXIES para um painel atrás de um proxy reverso (ver a secção sobre proteção). Fonte: notas da versão v15.5.0 e documentação de configuração opcional do projeto.

Este ficheiro segue o oficial, com uma alteração deliberada: a interface web só é publicada em 127.0.0.1, por isso o painel de administração nunca é acessível a partir da Internet e abre-o através de um túnel SSH. Quer um painel HTTPS no seu próprio domínio com o Caddy, ou um primeiro arranque totalmente automático? O nosso gerador docker-compose para wg-easy escreve essa variante por si.

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    environment:
      - INSECURE=true   # panel over plain HTTP, reached only through an SSH tunnel
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"             # WireGuard data: open to the internet
      - "127.0.0.1:51821:51821/tcp"   # web UI: bound to localhost only
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

volumes:
  etc_wireguard:

O que faz cada parte, e onde costuma falhar:

• 127.0.0.1:51821:51821/tcp mantém o painel fora da interface pública. Importa mais do que parece: as portas publicadas pelo Docker contornam o UFW, por isso um simples "51821:51821/tcp" fica aberto ao mundo mesmo que ufw status diga o contrário.
• INSECURE=true é necessário porque aqui o painel é servido em HTTP simples (a cifra é o túnel SSH). Sem ele, a v15 marca o cookie de sessão como Secure, o navegador descarta-o em HTTP e volta à página de login a cada tentativa.
• cap_add: NET_ADMIN e sysctls: net.ipv4.ip_forward=1 permitem ao contentor criar a interface WireGuard e encaminhar para os seus clientes. Se faltar um deles, o túnel liga e depois não encaminha nada.
• O volume com nome etc_wireguard guarda a base de dados com todas as chaves e clientes, por isso um docker compose down seguido de up mantém os seus dispositivos.

Coloque-o no sítio e arranque-o, com a estrutura de pastas da documentação oficial:

sudo mkdir -p /etc/docker/containers/wg-easy
cd /etc/docker/containers/wg-easy
sudo nano docker-compose.yml   # paste the file above
sudo docker compose up -d
sudo docker compose logs -f wg-easy   # Ctrl+C once it is listening

Depois abra o painel a partir do seu próprio computador, através do túnel:

# on your own computer, not on the server
ssh -L 51821:127.0.0.1:51821 user@YOUR_SERVER_IP
# then open http://localhost:51821 in your browser

Primeiro arranque: o assistente de configuração (adeus PASSWORD_HASH)

O PASSWORD_HASH bcrypt e o comando wgpw, a que todos os tutoriais v14 dedicam uma secção, já não existem. Na primeira visita, a v15 abre um assistente:

1. Crie a conta de administração: um nome de utilizador e uma palavra-passe. O wg-easy guarda ele próprio a palavra-passe como hash argon2, por isso não há nada para gerar nem para escapar num ficheiro .env.
2. «Tem uma configuração existente?» Responda Não numa instalação nova (Sim é a importação da v14, mais abaixo).
3. Host e porta: o IP público ou o domínio a que os seus clientes vão ligar (um endereço IPv6 vai entre parênteses retos, como [2001:db8::1]) e a porta UDP, 51820 salvo se alterou o mapeamento. Os clientes recebem exatamente esse valor como Endpoint.

O DNS, a gama de endereços dos clientes e os allowed IPs por omissão definem-se agora no painel de administração, já não em variáveis de ambiente. Para saltar o assistente (Ansible, cloud-init), a v15 lê INIT_ENABLED=true com INIT_USERNAME, INIT_PASSWORD, INIT_HOST e INIT_PORT apenas no primeiro arranque; remova-as quando o contentor estiver a correr para que a palavra-passe não fique no ficheiro. O gerador pode escrever essas linhas por si.

Sem acesso? Reponha a palavra-passe de administração a partir do servidor:

cd /etc/docker/containers/wg-easy
sudo docker compose exec -it wg-easy cli db:admin:reset

Se vem da v14

Não existe atualização no local. No painel antigo, clique em Backup para descarregar wg0.json e anote as antigas variáveis de ambiente, execute docker compose down, arranque o ficheiro v15 acima, responda Sim no assistente e carregue wg0.json: as chaves e os clientes passam, as variáveis antigas não, por isso volte a definir DNS e allowed IPs no painel de administração. Um limite firme do guia de migração: os anfitriões armv6 e armv7 (Raspberry Pi mais antigos) não podem passar para a v15 e têm de ficar fixados em :14.

Fica na v14 ou deixa o painel? O mesmo ficheiro de backup pode ser colado no WireGuard Manager, o nosso painel alojado (grátis para 1 servidor e 3 peers): como o wg0.json contém a chave privada de cada cliente, o .conf e o código QR de cada dispositivo ficam de novo disponíveis de imediato, e gera um wg0.conf normal para o wg-quick se retirar o wg-easy. A importação não altera nada no servidor.

Adicione o seu primeiro cliente

No painel, clique em New Client, dê-lhe um nome (ex. portatil, telemovel-pixel), e o wg-easy gera o par de chaves e uma configuração pronta. Para um computador, descarregue o .conf e importe-o na aplicação WireGuard ou nos modelos de configuração; para um telemóvel, clique no ícone QR e digitalize-o com a app móvel do WireGuard - sem escrever, sem transferir ficheiros. O interruptor por cliente desativa um dispositivo de imediato sem o apagar, que é a forma correta de revogar um telemóvel perdido.

Cliente importado mas nada funciona? Três causas cobrem quase todos os casos, e cada uma tem a sua ferramenta. O estado continua sem handshake: a porta UDP 51820 não chega ao contentor, use o verificador de porta WireGuard, que escreve a regra de firewall do seu anfitrião (ufw, firewalld, nftables, iptables) e um teste tcpdump que mostra se os pacotes chegam. Handshake correto mas páginas que bloqueiam ou carregam a meio: um problema de MTU, que a calculadora de MTU dimensiona para a sua ligação (coloque o valor na config do cliente). Quer que só parte do tráfego passe pelo túnel, ou manter o acesso à rede de casa: a calculadora AllowedIPs dá a lista exata para colar nos allowed IPs por omissão do wg-easy.

Blindar o painel de administração - faça-o já, não depois

A interface web pode criar clientes VPN, por isso um painel exposto e mal protegido é o verdadeiro perigo do wg-easy. Três camadas, por ordem de preferência:

1. Nunca publique a 51821 na Internet. Na firewall do seu fornecedor de VPS, deixe o UDP 51820 aberto e mantenha o TCP 51821 fechado ao mundo. Alcance o painel apenas a partir do seu IP, ou - o mais limpo - ligue-se primeiro à VPN e abra o painel através do túnel, para que a porta de administração nunca fique virada para a Internet.

2. Palavra-passe forte e depois 2FA. A v15 oferece login de dois fatores TOTP: abra o menu no canto superior direito, depois Account, ative a autenticação de dois fatores e leia o código QR com a sua app de autenticação. Trate o acesso ao painel como uma palavra-passe de root.

3. Coloque TLS à frente se tiver mesmo de a alcançar remotamente: um proxy reverso (Caddy, Traefik, nginx) a terminar HTTPS com um certificado real, idealmente com lista de permissões. HTTP em texto simples numa porta pública é a única configuração a evitar.

   Desde a v15.5.0, defina também TRUSTED_PROXIES com o endereço de origem do seu proxy (para um contentor Caddy na mesma rede Docker, o IP dele nessa rede). O wg-easy passa a ler X-Forwarded-Host e X-Forwarded-For apenas desse endereço, e as tentativas de login falhadas ficam registadas com o IP real do cliente: uma ferramenta como o CrowdSec bloqueia o atacante e não o seu proxy. Um endereço mal escrito impede o contentor de arrancar: verifique docker compose logs depois da alteração.

Uma VPN auto-hospedada à qual qualquer transeunte se pode adicionar é pior do que nenhuma VPN. O painel são as chaves do reino - proteja-o em conformidade.

wg-easy face às alternativas

• vs PiVPN - O PiVPN instala o WireGuard diretamente no anfitrião e gere os pares a partir do terminal (pivpn add, pivpn -qr). Sem contentor, sem interface web. Escolha o PiVPN para uma máquina bare-metal enxuta e scriptável; escolha o wg-easy quando quiser mesmo um painel clicável e estatísticas ao vivo.
• vs uma configuração à mão - Editar o wg0.conf por si é a opção mais transparente e leve, ideal para uma máquina VPN de propósito único e para a infraestrutura como código. O wg-easy troca um pouco de superfície extra (a app web) por uma gestão de clientes rápida e sem CLI.
• vs outras stacks auto-hospedadas - Se quer uma mesh (cada dispositivo a falar diretamente, com a travessia de NAT tratada por si) em vez de um servidor clássico em estrela, o wg-easy tem a forma errada; esse é o terreno do Tailscale/Headscale/NetBird, comparado no nosso guia da melhor VPN auto-hospedada.

O wg-easy também corre lindamente ao lado de outros contentores, razão pela qual combina naturalmente com uma instalação de WireGuard em Docker mais ampla.

Quando o wg-easy é a escolha certa - e quando não é

Use o wg-easy quando integra várias pessoas ou dispositivos, quer a configuração do telemóvel por QR, gosta de ver o estado da ligação ao vivo, ou simplesmente prefere um painel a um ficheiro de configuração. Transforma «configurar um cliente VPN» de uma tarefa de CLI de cinco minutos em dois cliques.

Dispense o wg-easy quando a máquina não faz mais do que servir um ou dois pares WireGuard (uma configuração à mão é mais simples e tem uma peça móvel a menos), quando não consegue manter em segurança a porta de administração fora da Internet, ou quando na verdade quer uma mesh e não um servidor. Para todos os outros, o wg-easy é o caminho honesto mais rápido de um VPS novo para uma VPN WireGuard funcional e gerível.

Para ter o essencial à mão: a WireGuard Cheat Sheet gratuita (PDF de 5 páginas em inglês, download direto, sem registo) reúne as tabelas de keepalive e MTU, os comandos wg genkey/wg pubkey/wg genpsk e as quatro verificações de servidor numa linha a correr primeiro quando um túnel não passa tráfego. O WireGuard Self-Hosting Kit pago (9 USD, em inglês) acrescenta uma checklist de diagnóstico com 12 causas e 11 modelos de configuração, entre eles um para wg-easy.

Uma VPN muda o seu IP. Não muda o seu navegador.

Um túnel substitui o endereço que um serviço vê. Não altera nada do que o seu navegador anuncia por conta própria - tipos de letra, ecrã, fuso horário, pilha gráfica - e essa combinação costuma bastar para o reconhecer de uma sessão para a outra.

Meça a sua impressão digital de navegador - medição passiva, sem perguntas, sem conta, sem e-mail.

A limitação honesta

O wg-easy torna o WireGuard mais fácil de gerir, não mais privado nem mais seguro do que o WireGuard já é. Partilha o núcleo do anfitrião, corre com NET_ADMIN, e está tão blindado quanto o anfitrião e o painel de administração que coloca à frente. Não audita os seus clientes, não impede sozinho as fugas de DNS (defina o DNS no painel de administração e verifique), e não o protege se deixar a 51821 aberta. Trate-o como uma camada de conveniência sobre o WireGuard real: implemente-o, reforce o anfitrião e o painel, mantenha a porta de dados pública e a de administração privada - e terá uma VPN auto-hospedada que pode mesmo operar para um lar inteiro sem viver no terminal.