Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
222
README.md
Normal file
222
README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd Datacenter-Control-Complete
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
Create a `.env` file in the project root:
|
||||
|
||||
```env
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Generate Prisma client
|
||||
pnpm run prisma:generate
|
||||
|
||||
# Run migrations
|
||||
pnpm run prisma:migrate
|
||||
```
|
||||
|
||||
### 4. Start the Application
|
||||
|
||||
**Development:**
|
||||
```bash
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
**Production:**
|
||||
```bash
|
||||
pnpm run build
|
||||
pnpm start
|
||||
```
|
||||
|
||||
**Docker Compose:**
|
||||
```bash
|
||||
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](CONTRIBUTING.md) for guidelines.
|
||||
Reference in New Issue
Block a user