mnemo_cards/tools/ssl/README.md

# SSL Certificates Management

This directory contains tools for managing SSL certificates for all Mnemo Cards domains.

## Domains and Certificates

The following domains require SSL certificates:

| Domain | Purpose | Certificate Path |
|--------|---------|------------------|
| `mnemo-cards.online` | Main web application | `/etc/letsencrypt/live/mnemo-cards.online/` |
| `api.mnemo-cards.online` | Backend API | `/etc/letsencrypt/live/api.mnemo-cards.online/` |
| `admin.mnemo-cards.online` | Admin panel | `/etc/letsencrypt/live/admin.mnemo-cards.online/` |
| `code.mnemo-cards.online` | Forgejo Git server | `/etc/letsencrypt/live/code.mnemo-cards.online/` |
| `vscode.mnemo-cards.online` | VSCode Server | `/etc/letsencrypt/live/vscode.mnemo-cards.online/` |

## Certificate Issuance

Certificates are centrally managed and automatically obtained during backend deployment:

- **All domains**: Automatically handled by `setup_ssl.sh` during backend deployment in CI/CD
- **Manual setup**: Run `sudo ./setup_ssl.sh` to obtain certificates for all domains
- **Individual certificates**: Use `renew_admin_ssl.sh` for admin domain only (fallback)

The CI/CD pipeline calls `setup_ssl.sh` during backend deployment to ensure all certificates are current.

## Tools

### Check Certificate Status
```bash
./check_ssl.sh
```

### Setup All Certificates
Obtain SSL certificates for all domains automatically:
```bash
sudo ./setup_ssl.sh
```
This script will:
- Stop nginx temporarily
- Obtain certificates for all domains using Let's Encrypt
- Restart nginx
- Configure automatic renewal via cron

### Obtain Certificate Manually
```bash
# Stop nginx temporarily
sudo systemctl stop nginx

# Get certificate
sudo certbot certonly --standalone -d DOMAIN_NAME --email admin@mnemo-cards.online --agree-tos

# Start nginx again
sudo systemctl start nginx
```

### Renew Certificates
```bash
sudo certbot renew
```

### Force Renewal
```bash
sudo certbot renew --force-renewal
```

## Certificate Validation

The CI/CD pipeline automatically checks SSL certificates during deployment:

- Certificate validity (must not expire within 30 days)
- HTTPS accessibility for all domains
- Certificate renewal configuration

## Troubleshooting

### Certificate Not Found
- Run the deployment script for the specific service
- Check that the domain DNS points to the server
- Verify nginx configuration

### Certificate Expired
- Run `sudo certbot renew`
- Check cron jobs for automatic renewal
- Verify Let's Encrypt account status

### HTTPS Not Working
- Check nginx configuration syntax: `sudo nginx -t`
- Verify certificate files exist and are readable
- Check firewall settings: `sudo ufw status`

## Cron Jobs

Automatic certificate renewal is configured via cron:

```bash
# Check existing cron jobs
crontab -l

# Example renewal jobs (configured automatically)
0 12 * * * /usr/bin/certbot renew --quiet --cert-name mnemo-cards.online
0 12 * * * /usr/bin/certbot renew --quiet --cert-name api.mnemo-cards.online
0 12 * * * /usr/bin/certbot renew --quiet --cert-name admin.mnemo-cards.online
```

## Security Notes

- All certificates use Let's Encrypt (preferred) with self-signed fallbacks
- Admin panel uses enhanced security headers
- Rate limiting is enabled for admin endpoints
- Certificates are automatically renewed before expiration