Merge pull request #17 from nutcas3/improv

Improv
2026-10-31 17:12:15 +00:00 · 2026-05-01 19:20:41 +03:00
parent 9734d3bcf2
commit 5d051bc936
3 changed files with 1214 additions and 4 deletions
@@ -0,0 +1,198 @@
+# API Gateway Quick Start Guide
+
+## Overview
+
+This guide helps you get the Telecom Platform running with Traefik as the API Gateway.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Make port 80, 443, and 8080 available
+- Domain `api.telecom.com` (or modify configuration)
+
+## Quick Start
+
+### 1. Start the Gateway
+
+```bash
+# Make the startup script executable
+chmod +x scripts/start-gateway.sh
+
+# Start the platform with API Gateway
+./scripts/start-gateway.sh
+```
+
+### 2. Configure DNS
+
+Add the domain to your hosts file:
+
+```bash
+# On Linux/macOS
+echo "127.0.0.1 api.telecom.com" | sudo tee -a /etc/hosts
+
+# On Windows (as Administrator)
+echo "127.0.0.1 api.telecom.com" >> C:\Windows\System32\drivers\etc\hosts
+```
+
+### 3. Access Services
+
+- **Traefik Dashboard**: http://localhost:8080
+- **API Documentation**: https://api.telecom.com/api/v1/swagger
+- **Web Dashboard**: http://localhost:3000
+- **Health Check**: https://api.telecom.com/api/v1/health
+
+## API Endpoints
+
+All services are now accessible through the gateway:
+
+### API Server
+- `https://api.telecom.com/api/v1/subscribers`
+- `https://api.telecom.com/api/v1/auth`
+- `https://api.telecom.com/api/v1/users`
+
+### Charging Engine
+- `https://api.telecom.com/v1/credit/{ip}/check`
+- `https://api.telecom.com/v1/credit/{ip}/deduct`
+- `https://api.telecom.com/v1/usage`
+
+### Carrier Connector
+- `https://api.telecom.com/v1/es2/download`
+- `https://api.telecom.com/v1/carrier/profile`
+
+### Packet Gateway
+- `https://api.telecom.com/v1/packet/flow`
+- `https://api.telecom.com/v1/gateway/status`
+
+## Security Features
+
+### Rate Limiting
+- **API endpoints**: 100 requests/minute, burst 200
+- **Charging endpoints**: 1000 requests/minute, burst 2000
+- **Carrier endpoints**: 50 requests/minute, burst 100
+
+### Security Headers
+- HTTPS redirection (80 -> 443)
+- XSS protection
+- Content Security Policy
+- Frame protection
+
+### Authentication
+- JWT validation (configure JWT_SECRET env var)
+- CORS handling
+- Request compression
+
+## Monitoring
+
+### Traefik Dashboard
+Access: http://localhost:8080
+
+Shows:
+- Active routers and services
+- Request metrics
+- Health checks
+- Middleware status
+
+### Logs
+```bash
+# View all logs
+docker-compose logs -f
+
+# View specific service logs
+docker-compose logs -f traefik
+docker-compose logs -f api-server
+docker-compose logs -f charging-engine
+```
+
+### Metrics
+Prometheus metrics available at: http://localhost:8080/metrics
+
+## Configuration
+
+### Environment Variables
+```bash
+# JWT Secret (required for production)
+export JWT_SECRET="your-32-character-secret-here"
+
+# Optional: Custom domain
+# Update traefik/dynamic/middlewares.yml and service labels
+```
+
+### Custom Domain
+1. Update service labels in `docker-compose.yml`
+2. Update middleware configuration in `traefik/dynamic/middlewares.yml`
+3. Update your DNS/hosts file
+
+### SSL Certificates
+For production, add certificates to `traefik/certs/` and update configuration:
+
+```yaml
+# traefik/traefik.yml
+entryPoints:
+  websecure:
+    address: ":443"
+    tls:
+      certificates:
+        - certFile: /traefik/certs/api.telecom.com.crt
+          keyFile: /traefik/certs/api.telecom.com.key
+```
+
+## Troubleshooting
+
+### Service Not Accessible
+1. Check if service is running: `docker-compose ps`
+2. Check service logs: `docker-compose logs [service-name]`
+3. Verify Traefik configuration: http://localhost:8080/dashboard/
+
+### Rate Limiting Issues
+1. Check middleware configuration in `traefik/dynamic/middlewares.yml`
+2. Monitor Traefik dashboard for rate limit status
+3. Adjust limits in configuration
+
+### Authentication Issues
+1. Verify JWT_SECRET is set: `echo $JWT_SECRET`
+2. Check JWT token format and expiration
+3. Review Traefik logs for authentication errors
+
+### Performance Issues
+1. Monitor Traefik dashboard for request metrics
+2. Check service health endpoints
+3. Review resource usage: `docker stats`
+
+## Migration from Direct Access
+
+If you were previously accessing services directly:
+
+### Before
+```bash
+# Direct access
+curl http://localhost:8000/api/v1/subscribers
+curl http://localhost:8081/v1/health
+```
+
+### After
+```bash
+# Through gateway
+curl https://api.telecom.com/api/v1/subscribers
+curl https://api.telecom.com/v1/health
+```
+
+### Update Client Applications
+1. Change base URLs from `http://localhost:PORT` to `https://api.telecom.com`
+2. Update authentication headers if needed
+3. Handle HTTPS certificate validation
+
+## Production Considerations
+
+1. **Set strong JWT_SECRET**: Use environment variable, not default
+2. **Use real SSL certificates**: Obtain from Let's Encrypt or your CA
+3. **Monitor resource usage**: Traefik adds minimal overhead
+4. **Backup configuration**: Save `traefik/` directory
+5. **Log rotation**: Configure Docker logging drivers
+6. **Health monitoring**: Set up alerts for service downtime
+
+## Support
+
+- Check logs: `docker-compose logs -f traefik`
+- View dashboard: http://localhost:8080
+- Review configuration: `traefik/traefik.yml` and `traefik/dynamic/`
+- Test endpoints: Use curl or Postman with proper headers