sábado, 21 de novembro de 2026

Como rodar o code-server com HTTPS em um servidor interno (Ubuntu + Nginx)

Rodar o code-server em uma rede interna traz muita praticidade, mas acessar o ambiente de desenvolvimento apenas via HTTP pode limitar recursos do navegador que exigem contexto seguro (como clipboard, service workers e certas APIs). A solução mais limpa é manter o code-server escutando apenas localmente (127.0.0.1:8080) e colocar o Nginx na frente como proxy reverso com TLS/HTTPS.


Neste guia, usamos o IP interno 10.134.210.4 e a porta 8443 como exemplo (ajuste para o IP e a porta do seu ambiente).

Pré-requisitos

  • Servidor interno rodando Ubuntu com acesso sudo.
  • code-server já instalado e configurado como serviço systemd (code-server@$USER).
  • Nginx (neste cenário instalaremos a versão nginx/1.18.0 (Ubuntu)).


Passo 1: Criar o certificado autoassinado com SAN usando openssl x509

Navegadores modernos exigem Subject Alternative Name (SAN) quando o acesso é feito por endereço IP.

  1. Crie uma pasta temporária e o arquivo de configuração cert-san.cnf:

mkdir -p ~/code-server-certs
cat << 'EOF' > ~/code-server-certs/cert-san.cnf
[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
x509_extensions = v3_req

[dn]
CN = 10.134.210.4

[v3_req]
subjectAltName = @alt_names
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth

[alt_names]
IP.1 = 10.134.210.4
EOF

  1. Gere a chave privada e o certificado X.509:

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ~/code-server-certs/your-key.pem \
  -out ~/code-server-certs/your-cert.pem \
  -days 825 -config ~/code-server-certs/cert-san.cnf -extensions v3_req


Teste de verificação do Passo 1


Confirme que o campo Subject Alternative Name contém o IP correto:

openssl x509 -in ~/code-server-certs/your-cert.pem -noout -text | grep -A1 "Subject Alternative Name"

Você deve ver IP Address:10.134.210.4 na saída.

Passo 2: Copiar os certificados para /etc/ssl/private e ajustar permissões

Mova os arquivos para /etc/ssl/private com permissões adequadas (chave privada restrita ao root, certificado legível para o Nginx ler):

sudo mkdir -p /etc/ssl/private
sudo cp ~/code-server-certs/your-cert.pem /etc/ssl/private/code-server.crt
sudo cp ~/code-server-certs/your-key.pem /etc/ssl/private/code-server.key
sudo chown root:root /etc/ssl/private/code-server.crt /etc/ssl/private/code-server.key
sudo chmod 644 /etc/ssl/private/code-server.crt
sudo chmod 600 /etc/ssl/private/code-server.key
rm -rf ~/code-server-certs


Teste de verificação do Passo 2

Lembre-se de que /etc/ssl/private costuma ter permissão 700 (root:root), então listar diretamente sem sudo pode dar Permission denied. Use sudo:

sudo ls -l /etc/ssl/private/code-server.crt /etc/ssl/private/code-server.key

Verifique também que o certificado e a chave combinam:

diff -u \
  <(sudo openssl x509 -in /etc/ssl/private/code-server.crt -pubkey -noout) \
  <(sudo openssl pkey -in /etc/ssl/private/code-server.key -pubout)

Se não houver saída, a chave pública do certificado e a chave privada correspondem exatamente.

Passo 3: Restringir o code-server ao 127.0.0.1:8080 e reiniciar o serviço


Para evitar exposição direta sem TLS na rede, faça o code-server escutar apenas em 127.0.0.1:8080 (com cert: false no config.yaml, já que o Nginx cuidará do HTTPS):


sed -i 's/^bind-addr:.*/bind-addr: 127.0.0.1:8080/' ~/.config/code-server/config.yaml
sudo systemctl restart code-server@$USER


Teste de verificação do Passo 3


Confira o status do serviço, o arquivo de configuração e o teste de WebSocket na porta local 8080:

systemctl status code-server@$USER --no-pager -l
grep -E '^(bind-addr|auth|cert):' ~/.config/code-server/config.yaml
curl -i -s -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
  -H "Sec-WebSocket-Version: 13" \
  http://127.0.0.1:8080/ | head -n 10

O serviço deve estar active (running) e responder na 127.0.0.1:8080 (por exemplo, HTTP/1.1 401 Unauthorized quando autenticado por senha).


Passo 4: Instalar e configurar o Nginx (nginx/1.18.0 (Ubuntu))


Instale o Nginx no Ubuntu:

sudo apt update
sudo apt install -y nginx
nginx -v

Crie o arquivo /etc/nginx/sites-available/code-server com suporte a TLS 1.2/1.3 e cabeçalhos corretos para WebSockets (Upgrade, Connection, Host e Origin):


server {
    listen 8443 ssl http2;
    server_name 10.134.210.4;

    ssl_certificate /etc/ssl/private/code-server.crt;
    ssl_certificate_key /etc/ssl/private/code-server.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Origin $http_origin;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # proxy_set_header Accept-Encoding gzip;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

 

Dica para nginx/1.18.0 (Ubuntu): O nginx 1.18.0 no Ubuntu já suporta ssl http2 na diretiva listen e TLSv1.2 TLSv1.3. Evite forçar Accept-Encoding gzip no proxy se quiser manter a negociação padrão de compressão com o upstream.

 

Ative o site, valide a configuração e recarregue o Nginx:

sudo ln -sf /etc/nginx/sites-available/code-server /etc/nginx/sites-enabled/code-server
sudo nginx -t && sudo systemctl reload nginx


Teste de verificação do Passo 4


Verifique se o Nginx está escutando na porta 8443 e sem erros recentes:

ss -tulpn | grep 8443
sudo tail -n 20 /var/log/nginx/error.log


Pronto! As configurações no seu servidor interno estão feitas.
Agora vamos acessar o code-server via browser.

Passo 5: Baixar o certificado no navegador e instalar em "Trusted Root Certification Authorities"


  1. Acesse https://10.134.210.4:8443/ no navegador.
  2. Clique no ícone de segurança/certificado na barra de endereços, abra os detalhes do certificado e exporte/baixe o certificado (formato .crt / .cer / PEM).
  3. No seu sistema/navegador (por exemplo, no gerenciador de certificados do Windows/navegador), importe o arquivo para Autoridades de Certificação Raiz Confiáveis (Trusted Root Certification Authorities).
  4. Feche e reabra o navegador (ou limpe dados/service workers antigos do site caso você tenha ignorado avisos anteriores) e acesse https://10.134.210.4:8443/ novamente.


Teste de verificação do Passo 5

  • Abra o DevTools (F12) -> aba Security: confirme que o certificado consta como válido e confiável e que os recursos estão seguros (TLS 1.3 / TLS 1.2).
  • Faça login no code-server e abra um terminal integrado ou explore arquivos para confirmar que o WebSocket permanece conectado sem erros de desconexão (1006) ou 403.



Sugestões extras e boas práticas para ambientes internos


  • Firewall (ufw): Se o ufw estiver ativo no Ubuntu, libere apenas a porta 8443 (e restrinja à sub-rede interna se possível), mantendo a 8080 fechada externamente:

sudo ufw allow 8443/tcp
sudo ufw status


  • Autenticação forte: Use hashed-password (com Argon2) em ~/.config/code-server/config.yaml em vez de senha em texto puro comentada/exposta.

  • Logs de diagnóstico: Em caso de falha de conexão no editor, acompanhe em paralelo /var/log/nginx/error.log, /var/log/nginx/access.log e sudo journalctl -u code-server@$USER -f.


Como rodar o code-server com HTTPS em um servidor interno (Ubuntu + Nginx)

Rodar o code-server em uma rede interna traz muita praticidade, mas acessar o ambiente de desenvolvimento apenas via HTTP pode limitar rec...