- What is ryoluo/sail-ssl and what does it do?
- ryoluo/sail-ssl is a Laravel Sail plugin that enables SSL/HTTPS for your local Docker-based development environment by configuring Nginx and generating locally trusted certificates. It lets you serve your Sail app at https://localhost instead of http://localhost with minimal manual setup. It is intended purely for local development, not for production TLS termination.
- How do I install sail-ssl in a Laravel Sail project?
- Install it as a Composer dev dependency with the --dev flag so it never ships to production, then run the package's Artisan/Sail command to generate certificates and patch your compose file. You need an existing Sail setup with Docker Compose and the standard Sail Nginx configuration in place. After installation, restart your Sail containers so Nginx picks up the generated certificate and the SSL server block.
- Which Laravel, PHP, Sail, and Docker Compose versions are supported?
- Version 1.5.0 is aligned with Sail v1.46.0 compose.yaml conventions, so newer Sail releases that use compose.yaml rather than docker-compose.yml are the intended target. Older Sail versions that still rely on docker-compose.yml stubs may not be patched correctly. Check the package's composer.json for PHP constraints, and verify against your own Sail and Docker Compose versions in a test branch before rolling it out to a team.
- Why does my browser still warn that the certificate is not trusted?
- Version 1.5.0 switched to a two-tier CA signing model, which means a new root CA must be imported into your OS or browser trust store before certificates are trusted. If you upgraded from v1.4.0, your old certificates will not chain to the new root CA, so regenerate them and import the new root CA. On macOS, Linux, and WSL the trust store steps differ, so document the procedure for each platform your team uses.
- Is sail-ssl safe to use in production?
- No. sail-ssl is local development tooling that generates self-signed, locally trusted certificates and rewrites your Sail compose file, so it should stay in require-dev and never be used as production ingress or TLS termination. For production, use a real reverse proxy or managed load balancer with certificates from a public CA such as Let's Encrypt. Keeping it dev-only means there is essentially no production risk from the package itself.
- How do I migrate from v1.4.0 to v1.5.0 without breaking local environments?
- Pin v1.5.0 in a test branch, regenerate your certificates, and import the new root CA into each developer's trust store, then confirm the browser shows a trusted connection. Remove stale v1.4.0 certificates and CA artifacts so the old and new chains do not conflict, and inspect the generated compose.yaml diff carefully. Keep a documented rollback to v1.4.0 plus a way to restore the previous certificates before rolling out to the whole team.
- Does sail-ssl help with service workers, secure cookies, and OAuth callbacks?
- Yes, that is its main use case. Many browser features only work over a secure context, including service workers, Secure-flagged cookies, and several OAuth providers that reject non-HTTPS callback URLs. Running your Sail app at https://localhost lets you exercise those flows locally instead of discovering problems after deployment.
- How do I use a custom domain or multiple hostnames with sail-ssl?
- Hostnames are controlled through the SSL alternate name (SSL_ALT_NAME) setting, and v1.5.0 includes a fix for an empty SSL_ALT_NAME that previously caused certificate generation to fail. Set the alternate names to every hostname you need, such as localhost and a custom .test domain, then regenerate certificates so the SANs are included. Remember to add matching entries to your hosts file and to trust the root CA for that machine.
- Does sail-ssl conflict with symfony/yaml or other Composer dependencies?
- v1.5.0 replaces brittle stub and regex-based compose manipulation with symfony/yaml, so symfony/yaml is a hard dependency with its own version constraints. Symfony-heavy Laravel stacks likely already have a compatible version, but tightly pinned lockfiles can produce a conflict. Run composer why symfony/yaml and test the update in a branch before merging.
- Should generated certificates and CA files be gitignored, and what are the alternatives to sail-ssl?
- Yes, generated certificates, keys, and root CA files should be gitignored so private material never lands in the repository, and each developer should generate their own locally. Alternatives include mkcert combined with manual Nginx configuration, Laravel Herd or Valet for non-Docker workflows, or hand-written Nginx SSL blocks inside your Sail setup. sail-ssl is the most convenient option when you want to stay entirely within Sail and Docker Compose, and you can also roll back to v1.4.0 if the two-tier CA model does not suit your team.