Como instalar a borda própria

A borda é o servidor contra o qual o assinante mede a velocidade. O teste abre no navegador do assinante, baixa e envia dados para a borda e mede o tempo. Este manual mostra como instalar a borda dentro da rede do seu provedor, conferir que ela está certa e cadastrá-la no painel.

Enquanto você não tem borda própria, o teste usa a borda compartilhada da plataforma, que fica fora do Brasil. Ela mede também o caminho pela internet até lá, então o resultado não diz se a sua rede entrega o plano. Por isso o assinante vê o aviso de medição provisória e há um limite diário de testes. Com a borda própria cadastrada, os dois somem e o teste passa a medir o trecho que é responsabilidade do provedor.

A borda não guarda dado de assinante. Ela só envia e recebe bytes de teste, responde a um ping e devolve ao navegador o IP de quem pergunta, sem gravar. Quem grava o resultado é a plataforma.

O que você precisa

Servidor. Uma máquina virtual ou física com Linux e acesso de root (ou sudo). Os comandos deste manual são de Ubuntu e Debian. As imagens usadas existem para x86_64 (amd64) e ARM64. As duas imagens da borda ocupam cerca de 250 MB em disco (medido em 26/10/2026).

Posição na rede. Do lado do concentrador (BNG), antes do CGNAT, sem proxy transparente, cache ou balanceador no caminho entre o assinante e a borda. É essa posição que faz o teste medir o acesso do assinante até a sua rede.

Capacidade de rede. Cada teste usa a velocidade do plano do assinante em cada direção, por 12 segundos. A interface do servidor precisa aguentar o maior plano que você vende vezes o número de testes ao mesmo tempo que você espera. Exemplo da conta: com plano de 1 Gbps e 3 testes simultâneos, a interface precisa de 3 Gbps. Um teste num plano de 1 Gbps transfere até cerca de 1.500 MB por direção (1.000 Mbps vezes 12 segundos, dividido por 8).

Memória. Durante o upload, cada teste ocupa até 175 MB de RAM na borda (5 conexões com até 35 MB cada). Some isso por teste simultâneo, mais o que o sistema operacional usa.

Endereço. Um IP público do bloco do provedor e um nome DNS apontando para ele, por exemplo speedtest.seuprovedor.com.br. O painel só aceita a borda por nome DNS ou IP público: IP privado ou reservado é recusado. Para medir IPv6, o nome também precisa de um registro AAAA.

Portas de entrada. A 443 (HTTPS), aberta para os assinantes. No modo de certificado automático, a 80 e a 443 também precisam receber conexões da internet, porque é por elas que o Let's Encrypt confere o domínio.

Certificado HTTPS. A página do teste é HTTPS, e o navegador recusa borda sem certificado válido. Você escolhe entre o modo automático, em que a borda emite e renova sozinha um certificado do Let's Encrypt, e o modo de certificado próprio, em que você entrega o certificado e a chave.

Passo 1: criar o nome DNS

No DNS do seu domínio, crie um registro A com o nome da borda apontando para o IP público do servidor. Se quiser medir IPv6, crie também um registro AAAA para um IPv6 do servidor. Nos comandos deste manual, troque speedtest.seuprovedor.com.br pelo nome da sua borda.

Se o seu DNS está na Cloudflare, deixe o registro sem proxy (nuvem cinza). Com o proxy ligado, o assinante passa a medir até a Cloudflare, e não até a sua rede.

Confira de qualquer computador:

dig +short speedtest.seuprovedor.com.br

A resposta tem de ser o IP público do servidor.

Passo 2: instalar o Docker

No servidor, instale o Docker com o script oficial e confira se o docker compose responde:

curl -fsSL https://get.docker.com | sudo sh
sudo docker compose version

Se o Docker já estiver instalado, basta o segundo comando. Ele precisa mostrar uma versão do Docker Compose (o plugin docker compose, com espaço).

Passo 3: liberar as portas

Libere a 443 no firewall do servidor e, no modo automático, também a 80. Com o ufw:

sudo ufw allow 443/tcp
sudo ufw allow 80/tcp

Confira também os firewalls e as ACLs que ficam antes do servidor na sua rede. O Docker abre as portas da borda por conta própria, por cima das regras do ufw, então uma regra do ufw que bloqueia a 443 não bloqueia a borda.

Passo 4: baixar a borda

Ainda no servidor, crie a pasta e baixe a versão atual:

mkdir -p ~/borda
curl -fsSL https://zapisp.run/borda/ist-edge.tar.gz | tar xz -C ~/borda
cd ~/borda

A pasta traz o docker-compose.yml, a configuração da borda, o modelo do arquivo de configuração (.env.example), o script de conferência (check-edge.sh) e este manual (LEIAME.md).

Passo 5: configurar

Crie o arquivo de configuração a partir do modelo e abra-o num editor:

cp .env.example .env
nano .env

Preencha as três linhas obrigatórias:

• EDGE_DOMAIN: o nome DNS do passo 1, sem https://. Exemplo: speedtest.seuprovedor.com.br.
• EDGE_TLS_MODE: acme para o certificado automático ou certs para o certificado próprio, escrito exatamente assim, em minúsculas.
• EDGE_ACME_EMAIL: um e-mail de contato da sua equipe, para avisos do Let's Encrypt. Obrigatório no modo acme.

Não defina EDGE_VERSION: a versão já vem da pasta que você baixou.

Modo `certs` (certificado próprio). Coloque o certificado com a cadeia completa em certs/fullchain.pem e a chave em certs/privkey.pem, dentro da pasta da borda. O certificado precisa ser de uma autoridade aceita pelos navegadores e cobrir o nome de EDGE_DOMAIN. Nesse modo a porta 80 não precisa estar aberta, e a borda não tenta emitir nenhum certificado sozinha.

Passo 6: subir a borda

Na pasta da borda:

sudo docker compose up -d
sudo docker compose ps

Na primeira vez o Docker constrói a imagem da borda e baixa a do Caddy, que cuida do HTTPS. Isso leva alguns minutos. No fim, o ps mostra dois contêineres, edge e caddy, com o estado running ou Up.

No modo acme, o certificado é emitido logo depois da subida. Para acompanhar:

sudo docker compose logs --tail 50 caddy

Não mude a pasta de lugar depois de subir e nunca rode docker compose down -v. Os volumes guardam o certificado, e apagá-los obriga uma nova emissão, que o Let's Encrypt limita quando se repete muitas vezes.

Passo 7: conferir

Faça a conferência de um computador fora do servidor, de preferência ligado à sua rede como um assinante. Ela precisa de bash e curl (Linux, macOS ou o WSL do Windows):

curl -fsSLO https://zapisp.run/borda/check-edge.sh
bash check-edge.sh https://speedtest.seuprovedor.com.br

O script baixa 30 MB da borda, envia 1 MB e imprime uma linha por verificação. Todas devem dar OK. As linhas ip e ipv6 podem dar AVISO, que não é falha:

• https: o certificado é válido para o nome.
• downloading, post-upload, get-upload, options-upload e ping: os caminhos que o teste usa respondem como devem.
• protocolo: a borda fala HTTP/1.1. O HTTP/2 fica desligado de propósito, porque o upload em HTTP/2 mede errado.
• health: a borda está de pé e informa a versão.
• ip: a borda devolve o IP de quem pergunta. AVISO com IP interno é esperado quando o computador da conferência está na rede dos assinantes atrás de NAT.
• ipv6: com registro AAAA, a borda precisa enxergar o IPv6 de quem chega por IPv6. AVISO quer dizer que não deu para verificar (sem AAAA ou o computador sem IPv6).
• server-token: a borda não expõe a versão do servidor web.

O script sai com erro se alguma linha der FAIL. Nesse caso veja a seção "Erros comuns" abaixo antes de cadastrar a borda.

Passo 8: cadastrar no painel

No painel do seu provedor, abra Configurações, seção Bordas:

1. Em Nome da borda, um nome que a sua equipe reconheça, por exemplo "Borda Centro".
2. Em Endereço da borda, o endereço completo com https:// e sem caminho no fim, por exemplo https://speedtest.seuprovedor.com.br.
3. Clique em Salvar configurações.

A mesma seção mostra a saúde da borda:

• No ar: a plataforma consultou a borda e ela respondeu.
• Não alcançável pela plataforma: a plataforma não alcança a borda, mas ela recebeu medição de assinante nas últimas 24 horas. É o normal para borda que só aceita conexões da sua própria rede.
• Fora do ar: a borda não respondeu e não recebeu medição nas últimas 24 horas.

Com a borda própria salva, o aviso de medição provisória e o limite diário de testes deixam de valer, e o passo "Borda própria" do cartão Primeiros passos, no Relatório, fica concluído. Faça um teste de uma conexão de assinante para ver a medição chegar.

Atualizar a borda

Para saber se há versão nova, compare a versão da sua borda com a versão atual:

curl -s https://speedtest.seuprovedor.com.br/health
curl -s https://zapisp.run/borda/versao.txt

Se forem diferentes, baixe a versão nova por cima da pasta atual e suba de novo. O seu .env e os seus certificados não fazem parte do pacote e continuam onde estão:

cd ~/borda
curl -fsSL https://zapisp.run/borda/ist-edge.tar.gz | tar xz -C ~/borda
sudo docker compose up -d
sudo docker compose restart caddy

O up -d constrói a imagem nova e troca o contêiner da borda. O restart caddy faz o Caddy ler a configuração nova. Os dois causam uma interrupção de poucos segundos: prefira um horário de pouco uso. O certificado é preservado.

Renovar o certificado próprio

No modo acme a renovação é automática. No modo certs ela é sua: troque certs/fullchain.pem e certs/privkey.pem pelos arquivos novos e rode:

sudo docker compose restart caddy

Monitorar

O endereço https://speedtest.seuprovedor.com.br/health responde {"ok":true,"version":"..."} quando a borda está de pé. Ele serve para o seu sistema de monitoramento. O painel também mostra a saúde da borda em Configurações, seção Bordas.

Erros comuns

O docker compose up falha com "defina EDGE_DOMAIN no .env"

O arquivo .env não existe na pasta onde você rodou o comando, ou está sem EDGE_DOMAIN. Rode o comando dentro da pasta da borda e confira o passo 5.

O docker compose up falha com "bind source path does not exist" e "Caddyfile"

O valor de EDGE_TLS_MODE está escrito errado. Ele precisa ser exatamente acme ou certs, em minúsculas e sem espaço. Corrija o .env e rode sudo docker compose up -d de novo.

O Caddy não sobe e o log mostra "wrong argument count" perto de "email"

No modo acme, o EDGE_ACME_EMAIL está vazio. Preencha um e-mail no .env e suba de novo.

"port is already allocated" ou "address already in use"

Outro programa já usa a porta 80 ou a 443 do servidor, em geral um nginx, Apache ou outro proxy. Descubra qual:

sudo ss -ltnp | grep -E ':(80|443) '

Pare esse programa, ou instale a borda num servidor só para ela.

O certificado não sai no modo acme

Veja o motivo no log do Caddy com sudo docker compose logs --tail 100 caddy. As causas mais comuns:

• O nome DNS ainda não aponta para o IP do servidor, ou o registro foi criado há pouco e ainda não se espalhou. Confira com dig +short (passo 1).
• A porta 80 ou a 443 está bloqueada para a internet em algum firewall ou ACL antes do servidor.
• O domínio tem um registro CAA que não autoriza o Let's Encrypt. Inclua letsencrypt.org no CAA ou use o modo certs.
• Muitas emissões repetidas para o mesmo nome, em geral depois de docker compose down -v. O Let's Encrypt bloqueia por um tempo. Espere e não apague os volumes de novo.

A conferência mostra erro de certificado no modo certs

Mensagens como "no alternative certificate subject name matches" querem dizer que o certificado não cobre o nome de EDGE_DOMAIN. Confira também se fullchain.pem traz a cadeia completa, e não só o certificado do servidor.

FAIL protocolo com "obtido '2'"

Há algo entre o assinante e a borda falando HTTP/2: o proxy da Cloudflare ligado, um balanceador ou outro proxy reverso na frente. Aponte o nome direto para o servidor da borda, sem nada no meio.

FAIL ipv6

A borda responde por IPv6, mas não enxerga o IPv6 de quem chega: o Docker do servidor está trocando o IP de origem. Sem correção, o IPv6 dos assinantes seria contado como IPv4. Fale com a Zapisp antes de cadastrar a borda. Se preferir seguir sem IPv6 por enquanto, apague o registro AAAA.

AVISO ip com IP interno, numa conferência feita de fora da sua rede

Se o computador da conferência não está na rede dos assinantes e mesmo assim a borda mostra um IP interno, algo no caminho esconde o IP de origem (um proxy ou NAT na frente do servidor). A borda só pode ficar atrás de equipamento que preserve o IP do assinante.

O painel recusa o endereço da borda

• "https obrigatório": o endereço precisa começar com https://.
• "não pode trazer query nem fragmento": tire do endereço o que vem depois de ? ou #, e também qualquer caminho depois do nome.
• "o endereço precisa ser público": use o nome DNS da borda, e não um IP privado.
• "endereço da borda compartilhada da plataforma": esse é o endereço da borda provisória. Informe o da sua borda.

O painel mostra "Fora do ar"

A plataforma não alcança a borda e nenhum assinante mediu nela nas últimas 24 horas. No servidor, confira sudo docker compose ps e o log do Caddy. De fora, abra https://speedtest.seuprovedor.com.br/health no navegador. Se você bloqueou de propósito o acesso de fora da sua rede, o status volta a "Não alcançável pela plataforma" assim que um assinante medir.

Desinstalar

Antes, troque no painel o endereço da borda pelo de outra borda que esteja no ar, senão os assinantes ficam sem teste. Depois, na pasta da borda, sudo docker compose down para a borda e mantém o certificado guardado, para quando ela voltar.

Ajuda

Se algo não estiver neste manual, mande a saída do check-edge.sh e as últimas linhas de sudo docker compose logs caddy para aleck@zapisp.com.br.