Skip to main content

mkcert | Windows

  • mkcert | Windows

🎯 Objetivo​

Este documento explica:

  • O que é o mkcert
  • Por que ele é a melhor solução no Windows
  • Como instalar
  • Como gerar certificados
  • Como usar com Docker / Traefik
  • Erros comuns e como evitar

🧠 1. O que é o mkcert?

O mkcert é uma ferramenta que:

  • Cria uma Autoridade Certificadora (CA) local
  • Instala essa CA automaticamente no Windows
  • Gera certificados confiáveis pelos navegadores
  • Elimina avisos de “Site não seguro”

🔑 Em resumo​

mkcert = HTTPS confiável em ambiente local, sem dor de cabeça

❌ 2. Por que NÃO usar OpenSSL puro no Windows?

Problemas comuns com certificados autoassinados no Windows:

  • Navegadores não confiam
  • WebSocket bloqueado
  • Fetch / API bloqueados
  • SPAs quebram silenciosamente
  • Chrome / Edge / Firefox se comportam diferente

👉 mkcert resolve tudo isso automaticamente.

🖥️ 3. Instalação do mkcert no Windows

🥇 Opção recomendada: Winget (mais simples)​

Abra PowerShell como Administrador:

winget install FiloSottile.mkcert

Verifique:

mkcert -version

🥈 Alternativa: Chocolatey​

choco install mkcert

🥉 Alternativa manual (ZIP)​

  1. Baixe: https://github.com/FiloSottile/mkcert/releases
  2. Extraia mkcert.exe
  3. Coloque em uma pasta do PATH

🔐 4. Instalar a CA local (PASSO MAIS IMPORTANTE)

⚠️ Esse passo é obrigatório e só feito uma vez

No PowerShell (Administrador):

mkcert -install

O que isso faz:​

  • Cria uma CA local

  • Instala em:

    • Windows Trust Store
    • Chrome / Edge
    • Firefox (se detectado)

📌 Após isso, todos os certificados gerados serão confiáveis.

🔏 5. Gerar certificados com mkcert

📍 Exemplo básico (um domínio)​

mkcert vaultwarden.localhost

Arquivos gerados:

vaultwarden.localhost.pem
vaultwarden.localhost-key.pem

📍 Exemplo múltiplos domínios (RECOMENDADO)​

mkcert vaultwarden.localhost passbolt.localhost aliasvault.localhost

Arquivos gerados:

vaultwarden.localhost+2.pem
vaultwarden.localhost+2-key.pem

🔁 Renomear para uso padrão (Docker / Traefik)​

rename vaultwarden.localhost+2.pem local.crt
rename vaultwarden.localhost+2-key.pem local.key

Estrutura final:

certs/
├── local.crt
└── local.key

🐳 6. Usando mkcert com Docker e Traefik

📁 Estrutura recomendada​

project/
├── certs/
│   ├── local.crt
│   └── local.key
├── traefik/
│   └── tls.yml
└── docker-compose.yml

📄 traefik/tls.yml (obrigatório)​

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /certs/local.crt
        keyFile: /certs/local.key

  certificates:
    - certFile: /certs/local.crt
      keyFile: /certs/local.key

🧩 Volume no Traefik​

volumes:
  - ./certs:/certs:ro
  - ./traefik:/etc/traefik:ro

🌐 7. Configurar o arquivo hosts (Windows)

Abra como Administrador:

C:\Windows\System32\drivers\etc\hosts

Adicione:

127.0.0.1 vaultwarden.localhost
127.0.0.1 passbolt.localhost
127.0.0.1 aliasvault.localhost

✅ 8. Resultado esperado

Após subir os containers:

  • 🔒 Cadeado verde no navegador
  • ❌ Nenhum aviso de certificado
  • ✅ Vaultwarden funciona
  • ✅ Passbolt funciona
  • ✅ AliasVault funciona
  • ✅ WebSocket e APIs funcionam

🧪 9. Verificação rápida

No navegador:

  • Clique no cadeado

  • Verifique que o emissor é algo como:

    mkcert development CA

⚠️ 10. Erros comuns e soluções

❌ “Site não seguro”​

➡️ Esqueceu mkcert -install

❌ Firefox ainda não confia​

mkcert -install

(ou importar manualmente no Firefox)

❌ Cert não carrega no container​

➡️ Volume errado (/certs)

🔐 11. Segurança (importante)

  • ❌ Nunca use mkcert em produção
  • ❌ Nunca commite local.key
  • ✅ Use somente para LAB / DEV
  • 🔄 Refaça se trocar de máquina

🧠 12. Resumo mental

mkcert
  ├─ cria CA local
  ├─ instala trust no Windows
  ├─ gera certificados válidos
  └─ elimina problemas HTTPS em LAB

📌 Links úteis​