PFEE/dashboard-sqdc/DEPLOYMENT.md

# SQDC Dashboard - Deployment Guide

## Table of Contents
- [Quick Start with Registry](#quick-start-with-registry)
- [Docker Deployment](#docker-deployment)
- [Kubernetes Deployment](#kubernetes-deployment)
- [Gitea CI/CD Setup](#gitea-cicd-setup)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

---

## Quick Start with Registry

For a step-by-step guide to set up the container registry and CI/CD pipeline, see [SETUP-REGISTRY.md](SETUP-REGISTRY.md).

**Quick Summary:**
- Registry: `gitea.vidoks.fr`
- Image: `gitea.vidoks.fr/sortifal/pfee:latest`
- Required Secrets: `KUBE_CONFIG`, `REGISTRY_URL`, `REGISTRY_USER`, `REGISTRY_PASSWORD`

---

## Docker Deployment

### Local Development with Docker Compose

1. **Build and run the application:**
   ```bash
   docker-compose up -d
   ```

2. **Access the application:**
   - Frontend: http://localhost:8080
   - API: http://localhost:3001

3. **View logs:**
   ```bash
   docker-compose logs -f
   ```

4. **Stop the application:**
   ```bash
   docker-compose down
   ```

### Manual Docker Build

1. **Build the image:**
   ```bash
   docker build -t sqdc-dashboard:latest .
   ```

2. **Run the container:**
   ```bash
   docker run -d \
     --name sqdc-dashboard \
     -p 8080:80 \
     -p 3001:3001 \
     -v $(pwd)/database:/app/database \
     sqdc-dashboard:latest
   ```

3. **Check container status:**
   ```bash
   docker ps
   docker logs sqdc-dashboard
   ```

---

## Kubernetes Deployment

### Prerequisites

- Kubernetes cluster (v1.20+)
- kubectl configured
- Nginx Ingress Controller installed
- (Optional) Cert-Manager for HTTPS

### Quick Deployment

1. **Create registry credentials secret:**
   ```bash
   kubectl create secret docker-registry registry-credentials \
     --docker-server=gitea.vidoks.fr \
     --docker-username=<your-username> \
     --docker-password=<your-password> \
     -n sqdc-dashboard
   ```

2. **Using the deployment script:**
   ```bash
   ./scripts/deploy.sh gitea.vidoks.fr <registry-user> <registry-password> sortifal/pfee
   ```

3. **Manual deployment:**
   ```bash
   # Apply all manifests
   kubectl apply -f k8s/

   # Or use kustomize
   kubectl apply -k k8s/
   ```

3. **Verify deployment:**
   ```bash
   kubectl get all -n sqdc-dashboard
   ```

### Detailed Steps

#### 1. Create Namespace
```bash
kubectl apply -f k8s/namespace.yaml
```

#### 2. Deploy Application
```bash
kubectl apply -f k8s/deployment.yaml
```

#### 3. Create Service
```bash
kubectl apply -f k8s/service.yaml
```

#### 4. Setup Ingress
```bash
kubectl apply -f k8s/ingress.yaml
```

#### 5. Verify Deployment
```bash
# Check pods
kubectl get pods -n sqdc-dashboard

# Check service
kubectl get svc -n sqdc-dashboard

# Check ingress
kubectl get ingress -n sqdc-dashboard

# View logs
kubectl logs -f deployment/sqdc-dashboard -n sqdc-dashboard
```

### Scaling

```bash
# Scale to 3 replicas
kubectl scale deployment/sqdc-dashboard --replicas=3 -n sqdc-dashboard

# Auto-scaling (optional)
kubectl autoscale deployment/sqdc-dashboard \
  --cpu-percent=70 \
  --min=2 \
  --max=10 \
  -n sqdc-dashboard
```

### Rollback

```bash
# Using the rollback script
./scripts/rollback.sh

# Or manually
kubectl rollout undo deployment/sqdc-dashboard -n sqdc-dashboard
kubectl rollout status deployment/sqdc-dashboard -n sqdc-dashboard
```

---

## Gitea CI/CD Setup

### 1. Configure Gitea Actions

Ensure Gitea Actions is enabled in your Gitea instance:
- Go to Site Administration → Configuration
- Enable Actions Runner

### 2. Set up Secrets

In your Gitea repository, add the following secrets:

**Settings → Secrets → Actions**

- `KUBE_CONFIG`: Plain text kubeconfig file for k3s
  ```bash
  cat ~/.kube/config
  ```

- `REGISTRY_URL`: Container registry URL (e.g., `gitea.vidoks.fr`)

- `REGISTRY_USER`: Registry username

- `REGISTRY_PASSWORD`: Registry password or access token

### 3. Configure Workflow

The workflow file is already created at `.gitea/workflows/build-deploy.yml`

**Workflow triggers:**
- Push to any branch
- Pull requests to any branch

**Workflow steps:**
1. Build - Runs tests, builds Docker image, and pushes to container registry
2. Deploy - Pulls image from registry and deploys to Kubernetes (on any push)
3. Notify - Sends deployment status

### 4. First Deployment

```bash
# Commit and push
git add .
git commit -m "Initial deployment setup"
git push origin main
```

The workflow will automatically:
- Install dependencies
- Run tests
- Build the application
- Create Docker image
- Push image to container registry (gitea.vidoks.fr)
- Pull image from registry and deploy to Kubernetes cluster

### 5. Monitor Workflow

- Go to your Gitea repository
- Click on "Actions" tab
- View workflow runs and logs

---

## Configuration

### Environment Variables

**Docker Compose:**
Edit `docker-compose.yml`:
```yaml
environment:
  - NODE_ENV=production
  - API_PORT=3001
```

**Kubernetes:**
Edit `k8s/configmap.yaml`:
```yaml
data:
  NODE_ENV: "production"
  API_PORT: "3001"
```

### Ingress Hostname

Edit `k8s/ingress.yaml` to change the hostname:
```yaml
spec:
  rules:
  - host: your-domain.com  # Change this
```

Update `/etc/hosts` for local testing:
```bash
echo "127.0.0.1 sqdc-dashboard.local" | sudo tee -a /etc/hosts
```

### Resource Limits

Edit `k8s/deployment.yaml` to adjust resources:
```yaml
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"
```

### Storage

Adjust persistent volume size in `k8s/deployment.yaml`:
```yaml
resources:
  requests:
    storage: 1Gi  # Change this
```

---

## Troubleshooting

### Container Issues

**Container won't start:**
```bash
docker logs sqdc-dashboard
docker inspect sqdc-dashboard
```

**Port already in use:**
```bash
# Find process using port
lsof -i :8080
# Kill process
kill -9 <PID>
```

### Kubernetes Issues

**Pods not running:**
```bash
kubectl describe pod <pod-name> -n sqdc-dashboard
kubectl logs <pod-name> -n sqdc-dashboard
```

**Image pull errors:**
```bash
# Check if image exists
docker images | grep sqdc-dashboard

# Load image into cluster (minikube)
minikube image load sqdc-dashboard:latest

# Or use kind
kind load docker-image sqdc-dashboard:latest
```

**Service not accessible:**
```bash
# Check service endpoints
kubectl get endpoints -n sqdc-dashboard

# Port-forward for testing
kubectl port-forward svc/sqdc-dashboard-service 8080:80 -n sqdc-dashboard
```

**Ingress not working:**
```bash
# Check ingress controller
kubectl get pods -n ingress-nginx

# Check ingress resource
kubectl describe ingress sqdc-dashboard-ingress -n sqdc-dashboard

# Verify nginx ingress controller is installed
kubectl get ingressclass
```

### Gitea Workflow Issues

**Workflow not triggering:**
- Check if Actions is enabled
- Verify branch names match trigger conditions
- Check workflow file syntax

**Deployment fails:**
- Verify KUBECONFIG secret is correctly set
- Check kubectl has access to cluster
- Review workflow logs in Gitea Actions tab

**Test failures:**
```bash
# Run tests locally
npm test

# Skip tests (not recommended)
# Modify workflow to add: -- --passWithNoTests
```

---

## Monitoring

### View Application Logs

**Docker:**
```bash
docker logs -f sqdc-dashboard
```

**Kubernetes:**
```bash
kubectl logs -f deployment/sqdc-dashboard -n sqdc-dashboard
```

### Check Health Status

**Docker:**
```bash
curl http://localhost:8080
curl http://localhost:3001/categories
```

**Kubernetes:**
```bash
kubectl get pods -n sqdc-dashboard
kubectl exec -it <pod-name> -n sqdc-dashboard -- wget -O- http://localhost/
```

---

## Backup and Restore

### Backup Database

**Docker:**
```bash
docker cp sqdc-dashboard:/app/database/sqdc.db ./backup-$(date +%Y%m%d).db
```

**Kubernetes:**
```bash
kubectl cp sqdc-dashboard/<pod-name>:/app/database/sqdc.db \
  ./backup-$(date +%Y%m%d).db \
  -n sqdc-dashboard
```

### Restore Database

**Docker:**
```bash
docker cp ./backup.db sqdc-dashboard:/app/database/sqdc.db
docker restart sqdc-dashboard
```

**Kubernetes:**
```bash
kubectl cp ./backup.db sqdc-dashboard/<pod-name>:/app/database/sqdc.db \
  -n sqdc-dashboard
kubectl rollout restart deployment/sqdc-dashboard -n sqdc-dashboard
```

---

## Additional Resources

- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [Docker Documentation](https://docs.docker.com/)
- [Gitea Actions](https://docs.gitea.io/en-us/actions/)
- [Nginx Ingress Controller](https://kubernetes.github.io/ingress-nginx/)