Initial commit: add .gitignore and README

ENV_SETUP.md

@@ -0,0 +1,198 @@
+# 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
+