<pclass="section-sub"style="margin-top:1rem">Do zero até um painel administrativo de WireGuard VPN funcional em menos de cinco minutos.</p>
</div>
</section>
<divclass="page-content">
<divclass="container">
<h2id="pré-requisitos">Pré-requisitos</h2>
<ul>
<li>Um servidor Linux acessível a partir de onde você vai administrá-lo</li>
<li><ahref="https://docs.docker.com/engine/install/">Docker</a> e <ahref="https://docs.docker.com/compose/install/">Docker Compose</a> instalados</li>
<li>Um nome de domínio apontando para o IP do seu servidor</li>
<li>Portas <strong>80</strong> e <strong>443</strong> abertas para o Caddy, além da porta UDP do WireGuard aberta (padrão <strong>51820</strong>)</li>
</ul>
<divclass="callout">
<p><strong>O Caddy precisa de um nome DNS válido</strong>, interno ou público, apontando para o seu servidor para conseguir obter e renovar certificados SSL automaticamente.</p>
<p>Veja abaixo a <ahref="#env-reference">referência do .env</a> com todas as variáveis disponíveis.</p>
</div>
<divclass="tab-panel"id="dep-step-4">
<pre><code>docker compose up -d</code></pre>
<p>Acesse o painel em <code>https://vpn.example.com</code>. O Caddy obtém e renova certificados SSL automaticamente.</p>
</div>
</div>
</div>
<hr>
<h2id="env-reference">Referência do .env</h2>
<tableclass="env-table">
<thead>
<tr>
<th>Variável</th>
<th>Obrigatória</th>
<th>Descrição</th>
</tr>
</thead>
<tbody>
<tr>
<td>SERVER_ADDRESS</td>
<td>Sim</td>
<td>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.</td>
</tr>
<tr>
<td>DEBUG_MODE</td>
<td>Não</td>
<td>Defina como <code>True</code> para ativar o modo debug do Django. Nunca use em produção. Padrão: <code>False</code>.</td>
</tr>
<tr>
<td>TIMEZONE</td>
<td>Não</td>
<td>Fuso horário da aplicação. Use um valor da <ahref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"target="_blank"rel="noopener">base tz</a>. Padrão: <code>America/Sao_Paulo</code>.</td>
</tr>
<tr>
<td>EXTRA_ALLOWED_HOSTS</td>
<td>Não</td>
<td>Hosts adicionais que o Django deve aceitar, separados por vírgula. <code>SERVER_ADDRESS</code> sempre é incluído. Exemplo: <code>app1.example.com,app2.example.com:8443</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_ENABLED</td>
<td>Não</td>
<td>Armazena o status do WireGuard em cache para reduzir chamadas ao <code>wg</code>. Padrão: <code>True</code>.</td>
</tr>
<tr>
<td>WIREGUARD_STATUS_CACHE_REFRESH_INTERVAL</td>
<td>Não</td>
<td>Com que frequência o cache é atualizado, em segundos. Valores permitidos: <code>30</code>, <code>60</code>, <code>150</code>, <code>300</code>. Padrão: <code>60</code>.</td>
<td>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: <code>9</code>.</td>
</tr>
<tr>
<td>DISABLE_AUTO_APPLY</td>
<td>Não</td>
<td>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 <code>true</code> para aplicar as alterações manualmente. Padrão: <code>false</code>.</td>
</tr>
<tr>
<td>WIREGUARD_MTU</td>
<td>Não</td>
<td>MTU personalizado para interfaces WireGuard (servidor e clientes). Altere somente se souber o que está fazendo. Deve ser um inteiro entre <code>1280</code> e <code>9000</code>. 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: <code>1420</code>.</td>
</tr>
<tr>
<td>VPN_CLIENTS_CAN_ACCESS_DJANGO</td>
<td>Não</td>
<td>Permite que clientes VPN acessem a interface web diretamente pela interface interna em <code>http://ip_ou_hostname:8000</code>. Quando habilitado, o endereço interno incluindo a porta <code>:8000</code> deve ser adicionado a <code>EXTRA_ALLOWED_HOSTS</code>, caso contrário o Django bloqueará a requisição. Padrão: <code>False</code>.</td>
</tr>
</tbody>
</table>
<hr>
<h2id="atualização">Atualização</h2>
<divclass="callout green">
<p><strong>Os dados ficam persistidos em volumes Docker.</strong> Atualizar não afeta seus peers, regras de firewall, entradas DNS nem qualquer outra configuração.</p>
</div>
<divclass="deploy-steps">
<divclass="deploy-step-card">
<divclass="deploy-step-num">01</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Entre no diretório do projeto</div>
<pre><code>cd wireguard_webadmin</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">02</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Pare os serviços e baixe as imagens mais recentes</div>
<pre><code>docker compose down
docker compose pull</code></pre>
</div>
</div>
<divclass="deploy-step-card">
<divclass="deploy-step-num">03</div>
<divclass="deploy-step-body">
<divclass="deploy-step-label">Faça backup dos seus dados</div>
<h2id="solução-de-problemas">Solução de problemas</h2>
<h3id="o-caddy-não-está-obtendo-certificado">O Caddy não está obtendo certificado</h3>
<ul>
<li>Confirme que o registro A do domínio aponta para o IP público do servidor</li>
<li>Verifique se as portas 80 e 443 estão abertas e não bloqueadas na rede</li>
<li>Consulte os logs do Caddy: <code>docker compose logs caddy</code></li>
</ul>
<h3id="o-painel-não-carrega">O painel não carrega</h3>
<ul>
<li>Verifique se todos os containers estão em execução: <code>docker compose ps</code></li>
<li>Procure por erros: <code>docker compose logs wireguard_webadmin</code></li>
<li>Confirme que <code>SERVER_ADDRESS</code> em <code>.env</code> corresponde exatamente ao que você digita no navegador</li>
</ul>
<h3id="erros-de-csrf-no-login">Erros de CSRF no login</h3>
<p><code>SERVER_ADDRESS</code> está configurado incorretamente. Ele precisa corresponder ao hostname, e à porta se não for a padrão, usado para acessar o painel. Atualize o <code>.env</code> e reinicie com <code>docker compose up -d</code>.</p>
<h3id="os-peers-do-wireguard-não-conseguem-se-conectar">Os peers do WireGuard não conseguem se conectar</h3>
<ul>
<li>Confirme que a porta UDP do WireGuard está aberta no firewall do host. O padrão é <strong>51820</strong>, mas se você estiver executando múltiplas instâncias cada uma precisa de sua própria porta.</li>
<li>Garanta que o intervalo de portas UDP declarado em <code>docker-compose.yml</code> 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.</li>
<li>Verifique se o IP forwarding está habilitado no host: <code>sysctl net.ipv4.ip_forward</code></li>
</ul>
<hr>
<h2id="o-que-está-rodando">O que está rodando</h2>
<tableclass="env-table">
<thead>
<tr><th>Serviço</th><th>Função</th></tr>
</thead>
<tbody>
<tr><td>wireguard-webadmin</td><td>Aplicação Django: interface web e API</td></tr>
<tr><td>caddy</td><td>Proxy reverso e TLS automático</td></tr>
<tr><td>auth-gateway</td><td>Camada de autorização Zero Trust: aplica verificações de identidade antes de encaminhar para o upstream</td></tr>
<tr><td>cron</td><td>Tarefas agendadas: ativação/desativação de peers e atualização de cache</td></tr>
<tr><td>rrdtool</td><td>Histórico de tráfego: coleta de dados RRD e geração de gráficos</td></tr>
<tr><td>dns</td><td>Resolvedor baseado em dnsmasq com suporte a listas de bloqueio por categoria</td></tr>
