Primeiros passos

Guia de Deploy

Do zero até um painel administrativo de WireGuard VPN funcional em menos de cinco minutos.

Pré-requisitos

  • Um servidor Linux acessível a partir de onde você vai administrá-lo
  • Docker e Docker Compose instalados
  • Um nome de domínio apontando para o IP do seu servidor
  • Portas 80 e 443 abertas para o Caddy, além da porta UDP do WireGuard aberta (padrão 51820)

O Caddy precisa de um nome DNS válido, interno ou público, apontando para o seu servidor para conseguir obter e renovar certificados SSL automaticamente.

Deploy

mkdir wireguard_webadmin && cd wireguard_webadmin
wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Crie um arquivo .env no mesmo diretório. Defina SERVER_ADDRESS com o seu domínio:

SERVER_ADDRESS=vpn.example.com
DEBUG_MODE=False
TIMEZONE=America/Sao_Paulo

Veja abaixo a referência do .env com todas as variáveis disponíveis.

docker compose up -d

Acesse o painel em https://vpn.example.com. O Caddy obtém e renova certificados SSL automaticamente.

Referência do .env

Variável Obrigatória Descrição
SERVER_ADDRESS Sim Nome DNS ou IP do seu servidor. Deve corresponder exatamente ao que você digita no navegador. Se não corresponder, ocorrerão erros de CSRF.
DEBUG_MODE Não Defina como True para ativar o modo debug do Django. Nunca use em produção. Padrão: False.
TIMEZONE Não Fuso horário da aplicação. Use um valor da base tz. Padrão: America/Sao_Paulo.
EXTRA_ALLOWED_HOSTS Não Hosts adicionais que o Django deve aceitar, separados por vírgula. SERVER_ADDRESS sempre é incluído. Exemplo: app1.example.com,app2.example.com:8443.
WIREGUARD_STATUS_CACHE_ENABLED Não Armazena o status do WireGuard em cache para reduzir chamadas ao wg. Padrão: True.
WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL Não Com que frequência o cache é atualizado, em segundos. Valores permitidos: 30, 60, 150, 300. Padrão: 60.
WIREGUARD_STATUS_CACHE_WEB_LOAD_PREVIOUS_COUNT Não Quantos snapshots em cache devem ser pré-carregados ao abrir a página (0-9). Valores mais altos preenchem os gráficos de tráfego antes. Reduza se a lista de peers parecer lenta. Padrão: 9.
DISABLE_AUTO_APPLY Não Desativa a aplicação automática das alterações de configuração do WireGuard e do DNS. Por padrão, mudanças em peers e DNS são aplicadas imediatamente. Defina como true para aplicar as alterações manualmente. Padrão: false.
WIREGUARD_MTU Não MTU personalizado para interfaces WireGuard (servidor e clientes). Altere somente se souber o que está fazendo. Deve ser um inteiro entre 1280 e 9000. Após alterar, reexporte e redistribua todos os arquivos de configuração dos clientes — MTU divergente entre servidor e clientes pode causar problemas de conectividade. Padrão: 1420.
VPN_CLIENTS_CAN_ACCESS_DJANGO Não Permite que clientes VPN acessem a interface web diretamente pela interface interna em http://ip_ou_hostname:8000. Quando habilitado, o endereço interno incluindo a porta :8000 deve ser adicionado a EXTRA_ALLOWED_HOSTS, caso contrário o Django bloqueará a requisição. Padrão: False.

Atualização

Os dados ficam persistidos em volumes Docker. Atualizar não afeta seus peers, regras de firewall, entradas DNS nem qualquer outra configuração.

01
Entre no diretório do projeto
cd wireguard_webadmin
02
Pare os serviços e baixe as imagens mais recentes
docker compose down
docker compose pull
03
Faça backup dos seus dados
tar cvfz wireguard-webadmin-backup-$(date +%Y-%m-%d-%H%M%S).tar.gz \
  /var/lib/docker/volumes/wireguard_webadmin_wireguard/_data/ \
  /var/lib/docker/volumes/wireguard_webadmin_rrd_data/_data/
04
Atualize o arquivo compose
wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml
05
Suba a stack atualizada
docker compose up -d
06
Verifique os logs em busca de erros inesperados
docker compose logs wireguard_webadmin

Solução de problemas

O Caddy não está obtendo certificado

  • Confirme que o registro A do domínio aponta para o IP público do servidor
  • Verifique se as portas 80 e 443 estão abertas e não bloqueadas na rede
  • Consulte os logs do Caddy: docker compose logs caddy

O painel não carrega

  • Verifique se todos os containers estão em execução: docker compose ps
  • Procure por erros: docker compose logs wireguard_webadmin
  • Confirme que SERVER_ADDRESS em .env corresponde exatamente ao que você digita no navegador

Erros de CSRF no login

SERVER_ADDRESS está configurado incorretamente. Ele precisa corresponder ao hostname, e à porta se não for a padrão, usado para acessar o painel. Atualize o .env e reinicie com docker compose up -d.

Os peers do WireGuard não conseguem se conectar

  • Confirme que a porta UDP do WireGuard está aberta no firewall do host. O padrão é 51820, mas se você estiver executando múltiplas instâncias cada uma precisa de sua própria porta.
  • Garanta que o intervalo de portas UDP declarado em docker-compose.yml corresponda ao que está configurado em cada instância do WireGuard dentro do painel. Se houver divergência, o container não exporá a porta correta no host.
  • Verifique se o IP forwarding está habilitado no host: sysctl net.ipv4.ip_forward

O que está rodando

ServiçoFunção
wireguard-webadminAplicação Django: interface web e API
caddyProxy reverso e TLS automático
auth-gatewayCamada de autorização Zero Trust: aplica verificações de identidade antes de encaminhar para o upstream
cronTarefas agendadas: ativação/desativação de peers e atualização de cache
rrdtoolHistórico de tráfego: coleta de dados RRD e geração de gráficos
dnsResolvedor baseado em dnsmasq com suporte a listas de bloqueio por categoria