file/lbl-01/DEPLOYMENT.md

# Label Studio Helm Chart Deployment Guide

This guide provides step-by-step instructions for deploying Label Studio using the Helm chart.

## Prerequisites

Before deploying Label Studio, ensure you have:

1. **Kubernetes cluster** (v1.19+)
2. **Helm** (v3.0+)
3. **kubectl** configured to access your cluster
4. **PostgreSQL database** (can be deployed separately or use managed service)
5. **Redis instance** (can be deployed separately or use managed service)
6. **Storage class** available in your cluster

## Quick Start

### 1. Clone or Download the Chart

```bash
# If you have the chart locally
cd /path/to/helm-chart/lbl-01

# Or download from repository
helm repo add label-studio https://your-repo-url
helm repo update
```

### 2. Create Namespace

```bash
kubectl create namespace label-studio
```

### 3. Deploy Dependencies

#### PostgreSQL (using Bitnami chart)

```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install postgresql bitnami/postgresql \
  --namespace label-studio \
  --set auth.postgresPassword=labelstudio123 \
  --set auth.username=labelstudio \
  --set auth.password=labelstudio123 \
  --set auth.database=labelstudio \
  --set primary.persistence.enabled=true \
  --set primary.persistence.size=20Gi
```

#### Redis (using Bitnami chart)

```bash
helm install redis bitnami/redis \
  --namespace label-studio \
  --set auth.password=redis123 \
  --set master.persistence.enabled=true \
  --set master.persistence.size=8Gi
```

### 4. Create Secrets

```bash
# PostgreSQL secret
kubectl create secret generic postgresql-secret \
  --from-literal=password=labelstudio123 \
  --namespace label-studio

# Redis secret
kubectl create secret generic redis-secret \
  --from-literal=password=redis123 \
  --namespace label-studio
```

### 5. Customize Values

Copy the example values file and customize it:

```bash
cp values-example.yaml my-values.yaml
```

Edit `my-values.yaml` to match your environment:

```yaml
# Update these values according to your setup
global:
  pgConfig:
    host: "postgresql.label-studio.svc.cluster.local"
    password:
      secretName: "postgresql-secret"
      secretKey: "password"
  
  redisConfig:
    host: "redis://redis-master.label-studio.svc.cluster.local:6379/1"
    password:
      secretName: "redis-secret"
      secretKey: "password"

ingress:
  enabled: true
  hosts:
    - host: label-studio.yourdomain.com  # Change this
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: label-studio-tls
      hosts:
        - label-studio.yourdomain.com  # Change this

env:
  LABEL_STUDIO_HOST: "https://label-studio.yourdomain.com"  # Change this
  LABEL_STUDIO_USERNAME: "admin@yourdomain.com"  # Change this
  LABEL_STUDIO_PASSWORD: "your-secure-password"  # Change this
```

### 6. Deploy Label Studio

```bash
helm install label-studio . \
  --namespace label-studio \
  --values my-values.yaml
```

### 7. Verify Deployment

```bash
# Check pods
kubectl get pods -n label-studio

# Check services
kubectl get svc -n label-studio

# Check ingress
kubectl get ingress -n label-studio

# View logs
kubectl logs -f deployment/label-studio -n label-studio
```

## Advanced Deployment Scenarios

### Production Deployment with External Database

For production environments, use managed database services:

```yaml
global:
  pgConfig:
    host: "your-rds-endpoint.amazonaws.com"
    port: 5432
    dbName: "labelstudio"
    userName: "labelstudio"
    password:
      secretName: "external-db-secret"
      secretKey: "password"
  
  redisConfig:
    host: "redis://your-elasticache-endpoint:6379/1"
    password:
      secretName: "external-redis-secret"
      secretKey: "password"

resources:
  limits:
    cpu: 4000m
    memory: 8Gi
  requests:
    cpu: 2000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70
```

### High Availability Setup

```yaml
replicaCount: 3

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values:
            - label-studio
        topologyKey: kubernetes.io/hostname

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 1000m
    memory: 2Gi
```

### Storage Configuration

#### S3 Storage

```yaml
global:
  persistence:
    enabled: true
    type: s3
    config:
      s3:
        bucket: "your-s3-bucket"
        region: "us-west-2"
        accessKey:
          secretName: "s3-credentials"
          secretKey: "access-key"
        secretKey:
          secretName: "s3-credentials"
          secretKey: "secret-key"

env:
  USE_S3: "true"
  S3_BUCKET: "your-s3-bucket"
  S3_REGION: "us-west-2"
```

#### Azure Blob Storage

```yaml
global:
  persistence:
    enabled: true
    type: azure
    config:
      azure:
        accountName: "yourstorageaccount"
        containerName: "labelstudio"
        accountKey:
          secretName: "azure-storage-secret"
          secretKey: "account-key"

env:
  USE_AZURE: "true"
  AZURE_ACCOUNT_NAME: "yourstorageaccount"
  AZURE_CONTAINER: "labelstudio"
```

## Monitoring and Observability

### Enable Prometheus Metrics

```yaml
env:
  PROMETHEUS_METRICS_ENABLED: "true"
  PROMETHEUS_METRICS_PORT: "9090"

service:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    prometheus.io/path: "/metrics"
```

### Logging Configuration

```yaml
env:
  LOG_LEVEL: "INFO"
  LOG_FORMAT: "json"
  PYTHONUNBUFFERED: "1"
```

## Troubleshooting

### Common Issues

1. **Pod not starting**
   ```bash
   kubectl describe pod <pod-name> -n label-studio
   kubectl logs <pod-name> -n label-studio
   ```

2. **Database connection issues**
   ```bash
   # Test database connectivity
   kubectl run -it --rm debug --image=postgres:13 --restart=Never -- psql -h postgresql.label-studio.svc.cluster.local -U labelstudio -d labelstudio
   ```

3. **Redis connection issues**
   ```bash
   # Test Redis connectivity
   kubectl run -it --rm debug --image=redis:6 --restart=Never -- redis-cli -h redis-master.label-studio.svc.cluster.local -a redis123
   ```

4. **Ingress not working**
   ```bash
   kubectl describe ingress label-studio -n label-studio
   kubectl get events -n label-studio
   ```

### Health Checks

```bash
# Check application health
kubectl exec -it deployment/label-studio -n label-studio -- curl http://localhost:8080/health

# Run Helm tests
helm test label-studio -n label-studio
```

## Upgrading

### Upgrade the Chart

```bash
# Update values if needed
helm upgrade label-studio . \
  --namespace label-studio \
  --values my-values.yaml

# Check upgrade status
helm status label-studio -n label-studio
```

### Rollback

```bash
# List releases
helm history label-studio -n label-studio

# Rollback to previous version
helm rollback label-studio 1 -n label-studio
```

## Uninstalling

```bash
# Uninstall Label Studio
helm uninstall label-studio -n label-studio

# Uninstall dependencies (if installed via Helm)
helm uninstall postgresql -n label-studio
helm uninstall redis -n label-studio

# Delete namespace
kubectl delete namespace label-studio
```

## Security Considerations

1. **Use strong passwords** for database and Redis
2. **Enable TLS** for ingress
3. **Use secrets** for sensitive data
4. **Configure RBAC** appropriately
5. **Enable pod security policies**
6. **Use non-root containers**
7. **Scan images** for vulnerabilities

## Performance Tuning

### Resource Optimization

```yaml
resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 1000m
    memory: 2Gi

# For high-traffic environments
autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 50
  targetCPUUtilizationPercentage: 60
  targetMemoryUtilizationPercentage: 70
```

### Database Optimization

```yaml
env:
  DJANGO_DB_CONN_MAX_AGE: "600"
  DJANGO_DB_OPTIONS: '{"MAX_CONNS": 20}'
```

## Support

For issues and questions:
- Check the [Label Studio documentation](https://labelstud.io/guide/)
- Review the [GitHub issues](https://github.com/heartexlabs/label-studio)
- Join the [Label Studio community](https://slack.labelstud.io/)

## Contributing

To contribute to this Helm chart:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request