Posted on: January 21, 2026 03:35 PM
Posted by: Renato
Categories: Laravel lets-encrypt
Views: 99
Laravel Lets Encrypt: Geração SSL Automática
O que é este pacote laravel-lets-encrypt, e como usar?
O pacote laravel-lets-encrypt é uma ferramenta desenvolvida para facilitar a geração e renovação automática de certificados SSL gratuitos da Let's Encrypt diretamente através de uma aplicação Laravel.
Geralmente, a gestão de SSL é feita no nível do servidor (usando ferramentas como Certbot ou via Forge/Ploi). Este pacote traz essa lógica para dentro do código, o que é extremamente útil para plataformas SaaS (Multi-tenancy), onde você precisa emitir certificados para domínios customizados de clientes de forma programática.
Como o pacote funciona?
Ele utiliza o protocolo ACME para se comunicar com a Let's Encrypt. O fluxo básico consiste em:
-
Solicitar um certificado para um domínio.
-
Provar a propriedade do domínio (Desafio HTTP ou DNS).
-
Receber e armazenar os arquivos do certificado (fullchain.pem, privkey.pem).
Como usar (Passo a Passo)
1. Instalação
Primeiro, instale o pacote via Composer:
Bash
composer require f60/laravel-lets-encrypt
Recomendo usar este:
composer require daanra/laravel-lets-encrypt
-
https://github.com/Daanra/laravel-lets-encrypt
(Nota: Existem variações deste pacote de diferentes autores, como o f60 ou driesvarts. Verifique a documentação da versão específica que você escolher, mas a lógica costuma ser similar.)
2. Configuração
Publique o arquivo de configuração para definir onde os certificados serão salvos e as credenciais da sua conta Let's Encrypt:
Bash
php artisan vendor:publish --provider="F60\LetsEncrypt\LetsEncryptServiceProvider"
No arquivo config/lets-encrypt.php, você configurará o e-mail de contato e o ambiente (Staging para testes ou Production).
3. O Desafio (Challenge)
A Let's Encrypt precisa confirmar que você é dono do domínio. O método mais comum é o HTTP-01.
-
O pacote cria uma rota automaticamente que responde em .well-known/acme-challenge/.
-
Você deve garantir que seu servidor web (Nginx/Apache) direcione essas requisições para o seu index.php do Laravel.
4. Gerando um Certificado via Código
A grande vantagem é poder disparar a criação em um Controller ou Job:
PHP
use F60\LetsEncrypt\LetsEncrypt; public function generateSsl($domain) { // Instancia o serviço e solicita o certificado $letsEncrypt = app(LetsEncrypt::class); // Isso executará o desafio e salvará os arquivos no storage definido $letsEncrypt->create($domain); return "Certificado gerado com sucesso!"; }
Pontos de Atenção
-
Limites de Taxa (Rate Limits): A Let's Encrypt tem limites estritos de quantas vezes você pode solicitar certificados. Sempre use o modo Staging durante o desenvolvimento.
-
Servidor Web: O pacote gera os arquivos, mas você ainda precisa configurar seu Nginx ou Apache para ler esses arquivos na pasta storage do Laravel.
-
Permissões: O usuário que roda o PHP (ex: www-data) precisa de permissão de escrita na pasta onde os certificados serão armazenados.
Quando usar este pacote?
-
SaaS: Se seu usuário aponta um domínio cliente.com para o seu IP e você quer gerar o SSL automaticamente.
-
Automação: Se você quer evitar o uso de ferramentas externas de linha de comando no servidor.
Pacote daanra/laravel-lets-encrypt. Ele é uma solução robusta para quem trabalha com SaaS (Software as a Service) ou qualquer aplicação onde você precise gerenciar centenas ou milhares de domínios customizados apontando para o seu servidor.
Aqui está uma análise detalhada dos pontos principais desse pacote:
1. O Diferencial: Baseado em Filas (Queues)
Diferente de outros pacotes que tentam fazer tudo de forma síncrona (travando a requisição), este pacote foi desenhado para ser assíncrono.
-
Ao chamar LetsEncrypt::create('dominio.com'), ele coloca tarefas na fila do Laravel para:
-
Registrar a conta na Let's Encrypt.
-
Criar o "desafio" (token de validação).
-
Solicitar o certificado.
-
Armazenar o certificado no banco de dados.
2. Gerenciamento via Banco de Dados
Este pacote possui uma migration própria. Isso significa que você tem um modelo Eloquent (LetsEncryptCertificate) para gerenciar os certificados. Você pode fazer consultas como:
-
Ver quais certificados expiram em breve.
-
Listar todos os domínios ativos.
-
Deletar certificados de clientes que cancelaram o serviço.
3. O Desafio HTTP (O "Pulo do Gato")
A Let's Encrypt precisa acessar uma URL no seu domínio para confirmar que você é o dono dele. O pacote salva esse token na pasta storage. O README avisa: Você precisa criar uma rota manualmente (ou configurar o Nginx) para que, quando a Let's Encrypt acessar seu-dominio.com/.well-known/acme-challenge/{token}, o Laravel entregue o conteúdo do arquivo que o pacote gerou.
4. Automação Total (Renovação)
O pacote resolve um dos maiores problemas do SSL: a expiração a cada 90 dias. Ele traz um Job pronto (RenewExpiringCertificates) que você agenda no seu Console/Kernel.php para rodar diariamente. Ele automaticamente renova certificados com mais de 60 dias de uso.
5. Encadeamento de Tarefas (Chaining)
Um recurso muito poderoso citado é a capacidade de "encadear" ações. Exemplo: Assim que o certificado for gerado com sucesso, você pode disparar automaticamente outros Jobs, como:
-
Reiniciar o servidor Apache/Nginx.
-
Notificar o usuário por e-mail que o domínio dele já está seguro.
6. Configuração Importante (Staging vs Production)
O README enfatiza: Por padrão, o pacote usa o servidor de testes (Staging) da Let's Encrypt.
-
Isso é ótimo para desenvolver sem ser bloqueado por excesso de tentativas.
-
Para o site real, você deve mudar a URL no seu .env para a URL de produção da Let's Encrypt.
Resumo: Devo usar?
-
Use se: Você está criando um sistema estilo "Shopify" ou "Wix", onde o usuário final aponta o próprio domínio para o seu servidor e você quer que o SSL apareça "magicamente" para ele.
-
Não use se: Você só quer SSL para o seu próprio site (www.meusite.com). Para isso, é muito mais simples e seguro usar o Certbot diretamente no servidor ou serviços como Cloudflare e Laravel Forge.
Dica técnica: Se você for usar este pacote, certifique-se de que seu sistema de Queues (Fila) está configurado corretamente (usando Redis ou Database), pois o pacote depende 100% disso para funcionar bem.
Para implementar esse pacote e transformar sua aplicação Laravel em um gerenciador de certificados, você precisa integrar o fluxo de solicitação, validação e renovação.
Aqui está um guia prático de como estruturar isso:
1. Configuração do Ambiente e Servidor
Antes do código, seu servidor (Nginx/Apache) precisa saber entregar o desafio que o Let's Encrypt enviará. No seu arquivo de rotas routes/web.php, adicione:
PHP
use Illuminate\Support\Facades\Storage; use Illuminate\Support\Facades\Route; // Rota crucial para a validação do Let's Encrypt Route::get('/.well-known/acme-challenge/{token}', function (string $token) { $path = 'public/.well-known/acme-challenge/' . $token; if (Storage::disk('local')->exists($path)) { return Storage::disk('local')->get($path); } abort(404); });
2. Criando um Serviço de Gestão de Domínios
Imagine que você tem um modelo Store ou Domain. Vamos criar um serviço para centralizar a criação do SSL.
PHP
namespace App\Services; use Daanra\LaravelLetsEncrypt\Facades\LetsEncrypt; use Daanra\LaravelLetsEncrypt\Models\LetsEncryptCertificate; class SslService { /**
* Gera um certificado para um novo domínio de cliente.
*/ public function createForDomain(string $domain) { // createNow executa de forma síncrona. // Se preferir via fila (queue), use apenas create(). return LetsEncrypt::createNow($domain); } /**
* Verifica o status de um certificado no banco.
*/ public function getStatus(string $domain) { $cert = LetsEncryptCertificate::where('domain', $domain)->first(); if (!$cert) return 'not_found'; return [ 'is_valid' => $cert->is_valid, 'expires_at' => $cert->expires_at, 'needs_renewal' => $cert->requiresRenewal(), ]; } }
3. Automatizando a Renovação
O Let's Encrypt dura apenas 90 dias. O pacote já traz um Job de renovação, você só precisa agendá-lo no arquivo app/Console/Kernel.php:
PHP
protected function schedule(Schedule $schedule) { // Tenta renovar diariamente certificados que vencem em menos de 30 dias $schedule->job(new \Daanra\LaravelLetsEncrypt\Jobs\RenewExpiringCertificates)->daily(); }
4. Exemplo de Fluxo em um Controller
Se você quer permitir que seu usuário clique em um botão "Ativar SSL":
PHP
public function activateSsl(Request $request, SslService $sslService) { $domain = $request->input('domain'); // ex: cliente.com try { $sslService->createForDomain($domain); return back()->with('success', 'Certificado gerado! Pode levar alguns minutos para propagar.'); } catch (\Exception $e) { return back()->with('error', 'Falha ao gerar SSL: ' . $e->getMessage()); } }
5. Dicas de Ouro para Produção
Onde ficam os arquivos?
Os certificados gerados são salvos no banco de dados (colunas certificate e key). Para que o seu servidor web (Nginx) os use, você precisará de um script ou Job que:
-
Pegue o conteúdo do banco.
-
Salve em um arquivo .pem no servidor.
-
Recarregue o Nginx (sudo nginx -s reload).
Configuração do .env
Nunca esqueça de alternar para o servidor de produção quando for lançar o site:
Snippet de código
# Em desenvolvimento (Staging - não gera SSL válido no navegador, mas evita bloqueios)
LETS_ENCRYPT_API_URL=https://acme-staging-v02.api.letsencrypt.org/directory
# Em produção (SSL Real)
LETS_ENCRYPT_API_URL=https://acme-v02.api.letsencrypt.org/directory
Limites de Taxa
A Let's Encrypt permite apenas 50 certificados por semana por domínio registrado. Se você estiver testando muito, use sempre o modo Staging.
Você já tem os domínios dos seus clientes apontados via CNAME ou IP para o seu servidor? Isso é um pré-requisito para o teste de validação funcionar.
Donate to Site
Renato
Developer