env documentation

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`