SSL Certificates

​

Overview

​

How SSL Automation Works

​

1. DNS Verification

• DNS records are properly configured
• The domain resolves to your server’s IP
• The domain is under your control

​

2. Forge Site Creation

• A new site is created on your Laravel Forge server
• The site is configured with proper Nginx settings
• The domain is added to the site configuration

​

3. Certificate Request

• Uses DigitalOcean DNS validation (not HTTP validation)
• Supports wildcard certificates if needed
• Handles DNS TXT record creation automatically

​

4. Certificate Installation

• Certificate is installed on the Forge site
• Nginx configuration is updated
• HTTPS is enabled automatically

​

5. Certificate Activation

• Set as the active certificate for the domain
• HTTP to HTTPS redirect is enabled
• Domain becomes fully operational

​

Certificate Workflow

Team adds domain
    ↓
DNS Verification Job
    ↓ (DNS Verified Event)
Create Forge Site Job
    ↓ (Forge Site Created Event)
Create Certificate Job
    ↓
Certificate Active ✅

​

Key Components

​

CreateForgeSiteCertificateJob

// Pseudo-code of the job's logic
1. Check if certificate already exists
2. If exists and installed:
   - Update domain record
   - Activate if needed
   - Send success notification
3. If not exists:
   - Request new Let's Encrypt certificate
   - Use DigitalOcean DNS validation
   - Track installation progress

​

Certificate Status Tracking

$domain->ssl_installed      // Boolean: Certificate installed
$domain->ssl_active         // Boolean: Certificate active
$domain->ssl_installed_at   // DateTime: When installed
$domain->forge_certificate_id  // Forge certificate ID

​

Let’s Encrypt Certificates

​

Certificate Details

• Issuer: Let’s Encrypt Authority
• Validity: 90 days
• Renewal: Automatic via Laravel Forge
• Type: Domain Validated (DV)
• Encryption: RSA 2048-bit or ECDSA
• Trust: Trusted by all major browsers

​

Rate Limits

​

DNS Validation with DigitalOcean

​

Why DNS Validation?

1. Works Before Site is Live: Can provision certificates before the site is fully configured
2. No Downtime: Doesn’t require the site to be accessible
3. Wildcard Support: Enables wildcard certificates if needed
4. More Reliable: No dependency on HTTP server configuration

​

How It Works

1. Certificate Request: System requests certificate from Let’s Encrypt
2. Challenge: Let’s Encrypt provides a DNS challenge
3. TXT Record: System creates TXT record via DigitalOcean API
4. Verification: Let’s Encrypt verifies TXT record exists
5. Issuance: Certificate is issued and downloaded

​

DigitalOcean Requirements

• Domain’s nameservers must point to DigitalOcean
• DigitalOcean API token must have read/write permissions
• Domain must be added to your DigitalOcean account

​

Certificate Management

​

Automatic Renewal

• Certificates are checked daily
• Renewed 30 days before expiration
• No manual intervention required
• Teams are notified if renewal fails

​

Certificate Installation Timeline

1. Domain Added: Immediate
2. DNS Verification: 5-30 minutes (depends on DNS propagation)
3. Site Creation: 1-2 minutes
4. Certificate Request: 2-5 minutes
5. Certificate Installation: 1-2 minutes
6. Total Time: ~10-40 minutes

​

Monitoring Certificate Status

// Get domain with certificate details
$domain = Domain::where('domain', 'app.clientdomain.com')->first();

// Check status
if ($domain->ssl_active && $domain->ssl_installed) {
    echo "✅ Certificate active and working";
} elseif ($domain->ssl_installed && !$domain->ssl_active) {
    echo "⏳ Certificate installed, activating...";
} elseif (!$domain->ssl_installed) {
    echo "⏳ Certificate being provisioned...";
}

​

Manual Certificate Check

php artisan app:check-custom-domain-setup

• Checks all domains with pending certificate installations
• Retries failed certificate requests
• Activates installed but inactive certificates
• Logs all actions for debugging

​

Troubleshooting

​

Certificate Not Installing

1. DigitalOcean API token invalid or lacks permissions
2. Domain not on DigitalOcean DNS
3. DNS TXT record propagation delays
4. Let’s Encrypt rate limits reached

# Check the logs
tail -f storage/logs/laravel.log | grep -i certificate

# Manually check certificate status on Forge
# Visit: https://forge.laravel.com/servers/{SERVER_ID}/sites/{SITE_ID}/certificates

# Retry certificate provisioning
php artisan app:check-custom-domain-setup

​

Certificate Validation Failed

1. Verify DigitalOcean token: FORGE_DIGITALOCEAN_TOKEN
2. Ensure domain uses DigitalOcean nameservers
3. Check Let’s Encrypt rate limits
4. Review Forge logs for detailed error messages

​

Multiple Certificates

// Check certificates via ForgeService
$forge = app(\App\Services\ForgeService::class);
$certificates = $forge->certificates($siteId);

// Delete old/inactive certificates
foreach ($certificates as $cert) {
    if (!$cert['active']) {
        $forge->deleteCertificate($siteId, $cert['id']);
    }
}

​

Certificate Not Activated

# Run the check command
php artisan app:check-custom-domain-setup

# Or manually via tinker
$forge = app(\App\Services\ForgeService::class);
$forge->activateCertificate($siteId, $certificateId);

​

DNS Validation Issues

1. Verify domain is on DigitalOcean DNS
2. Check DigitalOcean DNS records:
   Copy

   dig @ns1.digitalocean.com app.clientdomain.com
   

3. Ensure API token has correct permissions
4. Check if domain is in DigitalOcean account

​

Security Best Practices

​

1. Secure API Tokens

# Use strong environment variable protection
chmod 600 .env

# Never commit .env to version control
echo ".env" >> .gitignore

# Use Laravel's encryption for sensitive data
php artisan env:encrypt

​

2. Certificate Monitoring

// In your monitoring system
$domains = Domain::where('ssl_active', true)->get();

foreach ($domains as $domain) {
    if ($domain->ssl_installed_at < now()->subDays(60)) {
        // Certificate is getting old, should have been renewed
        Log::warning("Certificate may need renewal", [
            'domain' => $domain->domain,
            'installed_at' => $domain->ssl_installed_at,
        ]);
    }
}

​

3. HTTPS Enforcement

// In your middleware or AppServiceProvider
if (request()->getHost() !== config('app.url')) {
    // This is a custom domain
    if (!request()->secure()) {
        return redirect()->secure(request()->getRequestUri());
    }
}

​

4. HSTS Headers

# In Forge Nginx template
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

​

Certificate Types

​

Standard SSL Certificate

• Single domain (e.g., app.clientdomain.com)
• 90-day validity
• Automatic renewal
• Free via Let’s Encrypt

​

Wildcard SSL Certificate

• Covers *.clientdomain.com
• Requires DNS validation
• More complex setup
• Free via Let’s Encrypt

​

Advanced Configuration

​

Using Different Certificate Authority

1. Obtain certificate from your CA
2. Upload to Forge manually
3. Update domain record with certificate ID
4. Disable automatic certificate provisioning for that domain

​

Custom Certificate Installation

// Modify CreateForgeSiteCertificateJob
if ($team->has_custom_certificate) {
    // Skip automatic provisioning
    return;
}

// Or create a custom endpoint for certificate upload

​

Staging Certificates

// In ForgeService
$isStaging = config('app.env') !== 'production';

// Use staging endpoint for testing
$certificateType = $isStaging ? 'letsencrypt-staging' : 'letsencrypt';

​

Notifications

​

Success Notifications

Notification::make()
    ->title('SSL certificate for ' . $domain . ' has been created')
    ->body('You can now use your custom domain.')
    ->icon('heroicon-o-check-circle')
    ->iconColor('success')
    ->send();

​

Failure Notifications

// In CreateForgeSiteCertificateJob
public function failed(\Throwable $exception): void
{
    Notification::make()
        ->title('SSL certificate installation failed')
        ->body('Domain: ' . $this->team->domain . ' - ' . $exception->getMessage())
        ->icon('heroicon-o-exclamation-triangle')
        ->iconColor('danger')
        ->sendToDatabase($this->team->owner);
}

​

Next Steps

• Troubleshooting - Common issues and solutions
• API Reference - Programmatic domain management
• Advanced Topics - Wildcard domains, custom certificates, and more