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:

   cp env.example .env
   

   Or use the setup script:

   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:

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

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:

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

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

For Docker Compose (local development):

DATABASE_URL=postgresql://omada_user:omada_password@localhost:5432/omada_db?schema=public

For production: Use your actual PostgreSQL connection string.

Authentication

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

Generate a secure secret:

openssl rand -base64 32

Optional Environment Variables

Server Configuration

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

Logging

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

Recommended values:

• Development: debug (detailed logs)
• Production: info or warn (less verbose)

Background Jobs

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:

# 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