From c6d14d490450fc91f9b7e66d51168d065230305e Mon Sep 17 00:00:00 2001 From: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com> Date: Wed, 21 Jan 2026 17:10:55 -0500 Subject: [PATCH] env documentation --- .env.example | 73 ++++++----- .github/copilot-instructions.md | 52 ++++++++ README.md | 2 +- docs/ai-management-prompts.md | 56 ++++++-- docs/env-configuration.md | 221 ++++++++++++++++++++++++++++++++ docs/getting-started.md | 3 +- docs/post-setup.md | 42 +++++- tasks.txt | 14 ++ 8 files changed, 409 insertions(+), 54 deletions(-) create mode 100644 docs/env-configuration.md diff --git a/.env.example b/.env.example index 9986d25..009c3a7 100644 --- a/.env.example +++ b/.env.example @@ -2,10 +2,6 @@ # Copy this file to .env and fill in your values: cp .env.example .env # NEVER commit .env to git! -# ==================================== -# SYSTEM CONFIGURATION -# ==================================== - # User and Group IDs (get with: id -u and id -g) PUID=1000 PGID=1000 @@ -16,6 +12,11 @@ TZ=America/New_York # Server IP address SERVER_IP=192.168.1.100 +# Default credentials (used by multiple services for easier setup) +DEFAULT_USER=admin +DEFAULT_PASSWORD=changeme +DEFAULT_EMAIL=admin@example.com + # ==================================== # DOMAIN & DNS CONFIGURATION # ==================================== @@ -28,8 +29,8 @@ DUCKDNS_TOKEN=your-duckdns-token DUCKDNS_SUBDOMAINS=yourdomain # Without .duckdns.org # Let's Encrypt / ACME (for SSL certificates) -ACME_EMAIL=your-email@example.com -ADMIN_EMAIL=your-email@example.com # Used for admin user account +ACME_EMAIL=${DEFAULT_EMAIL} +ADMIN_EMAIL=${DEFAULT_EMAIL} # Used for admin user account # Cloudflare API (optional, for DNS challenge instead of DuckDNS) # CF_DNS_API_TOKEN=your-cloudflare-api-token @@ -47,9 +48,9 @@ AUTHELIA_STORAGE_ENCRYPTION_KEY=generate-with-openssl-rand-hex-64 # Authelia Admin Credentials # These will be auto-generated by setup-homelab.sh # DO NOT set these manually - they are generated during setup -# AUTHELIA_ADMIN_USER=admin -# AUTHELIA_ADMIN_EMAIL=admin@example.com -# AUTHELIA_ADMIN_PASSWORD=auto-generated-password +# AUTHELIA_ADMIN_USER=${DEFAULT_USER} +# AUTHELIA_ADMIN_EMAIL=${DEFAULT_EMAIL} +# AUTHELIA_ADMIN_PASSWORD=${DEFAULT_PASSWORD} # SMTP for Authelia Notifications (OPTIONAL) # If not configured, notifications are saved to file instead @@ -101,14 +102,14 @@ PLEX_CLAIM=claim-xxxxxxxxxx # qBittorrent QBITTORRENT_USER=admin -QBITTORRENT_PASS=changeme +QBITTORRENT_PASS=${DEFAULT_PASSWORD} # ==================================== # INFRASTRUCTURE SERVICES # ==================================== # Pi-hole -PIHOLE_PASSWORD=changeme +PIHOLE_PASSWORD=${DEFAULT_PASSWORD} # Watchtower Notifications (optional) # If not set, Watchtower will still update containers but without notifications @@ -123,52 +124,52 @@ PIHOLE_PASSWORD=changeme # MONITORING & DASHBOARDS # ==================================== -GRAFANA_ADMIN_PASSWORD=changeme +GRAFANA_ADMIN_PASSWORD=${DEFAULT_PASSWORD} # ==================================== # DEVELOPMENT TOOLS # ==================================== -CODE_SERVER_PASSWORD=changeme -CODE_SERVER_SUDO_PASSWORD=changeme +CODE_SERVER_PASSWORD=${DEFAULT_PASSWORD} +CODE_SERVER_SUDO_PASSWORD=${DEFAULT_PASSWORD} -JUPYTER_TOKEN=changeme +JUPYTER_TOKEN=${DEFAULT_PASSWORD} # ==================================== # DATABASES - GENERAL # ==================================== -POSTGRES_USER=postgres -POSTGRES_PASSWORD=changeme +POSTGRES_USER=${DEFAULT_USER} +POSTGRES_PASSWORD=${DEFAULT_PASSWORD} POSTGRES_DB=homelab -PGADMIN_EMAIL=admin@example.com -PGADMIN_PASSWORD=changeme +PGADMIN_EMAIL=${DEFAULT_EMAIL} +PGADMIN_PASSWORD=${DEFAULT_PASSWORD} # ==================================== # PRODUCTIVITY SERVICES # ==================================== # Nextcloud -NEXTCLOUD_ADMIN_USER=admin -NEXTCLOUD_ADMIN_PASSWORD=changeme -NEXTCLOUD_DB_PASSWORD=changeme -NEXTCLOUD_DB_ROOT_PASSWORD=changeme +NEXTCLOUD_ADMIN_USER=${DEFAULT_USER} +NEXTCLOUD_ADMIN_PASSWORD=${DEFAULT_PASSWORD} +NEXTCLOUD_DB_PASSWORD=${DEFAULT_PASSWORD} +NEXTCLOUD_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD} # Gitea -GITEA_DB_PASSWORD=changeme +GITEA_DB_PASSWORD=${DEFAULT_PASSWORD} # WordPress -WORDPRESS_DB_PASSWORD=changeme -WORDPRESS_DB_ROOT_PASSWORD=changeme +WORDPRESS_DB_PASSWORD=${DEFAULT_PASSWORD} +WORDPRESS_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD} # BookStack -BOOKSTACK_DB_PASSWORD=changeme -BOOKSTACK_DB_ROOT_PASSWORD=changeme +BOOKSTACK_DB_PASSWORD=${DEFAULT_PASSWORD} +BOOKSTACK_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD} # MediaWiki -MEDIAWIKI_DB_PASSWORD=changeme -MEDIAWIKI_DB_ROOT_PASSWORD=changeme +MEDIAWIKI_DB_PASSWORD=${DEFAULT_PASSWORD} +MEDIAWIKI_DB_ROOT_PASSWORD=${DEFAULT_PASSWORD} # ==================================== # UTILITIES @@ -176,17 +177,17 @@ MEDIAWIKI_DB_ROOT_PASSWORD=changeme # Bitwarden (Vaultwarden) Password Manager # Admin token: openssl rand -base64 48 -BITWARDEN_ADMIN_TOKEN=changeme-bitwarden-admin-token +BITWARDEN_ADMIN_TOKEN=${DEFAULT_PASSWORD} BITWARDEN_SIGNUPS_ALLOWED=true # Set to false after creating accounts BITWARDEN_INVITATIONS_ALLOWED=true SMTP_HOST=smtp.gmail.com -SMTP_FROM=bitwarden@yourdomain.com +SMTP_FROM=${DEFAULT_EMAIL} SMTP_PORT=587 SMTP_SECURITY=starttls # Form.io -FORMIO_JWT_SECRET=changeme -FORMIO_DB_SECRET=changeme +FORMIO_JWT_SECRET=${DEFAULT_PASSWORD} +FORMIO_DB_SECRET=${DEFAULT_PASSWORD} # ==================================== # HOMEPAGE DASHBOARD - API KEYS @@ -217,6 +218,4 @@ HOMEPAGE_VAR_UPTIMEKUMA_SLUG=your-uptime-kuma-slug HOMEPAGE_VAR_OPENWEATHER_KEY=your-openweather-api-key HOMEPAGE_VAR_WEATHERAPI_KEY=your-weatherapi-key HOMEPAGE_VAR_UNIFI_USER=your-unifi-username -HOMEPAGE_VAR_UNIFI_PASS=your-unifi-password - -# Add your own variables below +HOMEPAGE_VAR_UNIFI_PASS=your-unifi-password \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5c0f42b..ebe83f7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -356,6 +356,58 @@ ls -lh /opt/stacks/core/traefik/acme.json # Should be 600 permissions ``` Verify: DuckDNS token valid, `DUCKDNS_TOKEN` in `.env`, DNS propagation (wait 2-5 min), acme.json writable by Traefik +### Stuck Processes and Resource Issues +```bash +# Check for stuck processes +ps aux | grep -E "(copilot|vscode|node)" | grep -v grep + +# Monitor system resources +top -b -n1 | head -20 + +# Kill stuck processes (be careful!) +kill -9 PID # Replace PID with actual process ID + +# Check Docker container resource usage +docker stats --no-stream + +# Clean up stopped containers +docker container prune -f +``` + +### File Permission Issues +```bash +# Check file ownership +ls -la /opt/stacks/stack-name/config/ + +# Fix permissions for Docker volumes +sudo chown -R 1000:1000 /opt/stacks/stack-name/config/ + +# Validate PUID/PGID in .env +echo "PUID: $PUID, PGID: $PGID" +id -u && id -g # Should match PUID/PGID + +# Check volume mount permissions +docker run --rm -v /opt/stacks/stack-name/config:/test busybox ls -la /test +``` + +### System Health Checks +```bash +# Check Docker daemon status +sudo systemctl status docker + +# Verify network connectivity +ping -c 3 google.com + +# Check DNS resolution +nslookup yourdomain.duckdns.org + +# Monitor disk space +df -h + +# Check system load +uptime && cat /proc/loadavg +``` + ## AI Management Capabilities You can manage this homelab by: diff --git a/README.md b/README.md index 9a076b4..6607116 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ sudo ./scripts/deploy-homelab.sh **Access your homelab:** - **Dockge**: `https://dockge.yourdomain.duckdns.org` (primary management interface) -- **Homepage**: `https://home.yourdomain.duckdns.org` (service dashboard) +- **Homepage**: `https://homepage.yourdomain.duckdns.org` (service dashboard) - **Authelia**: `https://auth.yourdomain.duckdns.org` (SSO login) ## 📚 Documentation diff --git a/docs/ai-management-prompts.md b/docs/ai-management-prompts.md index 0ece322..286bd4d 100644 --- a/docs/ai-management-prompts.md +++ b/docs/ai-management-prompts.md @@ -4,29 +4,35 @@ This guide provides example prompts you can use with GitHub Copilot to manage yo ## Container and Stack Management -### Starting Services -- "Start the media stack" -- "Deploy the monitoring services" -- "Launch the productivity applications" +### Controling Services +- "Start/Pause/Stop/Restart the media stack" +- "Start/Pause/Stop/Restart wordpress" +- "Deploy the monitoring stack" - "Bring up the core infrastructure" -### Stopping Services -- "Stop the media stack" -- "Shut down the monitoring services" -- "Pause the productivity applications" -- "Take down the core infrastructure" -### Restarting Services -- "Restart the media stack" -- "Reload the monitoring services" -- "Reboot the productivity applications" -- "Refresh the core infrastructure" +### Restarting a service vs restarting a stack + +Restarting a container (service) does NOT pick up changes to the compose file + +Restarting a stack uses docker compose down && docker compose up -d +This DOES load changes to the compose file + +Restart traefik/sablier container(s) to apply configuration changes +Restart the core stack to apply changes to the compose file + +Homepage configuration is loaded on demand, no restart needed ### Status Checks + +>If your server keeps locking up, it's likely stuck background processes. +VS Code Copilot Chat in Agent mode sometimes leaves a stuck process running (in my experience) + - "Show me the status of all containers" - "Check if the media services are running" - "List all deployed stacks" - "Monitor container resource usage" +- "Check for and close any stuck proccesses hogging system resources" ## Service Configuration @@ -68,6 +74,28 @@ This guide provides example prompts you can use with GitHub Copilot to manage yo - "Verify network connectivity between services" - "Test SSL certificate validity" +### System Health Checks +- "Check for stuck processes consuming resources" +- "Monitor system load and identify bottlenecks" +- "Verify file permissions for Docker volumes" +- "Check Docker daemon status and logs" +- "Validate network connectivity and DNS resolution" +- "Review system resource limits and quotas" + +### Stuck Process Investigation +- "Find and terminate any stuck AI assistant processes" +- "Check for runaway Docker containers" +- "Monitor background jobs and cleanup if needed" +- "Review system process table for anomalies" +- "Check VS Code extension processes that may be hanging" + +### File Permission Issues +- "Fix permission problems with Docker volumes" +- "Set correct ownership for service configuration files" +- "Resolve access denied errors for mounted directories" +- "Validate PUID/PGID settings match system users" +- "Check and repair file system permissions recursively" + ## Backup and Recovery ### Creating Backups diff --git a/docs/env-configuration.md b/docs/env-configuration.md new file mode 100644 index 0000000..c49d108 --- /dev/null +++ b/docs/env-configuration.md @@ -0,0 +1,221 @@ +# Environment Configuration Guide + +This guide explains how to configure the `.env` file required for your AI-Homelab deployment. + +## Prerequisites + +Before running the setup scripts, you must create and configure a `.env` file in the root of the repository. + +### Step 1: Copy the Example File + +```bash +# Copy the example file to create your .env file +cp .env.example .env +``` + +This ensures you have all the required variables with proper defaults and structure. + +### Step 2: Edit Your Configuration + +Open the newly created `.env` file and modify the values to match your setup: + +```bash +# Edit the file with your preferred editor +nano .env # or use any text editor +``` + +## Required Variables + +The `.env` file contains the following key variables that you must configure: + +```bash +# Domain Configuration +DOMAIN=yourdomain.duckdns.org +DUCKDNS_TOKEN=your-duckdns-token +DUCKDNS_SUBDOMAINS=yourdomain + +# User Configuration (Linux user IDs) +PUID=1000 +PGID=1000 + +# Default Credentials (used by multiple services) +DEFAULT_USER=admin +DEFAULT_PASSWORD=changeme +DEFAULT_EMAIL=admin@example.com + +# Timezone +TZ=America/New_York + +# Authelia Secrets (auto-generated by setup script) +AUTHELIA_JWT_SECRET=64-char-secret +AUTHELIA_SESSION_SECRET=64-char-secret +AUTHELIA_STORAGE_ENCRYPTION_KEY=64-char-secret + +# VPN Configuration (optional, for download services) +SURFSHARK_PRIVATE_KEY=your-vpn-private-key +``` + +## Step-by-Step Configuration + +### 1. Domain Setup + +**DuckDNS Configuration:** +1. Go to [duckdns.org](https://duckdns.org) +2. Create an account and get your token +3. Choose your subdomain (e.g., `yourname`) +4. Your domain will be `yourname.duckdns.org` + +```bash +DOMAIN=yourname.duckdns.org +DUCKDNS_TOKEN=your-actual-token-here +DUCKDNS_SUBDOMAINS=yourname +``` + +### 2. User IDs + +Get your Linux user and group IDs: + +```bash +# Run these commands to get your IDs +id -u # This gives you PUID +id -g # This gives you PGID +``` + +Typically these are both `1000` for the first user. + +### 3. Default Credentials + +Set default credentials that will be used by multiple services for easier setup: + +```bash +DEFAULT_USER=admin +DEFAULT_PASSWORD=changeme +DEFAULT_EMAIL=admin@example.com +``` + +**Why these variables?** +- Many services (Nextcloud, Grafana, databases, etc.) use similar admin credentials +- Setting defaults here makes it easier to manage and remember passwords +- You can change these to your preferred values +- Individual services will use these defaults unless overridden + +### 4. Timezone + +Set your timezone. Common options: +- `America/New_York` +- `America/Los_Angeles` +- `Europe/London` +- `Asia/Tokyo` +- `Australia/Sydney` + +### 4. Authelia Secrets + +**⚠️ IMPORTANT:** These are auto-generated by the setup script. Do NOT set them manually. + +The `setup-homelab.sh` script will generate secure random secrets for: +- JWT Secret (64 hex characters) +- Session Secret (64 hex characters) +- Storage Encryption Key (64 hex characters) + +### 5. VPN Configuration (Optional) + +If you want to route download services through VPN: + +1. Get Surfshark WireGuard credentials +2. Extract the private key from your `.conf` file +3. Add to `.env`: + +```bash +SURFSHARK_PRIVATE_KEY=your-private-key-here +``` + +## Setup Process + +### Step 1: Copy the Template + +```bash +# Copy the example file (this creates your .env file) +cp .env.example .env +``` + +### Step 2: Edit Required Variables + +Open `.env` in your editor and update these essential variables: + +```bash +# Required: Set your domain +DOMAIN=yourdomain.duckdns.org +DUCKDNS_TOKEN=your-actual-duckdns-token +DUCKDNS_SUBDOMAINS=yourdomain + +# User Configuration (Linux user IDs) +PUID=1000 +PGID=1000 + +# Required: Set default credentials +DEFAULT_USER=admin +DEFAULT_PASSWORD=your-secure-password +DEFAULT_EMAIL=your-email@example.com + +# Required: Set your timezone +TZ=America/New_York + +# Optional: Configure VPN if using download services +# Note: these are not the same as what you use to log into surfshark.com with +SURFSHARK_USERNAME=your-surfshark-username +SURFSHARK_PASSWORD=your-surfshark-password +``` + +### Step 3: Review and Customize + +The `.env.example` file contains all available configuration options. Review and customize: + +- **Default Credentials**: Used by multiple services for consistency +- **Service-Specific Settings**: API keys, database passwords, etc. +- **Directory Paths**: Adjust for your storage setup +- **Optional Features**: VPN, monitoring, development tools + +## Validation + +After creating your `.env` file: + +```bash +# Check that all required variables are set +grep -E "^(DOMAIN|DUCKDNS_TOKEN|PUID|PGID|TZ|DEFAULT_USER|DEFAULT_PASSWORD|DEFAULT_EMAIL)=" .env + +# Validate domain format +echo $DOMAIN | grep -E "\.duckdns\.org$" +``` + +## Security Notes + +- Never commit `.env` files to git +- Keep your DuckDNS token secure +- The setup script generates cryptographically secure secrets for Authelia +- VPN keys should be kept confidential + +## Troubleshooting + +**Missing .env file:** +``` +Error: .env file not found +``` +→ Copy the example file: `cp .env.example .env` + +**Invalid domain:** +``` +Error: DOMAIN must end with .duckdns.org +``` +→ Check your domain format in the `.env` file + +**Missing DuckDNS token:** +``` +Error: DUCKDNS_TOKEN is required +``` +→ Get your token from duckdns.org and add it to `.env` + +**Permission issues:** +``` +Error: Cannot write to .env +``` +→ Check file permissions: `chmod 600 .env` \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index 545835d..9890a8a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,7 +4,8 @@ Welcome to your AI-powered homelab! This guide will walk you through setting up ## Getting Started Checklist - [ ] Clone this repository to your home folder -- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](#prerequisites)) +- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](env-configuration.md)) +- [ ] Forward ports 80 and 443 from your router to your server - [ ] Run setup script (generates Authelia secrets and admin user) ([setup-homelab.sh](../scripts/setup-homelab.sh)) - [ ] Log out and back in for Docker group permissions - [ ] Run deployment script (deploys all core, infrastructure & dashboard services) ([deploy-homelab.sh](../scripts/deploy-homelab.sh)) diff --git a/docs/post-setup.md b/docs/post-setup.md index d16bd4a..a348aa9 100644 --- a/docs/post-setup.md +++ b/docs/post-setup.md @@ -4,7 +4,7 @@ Congratulations! Your AI-powered homelab is now running. Here's what to do next. ## Access Your Services -- **Homepage**: `https://home.yourdomain.duckdns.org` +- **Homepage**: `https://homepage.yourdomain.duckdns.org` - Great place to start exploring your services - After configuring your services, come back and add widgets with API keys (optional) - Or ask the AI to find the API keys and add the widgets @@ -60,6 +60,46 @@ docker compose down -v --remove-orphans docker system prune -a --volumes ``` +## Set Up Backups + +Your homelab includes comprehensive backup solutions. The default setup includes Backrest (Restic-based) for automated backups. + +### Quick Backup Setup + +1. **Access Backrest**: `https://backrest.yourdomain.duckdns.org` +2. **Configure repositories**: Add local or cloud storage destinations +3. **Set up schedules**: Configure automatic backup schedules +4. **Add backup jobs**: Create jobs for your important data + +### What to Back Up + +- **Configuration files**: `/opt/stacks/*/config/` directories +- **Databases**: Service-specific database volumes +- **User data**: Nextcloud files, Git repositories, etc. +- **Media libraries**: Movies, TV shows, music (if space allows) + +### Backup Commands + +```bash +# Manual backup of a volume +docker run --rm \ + -v source-volume:/data \ + -v /mnt/backups:/backup \ + busybox tar czf /backup/volume-backup-$(date +%Y%m%d).tar.gz /data + +# List Backrest configurations +cd /opt/stacks/utilities/backrest +docker compose exec backrest restic snapshots + +# Restore from backup +docker run --rm \ + -v target-volume:/data \ + -v /mnt/backups:/backup \ + busybox tar xzf /backup/volume-backup.tar.gz -C / +``` + +For detailed backup configuration, see the [Restic-BackRest-Backup-Guide.md](Restic-BackRest-Backup-Guide.md). + ## Troubleshooting ### Script Issues diff --git a/tasks.txt b/tasks.txt index e69de29..d6805f0 100644 --- a/tasks.txt +++ b/tasks.txt @@ -0,0 +1,14 @@ +Tasks + +.env.example + ✅ create new variables + DAFAULT_USER: admin + DEFAULT_PASSWORD: changeme + DEFAULT_EMAIL: admin@example.com + + ✅ modify existing variables to use these 3 new variables like + NEXTCLOUD_ADMIN_USER=${DEFAULT_USER} + except for QBITTORRENT_USER=admin should stay as is + the goal is ease of setup for the user + +✅ Then update env-configuration.md \ No newline at end of file