Add no-keycloak and CrowdSec script variants; restore originals

Provide three tiers of the install script for both 24.04 and 26.04: - Originals (ubuntu-post-install-24.04.sh / -26.04.sh): restored to their true original state, with Keycloak intact, as a fallback baseline. (This reverts the in-place Keycloak removal from the previous commit; the cleanup now lives in the -no-keycloak variants instead.) - -no-keycloak.sh: Keycloak fully removed, Authelia as the SSO/2FA option. - -crowdsec.sh: builds on -no-keycloak and replaces fail2ban entirely with CrowdSec (SSH via auth.log/sshd collection, Caddy via caddy collection + log acquisition, firewall bouncer for enforcement, plus geo-blocking and community IP-reputation blocklists). Add SCRIPT-VARIANTS.md documenting the three tiers and how the Authelia / fail2ban / CrowdSec security layers differ. All variants pass 'bash -n'. https://claude.ai/code/session_017eA2qqq9jfF2tNtpUYL8vK
2026-06-03 11:34:43 +00:00
parent f564b4b6d8
commit 7cf82d5d28
15 changed files with 31861 additions and 45 deletions
@@ -11,7 +11,7 @@ This document describes the comprehensive security and infrastructure improvemen

 **Solution:**
 - Added `ensure_docker_dir_ownership()` helper function
- Applied to ALL 25+ services (Immich, ActualBudget, Jellyfin, etc.)
+- Applied to ALL 25+ services (Immich, Keycloak, ActualBudget, Jellyfin, etc.)
 - Fixed disaster recovery path (line 309)
 - All Docker directories now properly owned by sudo user

@@ -19,8 +19,8 @@ This document describes the comprehensive security and infrastructure improvemen

 ---

-### 2. Password & Credential Management
-**Problem:** Weak default passwords and credentials hardcoded in compose files.
+### 2. Keycloak Security Overhaul
+**Problem:** Weak default passwords, special characters causing issues, development mode in production.

 **Solutions Implemented:**

@@ -30,20 +30,35 @@ This document describes the comprehensive security and infrastructure improvemen
 - **Auto-generation:** Press ENTER to generate secure passwords automatically
 - **Validation:** Real-time password validation with retry loop

-#### Generated Secrets
- Services that need cryptographic secrets generate them automatically (e.g. Authelia's JWT, session, and storage secrets via `openssl rand`).
+#### Production vs Development Mode
+- **Production mode:** Uses `start` command, requires hostname configuration
+- **Development mode:** Uses `start-dev` command, relaxed security for testing
+- **Hostname support:** Proper `KC_HOSTNAME` configuration for public deployment

 #### Environment Variables
 - All credentials moved to `.env` file
- Passwords and secrets securely stored
+- Admin password and database password securely stored
 - No more hardcoded passwords in docker-compose.yml

+**Example Keycloak .env file structure:**
+```env
+# Keycloak Environment Variables
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=<secure-20-char-password>
+POSTGRES_DB=keycloak
+POSTGRES_USER=keycloak
+POSTGRES_PASSWORD=<secure-32-char-password>
+KC_PROXY=edge
+KC_HTTP_ENABLED=true
+KC_HOSTNAME=auth.yourdomain.com  # (if production mode)
+```
+
 ---

 ### 3. Environment Variable Management (.env Files)

 **Services Now Using .env Files:**
- ✅ Authelia (JWT/session/storage secrets + SMTP password)
+- ✅ Keycloak (admin + database passwords)
 - ✅ ActualBudget (timezone and config)
 - ✅ Immich (already had .env)
 - ✅ FindMyDevice (already had .env)
@@ -105,7 +120,7 @@ labels:

 **Services with fail2ban monitoring:**
 - ActualBudget
- Authelia
+- Keycloak
 - All other internet-facing services

 **fail2ban Configuration:**
@@ -115,10 +130,7 @@ labels:
 - Ban duration: 3600 seconds (1 hour)
 - Detection window: 600 seconds

-**Note:** When Authelia is in use, it provides its own failed-login regulation
-(account lockout after repeated failures). The Caddy fail2ban jail is
-complementary defense-in-depth at the HTTP layer. See
-`CADDY-FAIL2BAN-SETUP.md` for complete configuration.
+**Detailed Setup:** See `CADDY-FAIL2BAN-SETUP.md` for complete configuration.

 ---

@@ -142,7 +154,7 @@ PASSWORD=$(generate_password 20)  # 20-character password
 ```

 ### `validate_password(password [min_length])`
-Validates passwords for compatibility (alphanumeric only).
+Validates passwords for Keycloak compatibility.

 **Validation Rules:**
 - Minimum length (default: 12 characters)
@@ -158,9 +170,67 @@ fi

 ---

+## Keycloak Setup Guide
+
+### For ActualBudget on Pikapods
+
+1. **Install Keycloak with production mode:**
+   ```bash
+   sudo bash ubuntu-post-install.sh
+   # Select Keycloak from menu
+   # Choose production mode (y)
+   # Enter hostname: auth.yourdomain.com
+   # Press ENTER to auto-generate secure passwords
+   ```
+
+2. **Configure Caddy2:**
+   - Script automatically prompts for Caddy configuration
+   - Enter your domain (e.g., auth.yourdomain.com)
+   - Ensure DNS A record points to your server
+
+3. **Configure DNS:**
+   ```
+   auth.yourdomain.com  →  Your Server IP
+   ```
+
+4. **Access Keycloak:**
+   ```
+   https://auth.yourdomain.com
+   ```
+
+5. **Set up ActualBudget OAuth:**
+   - The script automatically creates an OAuth client for ActualBudget
+   - Client details saved to: `~/docker/keycloak/actualbudget-oauth.txt`
+   - Use these credentials in your Pikapod ActualBudget instance
+
+6. **Configure ActualBudget on Pikapods:**
+   - Go to your ActualBudget settings
+   - Enable OpenID Connect
+   - Enter your Keycloak details:
+     - Issuer: `https://auth.yourdomain.com/realms/homelab`
+     - Client ID: (from actualbudget-oauth.txt)
+     - Client Secret: (from actualbudget-oauth.txt)
+
+### For Other Self-Hosted Services
+
+The script can create generic OAuth clients for other services. After Keycloak installation, you can:
+
+1. Access Keycloak admin console
+2. Create new OAuth2/OIDC clients
+3. Configure redirect URIs for your services
+4. Use the client credentials in your service configuration
+
+**Generic Client Template:**
+- Client ID: your-service-name
+- Client Type: Confidential
+- Standard Flow Enabled: Yes
+- Valid Redirect URIs: https://your-service.com/*
+
+---
+
 ## Password Requirements Reference

-### Password Rules
+### Keycloak Passwords
 - **Minimum:** 12 characters
 - **Recommended:** 16+ characters
 - **Format:** Alphanumeric only (a-zA-Z0-9)
@@ -168,9 +238,7 @@ fi
 - **Generation:** Press ENTER for auto-generated secure passwords

 ### Why No Special Characters?
-Some services and database connection strings mishandle special characters in
-certain authentication flows. Restricting to alphanumeric ensures broad
-compatibility while remaining cryptographically strong.
+Keycloak has issues with special characters in certain authentication flows and database connection strings. Restricting to alphanumeric ensures compatibility.

 ### Password Strength with Alphanumeric Only
 - 12 characters: ~62^12 = 3.2 × 10^21 combinations
@@ -196,6 +264,21 @@ docker ps
 # Should work without permission errors
 ```

+### Keycloak
+```bash
+# Check .env file exists
+cat ~/docker/keycloak/.env
+# Should contain KEYCLOAK_ADMIN_PASSWORD and POSTGRES_PASSWORD
+
+# Check production mode
+cat ~/docker/keycloak/docker-compose.yml | grep command
+# Should show "start" for production or "start-dev" for development
+
+# Test access
+curl http://localhost:8180/health
+# Should return health status
+```
+
 ### Caddy2
 ```bash
 # Check Caddy is running
@@ -233,6 +316,20 @@ If you have existing services:
 4. Verify ownership: `ls -la ~/docker/actualbudget`
 5. Restart container: `cd ~/docker/actualbudget && docker compose restart`

+### Existing Keycloak
+1. **IMPORTANT:** Backup your data first!
+   ```bash
+   cp -r ~/docker/keycloak ~/docker/keycloak.backup
+   ```
+2. Stop existing container:
+   ```bash
+   cd ~/docker/keycloak && docker compose down
+   ```
+3. Run updated script and select Keycloak
+4. Choose whether to keep existing data or start fresh
+5. If keeping data, manually update .env with your existing passwords
+6. Restart: `docker compose up -d`
+
 ---

 ## Troubleshooting
@@ -243,6 +340,19 @@ If you have existing services:
 sudo chown -R $USER:$USER ~/docker
 ```

+### Keycloak Won't Start
+```bash
+# Check logs
+docker logs keycloak
+
+# Common issues:
+# 1. Missing KC_HOSTNAME in production mode
+# 2. Database connection failed (check postgres container)
+# 3. Port 8180 already in use
+
+# Fix: Edit .env and docker-compose.yml as needed
+```
+
 ### Caddy Certificate Errors
 ```bash
 # Check Caddy logs
@@ -265,17 +375,19 @@ sudo ufw status
 ## Security Best Practices

 1. **Change default passwords:** Even with auto-generation, review and update if needed
-2. **Enable fail2ban:** Monitor and ban malicious IPs
-3. **Regular updates:** Keep containers updated (use Watchtower in notify mode)
-4. **Backup .env files:** Store securely, separate from compose files
-5. **Use HTTPS everywhere:** Configure Caddy2 for all public services
-6. **Limit exposed ports:** Only expose necessary ports to the internet
-7. **Monitor logs:** Regular review of Caddy and fail2ban logs
+2. **Use production mode for Keycloak:** Never use development mode for internet-facing deployments
+3. **Enable fail2ban:** Monitor and ban malicious IPs
+4. **Regular updates:** Keep containers updated (use Watchtower in notify mode)
+5. **Backup .env files:** Store securely, separate from compose files
+6. **Use HTTPS everywhere:** Configure Caddy2 for all public services
+7. **Limit exposed ports:** Only expose necessary ports to the internet
+8. **Monitor logs:** Regular review of Caddy and fail2ban logs

 ---

 ## Additional Resources

+- **Keycloak Setup Guide:** `KEYCLOAK-SETUP-GUIDE.md`
 - **Caddy + fail2ban Setup:** `CADDY-FAIL2BAN-SETUP.md`
 - **Main Script:** `ubuntu-post-install.sh`
 - **Caddy Helper:** `caddy-setup-helper.sh`
@@ -290,3 +402,8 @@ If you encounter issues:
 2. Verify ownership: `ls -la ~/docker`
 3. Review this document for troubleshooting steps
 4. Check existing documentation in repository
+
+---
+
+**Last Updated:** 2026-01-13
+**Script Version:** Latest (with security improvements)