377ba6dc20
- Add new Arcane application stack - Move aliases.sh to scripts/ directory - Remove deprecated files (IMPLEMENTATION_COMPLETE.md, markup.yml, release notes) - Remove standalone traefik docker-compose (now part of core stack) - Update documentation (ai-vscode-setup.md, docker-guidelines.md, core README)
111 lines
4.1 KiB
Markdown
111 lines
4.1 KiB
Markdown
# Core Infrastructure Services
|
|
|
|
This directory contains the core infrastructure services that form the foundation of the homelab. These services should be deployed **on the core server only** and are critical for the operation of all other services across all servers.
|
|
|
|
## Services
|
|
|
|
### DuckDNS
|
|
- **Purpose**: Dynamic DNS service for domain resolution and wildcard SSL certificates
|
|
- **Subdomain**: Configurable via environment variables
|
|
- **Token**: Configured in environment variables
|
|
- **SSL Certificates**: Generates wildcard cert used by all services on all servers
|
|
- **Deploy**: Core server only
|
|
|
|
### Traefik (v3)
|
|
- **Purpose**: Reverse proxy and SSL termination with multi-server routing
|
|
- **Ports**: 80 (HTTP), 443 (HTTPS), 8080 (Dashboard)
|
|
- **Configuration**: Located in `traefik/config/traefik.yml`
|
|
- **Multi-Server**: Discovers services on all servers via Docker providers
|
|
- **SSL**: Let's Encrypt with DNS-01 challenge (wildcard certificate)
|
|
- **Dashboard**: Available at configured domain
|
|
- **Deploy**: Core server only
|
|
|
|
### Authelia (v4.37.5)
|
|
- **Purpose**: Single sign-on authentication service for all services across all servers
|
|
- **Port**: 9091 (internal)
|
|
- **Access**: Configured authentication domain
|
|
- **Configuration**: Located in `authelia/config/`
|
|
- **Database**: SQLite database in `authelia/config/db.sqlite3`
|
|
- **Deploy**: Core server only
|
|
|
|
## Multi-Server Architecture
|
|
|
|
The core stack on the main server provides centralized services for the entire homelab:
|
|
|
|
**Core Server:**
|
|
- Receives all external traffic (ports 80/443 forwarded from router)
|
|
- Runs DuckDNS for domain management and SSL certificates
|
|
- Runs Authelia for centralized authentication
|
|
- Runs Sablier for lazyloading local containers
|
|
- Traefik lables route servies on the core server
|
|
- Traekif external-host-servername.yml defines routes for Remote Servers
|
|
|
|
**Remote Server:**
|
|
- Each container exposes ports
|
|
- No port forwarding from router needed
|
|
- No Traefik lables
|
|
- Traefik configured by an external-host yaml file on Core Server
|
|
- Runs Sablier for lazyloading local containers
|
|
|
|
**Service Access:**
|
|
- All services accessible via: `https://service.yourdomain.duckdns.org`
|
|
- Core Traefik routes to appropriate server (local or remote)
|
|
- Single wildcard SSL certificate used for all services
|
|
- Authelia provides SSO for all protected services
|
|
|
|
## ⚠️ Version Pinning & Breaking Changes
|
|
|
|
### Authelia Version Pinning
|
|
**Current Version**: `authelia/authelia:4.37.5`
|
|
|
|
**Breaking Changes Identified**:
|
|
- Authelia v4.39.15+ has breaking configuration changes that are incompatible with the current setup
|
|
- Database schema changes may require migration or recreation
|
|
- Configuration file format changes may break existing setups
|
|
|
|
**Action Taken**:
|
|
- Pinned to v4.37.5 which is confirmed working
|
|
- Database recreated from scratch to ensure compatibility
|
|
- Configuration files verified and working
|
|
|
|
**Upgrade Path**:
|
|
- Test upgrades in a separate environment first
|
|
- Backup configuration and database before upgrading
|
|
- Check Authelia changelog for breaking changes
|
|
- Consider using Authelia's migration tools if available
|
|
|
|
### Traefik Version Pinning
|
|
**Current Version**: `traefik:v3`
|
|
|
|
**Notes**:
|
|
- Traefik v3 is stable and working with current configuration
|
|
- Configuration format is compatible
|
|
- No breaking changes identified in current setup
|
|
|
|
## Configuration Requirements
|
|
|
|
### File Structure
|
|
```
|
|
core/
|
|
├── docker-compose.yml # Main service definitions
|
|
├── .env # Environment variables
|
|
├── authelia/
|
|
│ ├── config/
|
|
│ | ├── configuration.yml # Authelia main config
|
|
│ | └── notification.txt
|
|
| └── secrets/
|
|
| └── users_database.yml # User credentials
|
|
├── duckdns/
|
|
│ └── config/ # DuckDNS configuration
|
|
├── traefik/
|
|
│ ├── config/
|
|
│ │ └── traefik.yml # Traefik static config
|
|
│ ├── dynamic/ # Dynamic configurations
|
|
│ │ ├── routes.yml
|
|
│ │ ├── sablier.yml
|
|
│ │ └── external-host-*.yml # Remote server routing
|
|
│ └── letsencrypt/
|
|
│ └── acme.json # SSL certificates
|
|
|
|
```
|