wg-easy (2026): auto-hospedar o WireGuard com interface web em minutos

Aviso de afiliação — Este guia liga à Contabo, o VPS onde corremos o nosso próprio WireGuard auto-hospedado. 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 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.

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. Corremos o nosso na Contabo 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 →

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

Esta é a implementação moderna do wg-easy. Substitua WG_HOST pelo IP público ou nome de anfitrião do seu servidor, e defina uma palavra-passe de administração forte (a secção seguinte explica a exigência de hash a partir da v14):

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:latest
    container_name: wg-easy
    environment:
      - WG_HOST=ip.publico.do.seu.servidor
      - PASSWORD_HASH=$2a$12$SUBSTITUA_PELO_SEU_HASH_BCRYPT
      - WG_DEFAULT_DNS=1.1.1.1
    volumes:
      - ./etc_wireguard:/etc/wireguard
    ports:
      - "51820:51820/udp"   # dados WireGuard — aberto à Internet
      - "51821:51821/tcp"   # interface web — limite APENAS ao SEU IP
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

Três coisas fazem o trabalho real e são os pontos de falha habituais:

• cap_add: NET_ADMIN permite ao contentor gerir a interface WireGuard. Sem ela, o contentor arranca mas não consegue levantar o túnel.
• sysctls: net.ipv4.ip_forward=1 transforma a máquina num router. Sem isto, o túnel liga e depois não encaminha nada — o clássico «ligado mas sem Internet».
• volumes persiste chaves e clientes no anfitrião, para que um docker compose down && up não apague todos os dispositivos.

Levante-o com docker compose up -d, depois abra http://IP_DO_SEU_SERVIDOR:51821 e inicie sessão.

A mudança de palavra-passe que parte as atualizações

É o maior obstáculo de 2026. O antigo wg-easy usava uma variável de ambiente PASSWORD em texto simples. As versões recentes (v14 e seguintes) removeram o PASSWORD em texto simples e agora exigem um hash bcrypt em PASSWORD_HASH. Se copiar a linha PASSWORD=segredo de um tutorial antigo para uma imagem atual, o contentor recusará o início de sessão ou não arrancará, e vai jurar que a documentação está errada.

Gere o hash com a própria imagem para nunca colar uma palavra-passe em texto simples no histórico da shell:

docker run --rm ghcr.io/wg-easy/wg-easy wgpw 'a-sua-palavra-passe-forte'
# imprime: PASSWORD_HASH=$2a$12$....

Copie o valor $2a$12$... completo para o ficheiro compose. Note que os caracteres $ têm de ser escapados (duplicados como $$) se colocar o hash num ficheiro .env que o Compose interpola — esse erro de escape é a segunda queixa mais comum a seguir à mudança de nome da variável.

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.

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. Use uma palavra-passe forte e com hash. A exigência PASSWORD_HASH existe por isto. Trate-a 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.

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.

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 WG_DEFAULT_DNS 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.