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ávelObrigatóriaDescrição
SERVER_ADDRESSSimNome 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_MODENãoDefina como True para ativar o modo debug do Django. Nunca use em produção. Padrão: False.
TIMEZONENãoFuso horário da aplicação. Use um valor da base tz. Padrão: America/Sao_Paulo.
EXTRA_ALLOWED_HOSTSNãoHosts 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_ENABLEDNãoArmazena o status do WireGuard em cache para reduzir chamadas ao wg. Padrão: True.
WIREGUARD_STATUS_CACHE_REFRESH_INTERVALNãoCom que frequência o cache é atualizado, em segundos. Valores permitidos: 30, 60, 150, 300. Padrão: 60.
WIREGUARD_STATUS_CACHE_WEB_LOAD_PREVIOUS_COUNTNãoQuantos 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.

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