CalejoControl/QUICKSTART.md

# Calejo Control Adapter - Quick Start Guide

## 🚀 5-Minute Setup with Docker

### Prerequisites
- Docker and Docker Compose installed
- At least 4GB RAM available

### Step 1: Get the Code
```bash
git clone <repository-url>
cd calejo-control-adapter
```

### Step 2: Start Everything
```bash
docker-compose up -d
```

### Step 3: Verify Installation
```bash
# Check if services are running
docker-compose ps

# Test the API
curl http://localhost:8080/health
```

### Step 4: Access the Interfaces
- **REST API**: http://localhost:8080
- **API Documentation**: http://localhost:8080/docs
- **Grafana Dashboard**: http://localhost:3000 (admin/admin)
- **Prometheus Metrics**: http://localhost:9091

## 🔧 Basic Configuration

### Environment Variables
Create a `.env` file:
```bash
# Copy the example
cp .env.example .env

# Edit with your settings
nano .env
```

Key settings to change:
```env
JWT_SECRET_KEY=your-very-secure-secret-key
API_KEY=your-api-access-key
DATABASE_URL=postgresql://calejo:password@postgres:5432/calejo
```

## 📊 Monitoring Your System

### Health Checks
```bash
# Basic health
curl http://localhost:8080/health

# Detailed health
curl http://localhost:8080/api/v1/health/detailed

# Prometheus metrics
curl http://localhost:8080/metrics
```

### Key Metrics to Watch
- Application uptime
- Database connection count
- Active protocol connections
- Safety violations
- API request rate

## 🔒 Security First Steps

1. **Change Default Passwords**
   - Update PostgreSQL password in `.env`
   - Change Grafana admin password
   - Rotate API keys and JWT secret

2. **Network Security**
   - Restrict access to management ports
   - Use VPN for remote access
   - Enable TLS/SSL for APIs

## 🛠️ Common Operations

### Restart Services
```bash
docker-compose restart
```

### View Logs
```bash
# All services
docker-compose logs

# Specific service
docker-compose logs calejo-control-adapter
```

### Stop Everything
```bash
docker-compose down
```

### Update to Latest Version
```bash
docker-compose down
git pull
docker-compose build --no-cache
docker-compose up -d
```

## 🆘 Troubleshooting

### Service Won't Start
- Check if ports are available: `netstat -tulpn | grep <port>`
- Verify Docker is running: `docker info`
- Check logs: `docker-compose logs`

### Database Connection Issues
- Ensure PostgreSQL container is running
- Check connection string in `.env`
- Verify database initialization completed

### Performance Issues
- Monitor system resources: `docker stats`
- Check application logs for errors
- Verify database performance

## 📞 Getting Help

- **Documentation**: See `DEPLOYMENT.md` for detailed instructions
- **Issues**: Check the GitHub issue tracker
- **Support**: Email support@calejo-control.com

## 🎯 Next Steps

1. **Configure Pump Stations** - Add your actual pump station data
2. **Set Up Alerts** - Configure monitoring alerts in Grafana
3. **Integrate with SCADA** - Connect to your existing control systems
4. **Security Hardening** - Implement production security measures

---

**Need more help?** Check the full documentation in `DEPLOYMENT.md` or contact our support team.