feat: Improve TLS handling for multi-server deployments

- Add CORE_SERVER_IP variable for remote server configuration
- Implement setup_multi_server_tls() function for shared CA management
- Change TLS failure handling from exit-on-error to warning-based approach
- Add TLS_ISSUES_SUMMARY for end-of-deployment remediation guidance
- Update documentation for automated TLS setup process
- Add comprehensive AI assistant instructions for project management

This allows deployments to complete successfully even with TLS issues,
providing clear remediation steps instead of failing the entire setup.
This commit is contained in:
Kelin
2026-01-26 16:34:25 -05:00
parent 3076232e8f
commit e2d28b5208
3 changed files with 445 additions and 184 deletions

View File

@@ -47,6 +47,12 @@ docker-compose/
- **Gluetun network mode**: Download clients use `network_mode: "service:gluetun"` for VPN routing
- **Port mapping**: Only core services expose ports (80/443 for Traefik); others route via Traefik labels
### TLS and Multi-Server Architecture
- **Shared CA**: Core server generates CA for signing certificates across all servers
- **Docker TLS**: Remote servers use TCP 2376 with mutual TLS for Sablier access
- **Certificate Management**: Automated generation and distribution of client/server certificates
- **Sablier Integration**: Core Sablier connects to remote Docker daemons via TLS for lazy loading
## Critical Operational Principles
### 1. Security-First SSO Strategy
@@ -284,6 +290,15 @@ Secrets auto-generated by `ez-homelab.sh`:
- **Renewal**: Traefik handles automatically (90-day Let's Encrypt certs)
- **Usage**: Services use `tls.certresolver=letsencrypt` label (no per-service cert requests)
### Remote Server TLS Setup
For multi-server deployments with Sablier lazy loading:
- **Core server**: Generates shared CA and client certificates
- **Remote servers**: Use `ez-homelab.sh` option 3, specify core server IP for CA import
- **Certificate chain**: Core has CA + client certs; remotes have CA + server certs
- **Sablier connection**: Uses TCP 2376 with mutual TLS to remote Docker daemons
- **Security**: All Docker API access encrypted and authenticated
- **Failure handling**: Setup fails if CA cannot be copied (prevents inconsistent TLS state)
### Homepage Dashboard AI Configuration
Homepage (`/opt/stacks/dashboards/`) uses dynamic variable replacement:
- Services configured in `homepage/config/services.yaml`
@@ -357,6 +372,17 @@ docker logs gluetun | grep -i wireguard # Verify connection
```
Verify: `SURFSHARK_PRIVATE_KEY` set in `.env`, service using `network_mode: "service:gluetun"`, ports mapped in Gluetun
### Sablier TLS Connection Issues
```bash
# Test Docker TLS connection from core to remote
cd /opt/stacks/core/shared-ca
docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem --host=tcp://REMOTE_IP:2376 ps
# Check Sablier logs
docker compose -f /opt/stacks/core/docker-compose.yml logs sablier-service
```
Verify: Remote Docker daemon configured with shared CA, certificates properly signed, firewall allows 2376/tcp
### Wildcard Certificate Issues
```bash
docker logs traefik | grep -i certificate