EZ-Homelab/docs/env-configuration.md

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