Datacenter-Control-Complete/README.md

Datacenter Control Complete

A comprehensive datacenter control system integrated with TP-Link Omada Cloud (northbound API) for centralized network device management, inventory tracking, configuration automation, and monitoring.

Features

• Omada Cloud Integration: Connect to TP-Link Omada Cloud controller via northbound API
• Device Management: Discover and manage gateways, switches, EAPs, and clients across multiple sites
• Configuration Automation: Programmatically configure WAN, VLANs, SSIDs, and more
• Inventory Sync: Automatic periodic synchronization of sites and devices
• License Monitoring: Track and alert on expiring device licenses
• REST API: Clean, type-safe API for integration with other systems
• Audit Logging: Complete audit trail of all configuration changes
• Configuration Templates: Reusable templates for device configuration

Architecture

• Backend: Node.js with TypeScript
• Database: PostgreSQL with Prisma ORM
• API: Express.js REST API
• Background Jobs: node-cron for scheduled tasks
• Logging: Winston with file and console transports

Prerequisites

• Node.js 20+ and pnpm
• PostgreSQL 15+
• Docker and Docker Compose (optional, for containerized deployment)

Quick Start

1. Clone and Install

git clone <repository-url>
cd Datacenter-Control-Complete
pnpm install

2. Configure Environment

Create a .env file in the project root:

# Omada Cloud Credentials
OMADA_USERNAME=your-omada-email@example.com
OMADA_PASSWORD=your-strong-password
OMADA_ID=b7335e3ad40ef0df060a922dcf5abdf5
OMADA_CONTROLLER_BASE=https://euw1-omada-controller.tplinkcloud.com
OMADA_NORTHBOUND_BASE=https://euw1-omada-northbound.tplinkcloud.com

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

# API Server
PORT=3000
NODE_ENV=development

# Authentication
JWT_SECRET=your-jwt-secret-key-change-in-production

# Logging
LOG_LEVEL=info

3. Set Up Database

# Generate Prisma client
pnpm run prisma:generate

# Run migrations
pnpm run prisma:migrate

4. Start the Application

Development:

pnpm run dev

Production:

pnpm run build
pnpm start

Docker Compose:

docker-compose up -d

API Endpoints

Sites

• GET /api/sites - List all sites (from database)
• POST /api/sync/sites - Sync sites from Omada to database
• GET /api/sites/:siteId - Get site details
• GET /api/sites/:siteId/devices - List devices for a site

Devices

• GET /api/devices/:deviceId - Get device details
• POST /api/devices/:deviceId/reboot - Reboot a device
• POST /api/devices/:deviceId/locate - Locate a device (blink LED)

Configuration

• GET /api/devices/:deviceId/wan - Get gateway WAN configuration
• PUT /api/devices/:deviceId/wan - Update gateway WAN configuration
• GET /api/devices/:deviceId/ports - Get switch ports
• POST /api/devices/:deviceId/ports/:portIndex/vlan - Set switch port VLAN
• GET /api/sites/:siteId/wlans - List SSIDs for a site
• POST /api/sites/:siteId/wlans - Create a new SSID
• PUT /api/sites/:siteId/wlans/:wlanId - Update an existing SSID

Templates

• GET /api/templates - List all configuration templates
• GET /api/templates/:templateId - Get template details
• POST /api/templates - Create a new template
• PUT /api/templates/:templateId - Update a template
• DELETE /api/templates/:templateId - Delete a template
• POST /api/devices/:deviceId/apply-template/:templateId - Apply template to device

Health

• GET /health - Health check endpoint

Background Jobs

The system runs two background jobs:

1. Inventory Sync (every 10 minutes): Syncs sites and devices from Omada to the database
2. License Check (daily at 9 AM): Checks for expiring licenses and generates alerts

Job schedules can be customized via environment variables:

• SYNC_JOB_SCHEDULE - Cron expression for inventory sync (default: */10 * * * *)
• LICENSE_JOB_SCHEDULE - Cron expression for license check (default: 0 9 * * *)

Database Schema

The system uses PostgreSQL with the following main tables:

• sites - Site information synced from Omada
• devices - Device inventory with health scores and license status
• config_templates - Reusable configuration templates
• device_config_applied - History of template applications
• audit_logs - Complete audit trail of all actions

Development

Project Structure

src/
  config/          # Configuration management
  lib/             # Shared utilities (logger, httpClient, db)
  services/        # Omada API service layer
  jobs/            # Background jobs
  api/             # REST API routes and middleware
  db/              # Prisma schema
  types/           # TypeScript type definitions
  index.ts         # Application entrypoint

Scripts

• pnpm run dev - Start development server with hot reload
• pnpm run build - Build TypeScript to JavaScript
• pnpm start - Start production server
• pnpm run prisma:generate - Generate Prisma client
• pnpm run prisma:migrate - Run database migrations
• pnpm run prisma:studio - Open Prisma Studio (database GUI)

Security Considerations

• All Omada credentials stored in environment variables (never commit .env)
• Token refresh logic prevents expired token usage
• Audit logging for all write operations
• Parameterized queries via Prisma (SQL injection protection)
• API authentication middleware (currently permissive in development)

Production Deployment

1. Set NODE_ENV=production
2. Use strong JWT_SECRET for API authentication
3. Configure proper database connection pooling
4. Set up log rotation for Winston logs
5. Use secrets management (AWS Secrets Manager, HashiCorp Vault, etc.)
6. Enable rate limiting on API endpoints
7. Set up monitoring and alerting

Troubleshooting

Database Connection Issues

• Verify DATABASE_URL is correct
• Ensure PostgreSQL is running and accessible
• Check database user permissions

Omada Authentication Failures

• Verify OMADA_USERNAME, OMADA_PASSWORD, and OMADA_ID are correct
• Check that controller and northbound base URLs are correct
• Review logs for specific error messages

Sync Job Failures

• Check logs in logs/combined.log and logs/error.log
• Verify Omada API connectivity
• Ensure database is accessible

License

[Add license information here]

Contributing

See CONTRIBUTING.md for guidelines.