106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# Development SSL Certificates
|
|
|
|
This directory contains SSL certificates for the development container HTTPS setup.
|
|
|
|
## Files
|
|
|
|
| File | Purpose | Generated By |
|
|
| --------------- | ---------------------------------------------------- | -------------------------- |
|
|
| `localhost.crt` | SSL certificate for localhost and 127.0.0.1 | mkcert (in Dockerfile.dev) |
|
|
| `localhost.key` | Private key for localhost.crt | mkcert (in Dockerfile.dev) |
|
|
| `mkcert-ca.crt` | Root CA certificate for trusting mkcert certificates | mkcert |
|
|
|
|
## Certificate Details
|
|
|
|
The `localhost.crt` certificate includes the following Subject Alternative Names (SANs):
|
|
|
|
- `DNS:localhost`
|
|
- `IP Address:127.0.0.1`
|
|
- `IP Address:::1` (IPv6 localhost)
|
|
|
|
This allows the development server to be accessed via both `https://localhost/` and `https://127.0.0.1/` without SSL errors.
|
|
|
|
## Installing the CA Certificate (Recommended)
|
|
|
|
To avoid SSL certificate warnings in your browser, install the mkcert CA certificate on your system.
|
|
|
|
### Windows
|
|
|
|
1. Double-click `mkcert-ca.crt`
|
|
2. Click **"Install Certificate..."**
|
|
3. Select **"Local Machine"** > Next
|
|
4. Select **"Place all certificates in the following store"**
|
|
5. Click **Browse** > Select **"Trusted Root Certification Authorities"** > OK
|
|
6. Click **Next** > **Finish**
|
|
7. Restart your browser
|
|
|
|
### macOS
|
|
|
|
```bash
|
|
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain certs/mkcert-ca.crt
|
|
```
|
|
|
|
### Linux
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo cp certs/mkcert-ca.crt /usr/local/share/ca-certificates/mkcert-ca.crt
|
|
sudo update-ca-certificates
|
|
|
|
# Fedora/RHEL
|
|
sudo cp certs/mkcert-ca.crt /etc/pki/ca-trust/source/anchors/
|
|
sudo update-ca-trust
|
|
```
|
|
|
|
### Firefox (All Platforms)
|
|
|
|
Firefox uses its own certificate store:
|
|
|
|
1. Open Firefox Settings
|
|
2. Search for "Certificates"
|
|
3. Click **"View Certificates"**
|
|
4. Go to **"Authorities"** tab
|
|
5. Click **"Import..."**
|
|
6. Select `certs/mkcert-ca.crt`
|
|
7. Check **"Trust this CA to identify websites"**
|
|
8. Click **OK**
|
|
|
|
## After Installation
|
|
|
|
Once the CA certificate is installed:
|
|
|
|
- Your browser will trust all mkcert certificates without warnings
|
|
- Access `https://localhost/` with no security warnings
|
|
- Images from `https://127.0.0.1/flyer-images/` will load without SSL errors
|
|
|
|
## Regenerating Certificates
|
|
|
|
If you need to regenerate the certificates (e.g., after rebuilding the container):
|
|
|
|
```bash
|
|
# Inside the container
|
|
cd /app/certs
|
|
mkcert localhost 127.0.0.1 ::1
|
|
mv localhost+2.pem localhost.crt
|
|
mv localhost+2-key.pem localhost.key
|
|
nginx -s reload
|
|
|
|
# Copy the new CA to the host
|
|
podman cp flyer-crawler-dev:/app/certs/mkcert-ca.crt ./certs/mkcert-ca.crt
|
|
```
|
|
|
|
Then reinstall the CA certificate as described above.
|
|
|
|
## Security Note
|
|
|
|
**DO NOT** commit the private key (`localhost.key`) to version control in production projects. For this development-only project, the certificates are checked in for convenience since they're only used locally with self-signed certificates.
|
|
|
|
The certificates in this directory are automatically generated by the Dockerfile.dev and should not be used in production.
|
|
|
|
## See Also
|
|
|
|
- [Dockerfile.dev](../Dockerfile.dev) - Certificate generation (line ~69)
|
|
- [docker/nginx/dev.conf](../docker/nginx/dev.conf) - NGINX SSL configuration
|
|
- [docs/FLYER-URL-CONFIGURATION.md](../docs/FLYER-URL-CONFIGURATION.md) - URL configuration details
|
|
- [docs/development/DEBUGGING.md](../docs/development/DEBUGGING.md) - SSL troubleshooting
|