Datacenter-Control-Complete/ENV_SETUP.md

# Environment Variables Setup Guide

This guide explains all environment variables needed for the Omada Cloud Integration System.

## Quick Setup

1. **Copy the template:**
   ```bash
   cp env.example .env
   ```

   Or use the setup script:
   ```bash
   pnpm run setup:env
   ```

2. **Edit `.env` and fill in your values** (see details below)

## Required Environment Variables

### Omada Cloud Authentication

You can use **either** OAuth (Client ID/Secret) **or** Username/Password authentication. The system will automatically detect which method to use based on which credentials are provided.

#### Option 1: OAuth Authentication (Recommended)

If you have TP-LINK Open API credentials:

```env
TP_LINK_CLIENT_ID=your-client-id-here
TP_LINK_CLIENT_SECRET=your-client-secret-here
TP_LINK_APPLICATION=Datacenter-Control-Complete
TP_LINK_REDIRECT_URI=http://localhost:3000/callback
TP_LINK_API_BASE_URL=https://openapi.tplinkcloud.com
```

**How to get these:**
- Register your application at TP-LINK Developer Portal
- Create an OAuth app to get Client ID and Secret
- Set the redirect URI to match your application

**Note:** OAuth implementation is currently in progress. For now, use username/password authentication.

#### Option 2: Username/Password Authentication

```env
OMADA_USERNAME=your-omada-email@example.com
OMADA_PASSWORD=your-strong-password
```

**How to find these values:**
- `OMADA_USERNAME`: Your Omada cloud account email
- `OMADA_PASSWORD`: Your Omada cloud account password

### Omada Cloud Configuration (Required)

These are **always required** regardless of authentication method:

```env
OMADA_ID=b7335e3ad40ef0df060a922dcf5abdf5
OMADA_CONTROLLER_BASE=https://euw1-omada-controller.tplinkcloud.com
OMADA_NORTHBOUND_BASE=https://euw1-omada-northbound.tplinkcloud.com
```

**How to find these values:**
- `OMADA_ID`: Found in your Omada controller URL (the long hex string)
- `OMADA_CONTROLLER_BASE`: Base URL for authentication (usually `https://{region}-omada-controller.tplinkcloud.com`)
- `OMADA_NORTHBOUND_BASE`: Base URL for API calls (usually `https://{region}-omada-northbound.tplinkcloud.com`)

### Database

```env
DATABASE_URL=postgresql://user:password@localhost:5432/omada_db?schema=public
```

**For Docker Compose (local development):**
```env
DATABASE_URL=postgresql://omada_user:omada_password@localhost:5432/omada_db?schema=public
```

**For production:** Use your actual PostgreSQL connection string.

### Authentication

```env
JWT_SECRET=your-jwt-secret-key-change-in-production-minimum-32-characters
```

**Generate a secure secret:**
```bash
openssl rand -base64 32
```

## Optional Environment Variables

### Server Configuration

```env
PORT=3000                    # API server port (default: 3000)
NODE_ENV=development         # Environment: development, staging, production
```

### Logging

```env
LOG_LEVEL=info               # Log level: error, warn, info, debug
```

**Recommended values:**
- Development: `debug` (detailed logs)
- Production: `info` or `warn` (less verbose)

### Background Jobs

```env
SYNC_JOB_SCHEDULE=*/10 * * * *      # Inventory sync schedule (default: every 10 minutes)
LICENSE_JOB_SCHEDULE=0 9 * * *      # License check schedule (default: daily at 9 AM)
```

**Cron format:** `minute hour day month day-of-week`

**Examples:**
- `*/10 * * * *` - Every 10 minutes
- `0 * * * *` - Every hour
- `0 9 * * *` - Daily at 9 AM
- `0 9 * * 1` - Every Monday at 9 AM
- `0 0 1 * *` - First day of every month at midnight

## Complete Example

Here's a complete `.env` file example for local development:

```env
# Omada Cloud Credentials
OMADA_USERNAME=admin@example.com
OMADA_PASSWORD=SecurePassword123!
OMADA_ID=b7335e3ad40ef0df060a922dcf5abdf5
OMADA_CONTROLLER_BASE=https://euw1-omada-controller.tplinkcloud.com
OMADA_NORTHBOUND_BASE=https://euw1-omada-northbound.tplinkcloud.com

# Database (Docker Compose)
DATABASE_URL=postgresql://omada_user:omada_password@localhost:5432/omada_db?schema=public

# Server
PORT=3000
NODE_ENV=development

# Authentication
JWT_SECRET=$(openssl rand -base64 32)

# Logging
LOG_LEVEL=debug

# Background Jobs
SYNC_JOB_SCHEDULE=*/10 * * * *
LICENSE_JOB_SCHEDULE=0 9 * * *
```

## Validation

The application will validate all required environment variables on startup. If any are missing, you'll see an error message listing which variables need to be set.

## Security Notes

1. **Never commit `.env` to version control** - it's already in `.gitignore`
2. **Use strong passwords** for `OMADA_PASSWORD` and `JWT_SECRET`
3. **Rotate secrets regularly** in production
4. **Use environment-specific values** - different `.env` files for dev/staging/prod
5. **Consider using secrets management** in production (AWS Secrets Manager, HashiCorp Vault, etc.)

## Troubleshooting

### "Missing required environment variables" error

Check that all required variables are set in your `.env` file:
- `OMADA_USERNAME`
- `OMADA_PASSWORD`
- `OMADA_ID`
- `OMADA_CONTROLLER_BASE`
- `OMADA_NORTHBOUND_BASE`
- `DATABASE_URL`
- `JWT_SECRET`

### Database connection errors

Verify your `DATABASE_URL` is correct:
- Check PostgreSQL is running
- Verify username, password, host, and port
- Ensure the database exists
- Check network connectivity

### Omada authentication failures

Verify your Omada credentials:
- Check `OMADA_USERNAME` and `OMADA_PASSWORD` are correct
- Verify `OMADA_ID` matches your controller
- Ensure `OMADA_CONTROLLER_BASE` and `OMADA_NORTHBOUND_BASE` are correct for your region