#Sail-SSL

A Laravel Sail plugin that enables SSL (HTTPS) for your local development environment using an Nginx reverse proxy with self-signed certificates.

#Table of Contents

• How It Works
• Requirements
• Installation
• Update AppServiceProvider
• Trust the Certificate (Optional)
• Environment Variables
• Customize Nginx Configuration
• Troubleshooting
• Contributing
• License

#How It Works

Sail-SSL adds an Nginx container to your Docker Compose setup that acts as an SSL-terminating reverse proxy:

Browser → https://localhost:443 → Nginx (SSL termination) → http://laravel.test → Laravel App

Running the sail-ssl:install command automatically adds an Nginx service to your docker-compose.yml. On container startup, a self-signed Root CA and server certificate are generated, enabling HTTPS access out of the box.

#Requirements

• Laravel Sail already set up in your project
• Docker and Docker Compose installed

#Installation

#With Local PHP / Composer

composer require ryoluo/sail-ssl --dev
php artisan sail-ssl:install
./vendor/bin/sail up

#With Sail Container

./vendor/bin/sail up -d
./vendor/bin/sail composer require ryoluo/sail-ssl --dev
./vendor/bin/sail artisan sail-ssl:install
./vendor/bin/sail down
./vendor/bin/sail up

Once the containers are running, you can access https://localhost.

Note: The sail-ssl:install command adds an Nginx service to your docker-compose.yml (or compose.yaml). If an nginx service already exists, the command will be skipped.

#Update AppServiceProvider

Since the application runs behind an Nginx reverse proxy that handles SSL, Laravel needs to be configured to generate HTTPS URLs. Add URL::forceScheme('https') to the boot method of your AppServiceProvider:

use Illuminate\Support\Facades\URL;

public function boot(): void
{
    URL::forceScheme('https');
}

Without this setting, Laravel may generate HTTP URLs for assets, routes, etc., even though the site is served over HTTPS.

#Trust the Certificate (Optional)

The plugin generates a local Root CA certificate to sign the server certificate. You can import the Root CA into your browser or OS to remove the security warning.

#1. Copy the Root CA certificate to your host machine

./vendor/bin/sail cp nginx:/etc/nginx/certs/root-ca.crt .

#2. Import the certificate

Note: If you change SSL_DOMAIN or SSL_ALT_NAME, remove the Docker volume to regenerate certificates:

docker volume rm sail-nginx

#Environment Variables

You can customize the behavior by setting the following environment variables in your .env file:

#Custom Domain Example

To access your app via mydomain.test, add the following to your .env:

SERVER_NAME=mydomain.test
SSL_DOMAIN=mydomain.test
SSL_ALT_NAME=DNS:mydomain.test,DNS:localhost

Then add an entry to your hosts file (/etc/hosts on macOS/Linux, C:\Windows\System32\drivers\etc\hosts on Windows):

127.0.0.1 mydomain.test

#Customize Nginx Configuration

You can publish the default Nginx configuration template to your project for customization:

php artisan sail-ssl:publish

This copies default.conf.template to ./nginx/templates/ in your project root and automatically updates the volume mount in docker-compose.yml.

You can use environment variables such as ${SERVER_NAME} and ${APP_SERVICE} directly in the template file.

#Troubleshooting

#Port Conflicts

If SSL_PORT or HTTP_PORT conflicts with another service, change them in your .env:

HTTP_PORT=8080
SSL_PORT=4443

#Regenerate Certificates

Remove the Docker volume and restart the containers:

docker volume rm sail-nginx
./vendor/bin/sail up

#Assets or Links Generated with HTTP

Make sure you have configured URL::forceScheme('https') in your AppServiceProvider. See Update AppServiceProvider for details.

#Contributing

Pull requests are welcome! For bug reports and feature requests, please open an Issue.

#License

MIT License