kelin/EZ-Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs update

Browse Source
This commit is contained in:
kelinfoxy
2026-01-27 13:20:22 -05:00
parent ee93f26d52
commit 552f0240b5
2 changed files with 176 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
docs/Ondemand-Remote-Services.md
View File

@@ -192,12 +192,12 @@ This section provides a complete deployment plan for scenarios where the core in
- Both servers must be on the same network and able to communicate - Both servers must be on the same network and able to communicate
- SSH access configured between servers (key-based or password authentication supported) - SSH access configured between servers (key-based or password authentication supported)
- Domain configured with DuckDNS or similar - Domain configured with DuckDNS or similar
- The EZ-Homelab script handles most Docker TLS and certificate setup automatically - The EZ-Homelab script handles Docker TLS certificate generation on the core server and automatic copying to remote servers
- Basic understanding of Docker concepts (optional - script guides you through setup) - Basic understanding of Docker concepts (optional - script guides you through setup)
## Step 1: Configure Docker TLS on All Servers ## Step 1: Configure Core Server
### On Each Server (Core and Remote) ### On Core Server Only
1. **Install Docker** (if not already installed): 1. **Install Docker** (if not already installed):
```bash ```bash
@@ -208,52 +208,35 @@ This section provides a complete deployment plan for scenarios where the core in
# Log out and back in for group changes # Log out and back in for group changes
``` ```
2. **Generate TLS Certificates**: 2. **Configure Firewall** (optional, for security):
```bash ```bash
mkdir -p ~/EZ-Homelab/docker-tls sudo ufw allow 2376/tcp # For Docker API access from remote servers
cd ~/EZ-Homelab/docker-tls
# Generate CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=Docker-CA"
# Generate server key and cert (replace SERVER_IP with actual IP)
openssl genrsa -out server-key.pem 4096
openssl req -subj "/CN=<SERVER_IP>" -new -key server-key.pem -out server.csr
echo "subjectAltName = DNS:<SERVER_IP>,IP:<SERVER_IP>,IP:127.0.0.1" > extfile.cnf
openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -extfile extfile.cnf
# Generate client key and cert
openssl genrsa -out client-key.pem 4096
openssl req -subj "/CN=client" -new -key client-key.pem -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem
```
3. **Configure Docker Daemon**:
Create `/etc/docker/daemon.json`:
```json
{
"tls": true,
"tlsverify": true,
"tlscacert": "/home/$USER/EZ-Homelab/docker-tls/ca.pem",
"tlscert": "/home/$USER/EZ-Homelab/docker-tls/server-cert.pem",
"tlskey": "/home/$USER/EZ-Homelab/docker-tls/server-key.pem"
}
```
4. **Update Systemd Service**:
```bash
sudo sed -i 's|-H fd://|-H fd:// -H tcp://0.0.0.0:2376|' /lib/systemd/system/docker.service
sudo systemctl daemon-reload
sudo systemctl restart docker
```
5. **Configure Firewall**:
```bash
sudo ufw allow 2376/tcp
sudo ufw --force enable sudo ufw --force enable
``` ```
The EZ-Homelab script will automatically generate TLS certificates and configure Docker daemon TLS when you deploy the core infrastructure.
## Step 2: Configure Remote Servers
### On Each Remote Server
1. **Install Docker** (if not already installed):
```bash
curl -fsSL https://get.docker.com | sh
usermod -aG docker $USER
systemctl enable docker
systemctl start docker
# Log out and back in for group changes
```
2. **Configure Firewall** (optional, for security):
```bash
sudo ufw allow 2376/tcp # For Docker API access from core server
sudo ufw --force enable
```
The EZ-Homelab script will automatically copy TLS certificates from the core server and configure Docker daemon TLS when you run the infrastructure-only deployment.
## Certificate and Secret Sharing ## Certificate and Secret Sharing
The EZ-Homelab script automatically handles certificate and secret sharing for infrastructure-only deployments: The EZ-Homelab script automatically handles certificate and secret sharing for infrastructure-only deployments:
@@ -264,8 +247,9 @@ The EZ-Homelab script automatically handles certificate and secret sharing for i
2. **Script Actions**: 2. **Script Actions**:
- Prompts for core server IP - Prompts for core server IP
- Tests SSH connectivity - Tests SSH connectivity
- Copies Docker TLS certificates for remote control - Copies shared CA and TLS certificates from core server
- Sets up certificates in the correct location - Generates server-specific certificates signed by the shared CA
- Configures Docker daemon for TLS on port 2376
### Manual Process (Fallback) ### Manual Process (Fallback)
@@ -273,15 +257,33 @@ If automatic sharing fails, manually share certificates:
1. **On Core Server**: 1. **On Core Server**:
```bash ```bash
# Copy client certificates to remote server # Generate server certificates for remote server
scp /opt/stacks/core/docker-tls/ca.pem /opt/stacks/core/docker-tls/client-cert.pem /opt/stacks/core/docker-tls/client-key.pem user@remote-server:/opt/stacks/infrastructure/docker-tls/ cd /opt/stacks/core/shared-ca
openssl genrsa -out server-key.pem 4096
openssl req -subj "/CN=<REMOTE_IP>" -new -key server-key.pem -out server.csr
echo "subjectAltName = DNS:<REMOTE_IP>,IP:<REMOTE_IP>,IP:127.0.0.1" > extfile.cnf
openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -extfile extfile.cnf
``` ```
2. **On Remote Server**: 2. **On Remote Server**:
```bash ```bash
# Ensure certificates are in the correct location # Copy certificates
ls -la /opt/stacks/infrastructure/docker-tls/ scp user@core-server:/opt/stacks/core/shared-ca/ca.pem /opt/stacks/core/shared-ca/
# Should contain: ca.pem, client-cert.pem, client-key.pem scp user@core-server:/opt/stacks/core/shared-ca/server-cert.pem /opt/stacks/core/shared-ca/
scp user@core-server:/opt/stacks/core/shared-ca/server-key.pem /opt/stacks/core/shared-ca/
# Update Docker daemon
sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
"tls": true,
"tlsverify": true,
"tlscacert": "/opt/stacks/core/shared-ca/ca.pem",
"tlscert": "/opt/stacks/core/shared-ca/server-cert.pem",
"tlskey": "/opt/stacks/core/shared-ca/server-key.pem"
}
EOF
sudo systemctl restart docker
``` ```
## Step 3: Deploy Core Infrastructure ## Step 3: Deploy Core Infrastructure
@@ -297,7 +299,8 @@ If automatic sharing fails, manually share certificates:
The script will: The script will:
- Generate Authelia secrets automatically - Generate Authelia secrets automatically
- Configure TLS for Docker API - Generate shared TLS CA and certificates
- Configure Docker daemon TLS
- Deploy Traefik, Authelia, and Sablier - Deploy Traefik, Authelia, and Sablier
- Set up certificates for secure communication - Set up certificates for secure communication
@@ -324,44 +327,40 @@ If automatic sharing fails, manually share certificates:
The script will automatically: The script will automatically:
- Prompt for core server IP address - Prompt for core server IP address
- Establish SSH connection to core server - Establish SSH connection to core server
- Copy Authelia secrets and TLS certificates - Copy shared CA and generate server-specific certificates
- Configure Docker TLS for remote control - Configure Docker daemon for TLS on port 2376
- Set up required networks and directories - Set up required networks and directories
2. **Manual certificate sharing** (if automatic fails): 2. **Manual certificate setup** (if automatic fails):
If SSH connection fails, manually copy certificates: If SSH connection fails, follow the manual process in the Certificate and Secret Sharing section above.
```bash
# On core server, copy certs to remote server
scp /opt/stacks/core/docker-tls/ca.pem /opt/stacks/core/docker-tls/client-cert.pem /opt/stacks/core/docker-tls/client-key.pem user@remote-server:/opt/stacks/infrastructure/docker-tls/
# On remote server, copy Authelia secrets
scp /home/kelin/EZ-Homelab/.env user@remote-server:/home/kelin/EZ-Homelab/.env.core
```
## Step 5: Configure Sablier for Remote Control ## Step 5: Configure Sablier for Remote Control
### On Core Server ### On Core Server
Update Sablier configuration to control remote servers: Sablier uses middleware configuration in Traefik's dynamic files to control remote Docker daemons. The middleware specifies the remote server connection details.
1. **Edit core docker-compose.yml**: 1. **Create Sablier middleware configuration**:
`/opt/stacks/core/traefik/dynamic/sablier.yml`
```yaml ```yaml
sablier-service: http:
environment: middlewares:
- DOCKER_HOST=tcp://<REMOTE_SERVER_IP>:2376 sablier-<remote_hostname>-<group>:
- DOCKER_TLS_VERIFY=1 plugin:
- DOCKER_CERT_PATH=/certs sablier:
volumes: sablierUrl: http://sablier-service:10000
- ./docker-tls/ca.pem:/certs/ca.pem:ro group: <remote_hostname>-<group>
- ./docker-tls/client-cert.pem:/certs/cert.pem:ro sessionDuration: 2m
- ./docker-tls/client-key.pem:/certs/key.pem:ro ignoreUserAgent: curl
dynamic:
displayName: "<Service Group Display Name>"
theme: ghost
show-details-by-default: true
``` ```
2. **Restart core stack**: 2. **Restart Traefik** to load the middleware:
```bash ```bash
cd /opt/stacks/core docker restart traefik
docker compose down
docker compose up -d
``` ```
## Step 6: Deploy Application Services ## Step 6: Deploy Application Services
@@ -386,7 +385,7 @@ Update Sablier configuration to control remote servers:
docker compose stop docker compose stop
``` ```
## Step 5: Configure Traefik Routing ## Step 7: Configure Traefik Routing
### On Core Server ### On Core Server
@@ -405,7 +404,7 @@ Since Traefik cannot auto-discover labels from remote Docker hosts, use the file
tls: tls:
certResolver: letsencrypt certResolver: letsencrypt
middlewares: middlewares:
- sablier-<remote_hostname>-arr@file - sablier-<remote_hostname>-media@file
- authelia@docker - authelia@docker
services: services:
@@ -416,30 +415,12 @@ Since Traefik cannot auto-discover labels from remote Docker hosts, use the file
passHostHeader: true passHostHeader: true
``` ```
2. **Create Sablier middleware configuration**: 2. **Restart Traefik**:
`/opt/stacks/core/traefik/dynamic/sablier.yml`
```yaml
http:
middlewares:
sablier-<remote_hostname>-arr:
plugin:
sablier:
sablierUrl: http://sablier-service:10000
group: <remote_hostname>-arr
sessionDuration: 2m
ignoreUserAgent: curl
dynamic:
displayName: "Media Management Services"
theme: ghost
show-details-by-default: true
```
3. **Restart Traefik**:
```bash ```bash
docker restart traefik docker restart traefik
``` ```
## Step 6: Verification and Testing ## Step 8: Verification and Testing
1. **Check Sablier connection**: 1. **Check Sablier connection**:
```bash ```bash
@@ -460,10 +441,11 @@ Since Traefik cannot auto-discover labels from remote Docker hosts, use the file
## Troubleshooting ## Troubleshooting
- **TLS Connection Issues**: Check certificate validity and paths - **TLS Connection Issues**: Check certificate validity and paths on both core and remote servers
- **Sablier Not Detecting Groups**: Verify DOCKER_HOST and certificates - **Sablier Not Detecting Groups**: Verify middleware configuration in `/opt/stacks/core/traefik/dynamic/sablier.yml` and that remote services have correct Sablier labels
- **Traefik Routing Problems**: Check external host YAML syntax - **Traefik Routing Problems**: Check external host YAML syntax and that Traefik has reloaded configuration
- **Network Connectivity**: Ensure ports 2376, 80, 443 are open between servers - **Network Connectivity**: Ensure ports 2376 (Docker API), 80, 443 are open between servers
- **Certificate Sharing Failed**: Verify SSH access between servers and that the shared CA exists on core server
## Security Considerations ## Security Considerations

89
release-notes-v0.1.md Normal file
View File

@@ -0,0 +1,89 @@
# Release Notes v0.1
## ez-homelab.sh
* Options 1 & 2: Require additional testing
* Option 3: Confirmed working on fresh Debian 12 install with an existing core server.
## Manual Install Instructions
* May require some refinement
## Security
* Authelia SSO
* Optional 2FA
* TLS Certificates for docker-proxy
* SSO enabled by default (except for special cases)
## DNS & Proxy
* DuckDNS & LetsEncrypt
* Traefik routing via lables for local services
* Traefik routing via external host files for remote servers
* service.yoursubdomain.duckdns.org subdomains for all exposed webui
* service.serverhostname.yoursubdomain.duckdns.org for services that are likely to run on multiple servers (dockge, glances, etc)
## Sablier lazyloading of services
>**WHY?** Saves resounces, reduces power bills, allows for running a ton of services without overtaxing your server.
>Requires the stack to be up.
* Enabled on most services by default
* Dependant services are loaded as a group (like the arr apps)
>**Downsides** Short delay while the service starts.
Occasional time-out or Bad Gateway errors in browser.
Refreshing the page will work once the container is healthy.
## UX - Setup
On a fresh install of an OS, like Debian
* Log in as root and run (replace yourusername with the username created during install)
`apt update && apt upgrade -y && apt install git sudo -y && usermod -aG sudo yourusername`
* Run `exit` to log out
* Log in with your username
* Change directory to your home folder
`cd ~`
* Run `git clone https://github.com/kelinfoxy/EZ-Homelab.git`
* run `sudo ./scripts/ez-homelab.sh` to install docker
* Log out (`exit`) and back in
* Run `./scripts/ez-homelab.sh` (without sudo) to perform the install
**Once complete**
* the script provides a link to open Dockge in a browser
* The core stack (if installed) is running
* The infrastructure stack is running
* The dashboards stack is running
* All remaining stacks show as inactive
## UX - Dashboards
>**REMEMBER** Lazyloading only works if the stacks are up
* Homepage is the default dashboard
* homepage.yoursubdomain.duckdns.org
* Preconfigured to work out of the box
# Services Preconfigured wtih Traefik and Sablier
>**NOTE**: Most services require an initial setup in the webui on first launch
* Core stack
* Infrastructure stack
* Dashboards stack
* Media stack
* Media Management stack
* Productivity stack
* Transcoders stack
* Utilities stack
* VPN stack
* Wikis stack
The Monitoring stack is not configured for traefik/sablier yet
The Alternatives stack is completely untested.
## Github Wiki
Mostly accurate, needs refinement