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

env documentation

Browse Source
This commit is contained in:
kelinfoxy
2026-01-21 17:10:55 -05:00
parent 2dc6bdec81
commit c6d14d4904
8 changed files with 409 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
.env.example
View File

@@ -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
@@ -218,5 +219,3 @@ 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

52
.github/copilot-instructions.md vendored
View File

@@ -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:

2
README.md
View File

@@ -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

56
docs/ai-management-prompts.md
View File

@@ -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

221
docs/env-configuration.md Normal file
View File

@@ -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`

3
docs/getting-started.md
View File

@@ -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))

42
docs/post-setup.md
View File

@@ -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

14
tasks.txt
View File

@@ -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