# MOTM App Kubernetes Deployment Guide

This guide provides step-by-step instructions for deploying the MOTM (Man of the Match) Hockey Voting Application to a Kubernetes cluster using Helm.

## Prerequisites

### Required Tools
- **Kubernetes Cluster** (version 1.19+)
- **Helm** (version 3.0+)
- **kubectl** (configured for your cluster)
- **Docker** (for building images)

### Required Services
- **PostgreSQL Database** (or MySQL/SQLite)
- **S3-compatible Storage** (optional, for asset management)

## Quick Start

### 1. Build and Push Docker Image

```bash
# Navigate to the application directory
cd /home/jonny/Projects/gcp-hockey-results/motm_app

# Build the Docker image
docker build -t your-registry/motm-app:latest .

# Push to your container registry
docker push your-registry/motm-app:latest
```

### 2. Deploy to Development

```bash
# Navigate to the helm chart directory
cd helm-chart/motm-app

# Update the image repository in values-development.yaml
sed -i 's/your-registry\/motm-app/your-actual-registry\/motm-app/g' values-development.yaml

# Deploy using the deployment script
./scripts/deploy.sh development install
```

### 3. Deploy to Production

```bash
# Update production values
cp values-production.yaml my-production-values.yaml
# Edit my-production-values.yaml with your production settings

# Deploy to production
./scripts/deploy.sh production install
```

## Manual Deployment

### 1. Customize Values

Edit the appropriate values file:

```bash
# For development
vim values-development.yaml

# For production
vim values-production.yaml
```

Key values to update:
- `image.repository`: Your container registry
- `database.host`: Database service name
- `ingress.hosts[0].host`: Your domain name
- `secrets.*`: Database and S3 credentials

### 2. Install with Helm

```bash
# Development
helm install motm-app ./motm-app \
  --namespace motm-app \
  --values values-development.yaml \
  --create-namespace

# Production
helm install motm-app ./motm-app \
  --namespace motm-app \
  --values values-production.yaml \
  --create-namespace
```

## Configuration

### Database Setup

The application supports multiple database types:

#### PostgreSQL (Recommended)
```yaml
database:
  type: "postgresql"
  host: "postgresql-service"
  port: 5432
  name: "motm"
  username: "motm_user"
```

#### MySQL
```yaml
database:
  type: "mysql"
  host: "mysql-service"
  port: 3306
  name: "motm"
  username: "motm_user"
```

#### SQLite (Development only)
```yaml
database:
  type: "sqlite"
  # Other fields ignored for SQLite
```

### S3 Configuration

For asset management (logos, images):

```yaml
s3:
  enabled: true
  endpoint: "https://s3.amazonaws.com"
  region: "us-east-1"
  bucket: "motm-assets"
  # Credentials set via secrets
```

### Security Configuration

#### Secrets Management

Set secrets via Helm values or external secret management:

```yaml
secrets:
  dbPassword: "your-database-password"
  s3AccessKey: "your-s3-access-key"
  s3SecretKey: "your-s3-secret-key"
```

Or use external secret management:
```bash
# Create secrets manually
kubectl create secret generic motm-app-secrets \
  --from-literal=db-password=your-password \
  --from-literal=s3-access-key=your-key \
  --from-literal=s3-secret-key=your-secret \
  --namespace motm-app
```

#### Network Policies

For enhanced security, create network policies:

```yaml
# network-policy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: motm-app-netpol
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: motm-app
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
  egress:
  - to:
    - namespaceSelector:
        matchLabels:
          name: postgresql
```

## Monitoring and Observability

### Health Checks

The application includes built-in health checks:
- **Liveness Probe**: Checks if the application is running
- **Readiness Probe**: Checks if the application is ready to serve traffic

### Logging

Configure log levels in values:

```yaml
logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR
  format: "json" # json, text
```

### Metrics (Optional)

Add Prometheus metrics endpoint:

```yaml
monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s
```

## Scaling

### Horizontal Pod Autoscaling

Enable HPA for production:

```yaml
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80
```

### Resource Limits

Adjust based on your cluster capacity:

```yaml
resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 200m
    memory: 512Mi
```

## Troubleshooting

### Common Issues

#### 1. Pod Not Starting
```bash
# Check pod status
kubectl get pods -n motm-app -l app.kubernetes.io/name=motm-app

# Check pod logs
kubectl logs -n motm-app -l app.kubernetes.io/name=motm-app
```

#### 2. Database Connection Issues
```bash
# Test database connectivity
kubectl exec -n motm-app -it deployment/motm-app -- python -c "
from database import sql_read_static
from sqlalchemy import text
try:
    result = sql_read_static(text('SELECT 1'))
    print('Database connection successful')
except Exception as e:
    print(f'Database connection failed: {e}')
"
```

#### 3. S3 Connection Issues
```bash
# Check S3 configuration
kubectl exec -n motm-app -it deployment/motm-app -- cat /app/s3_config.json
```

#### 4. Ingress Issues
```bash
# Check ingress status
kubectl get ingress -n motm-app

# Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
```

### Debugging Commands

```bash
# Get all resources
kubectl get all -n motm-app

# Describe deployment
kubectl describe deployment -n motm-app motm-app

# Check events
kubectl get events -n motm-app --sort-by='.lastTimestamp'

# Port forward for local testing
kubectl port-forward -n motm-app svc/motm-app 8080:80
```

## Maintenance

### Updates

```bash
# Update application
helm upgrade motm-app ./motm-app \
  --namespace motm-app \
  --values values-production.yaml

# Rollback if needed
helm rollback motm-app 1 --namespace motm-app
```

### Backup

```bash
# Backup database (PostgreSQL)
kubectl exec -n postgresql postgresql-0 -- pg_dump -U motm_user motm > backup.sql

# Backup application data
kubectl exec -n motm-app deployment/motm-app -- tar -czf /tmp/data-backup.tar.gz /app/data
kubectl cp motm-app/deployment/motm-app:/tmp/data-backup.tar.gz ./data-backup.tar.gz
```

### Cleanup

```bash
# Uninstall application
helm uninstall motm-app --namespace motm-app

# Delete namespace (if no other resources)
kubectl delete namespace motm-app
```

## Security Best Practices

1. **Use Non-Root Containers**: The application runs as non-root user (UID 1000)
2. **Read-Only Root Filesystem**: Enable in production values
3. **Network Policies**: Implement to restrict pod-to-pod communication
4. **RBAC**: Use dedicated service accounts with minimal permissions
5. **Secret Management**: Use external secret management solutions
6. **Image Security**: Scan images for vulnerabilities
7. **TLS**: Enable TLS for all ingress traffic
8. **Resource Limits**: Set appropriate CPU and memory limits

## Support

For issues and questions:
1. Check the application logs
2. Review Kubernetes events
3. Consult the Helm chart documentation
4. Create an issue in the repository