PFEE/dashboard-sqdc/DEPLOYMENT.md

SQDC Dashboard - Deployment Guide

Table of Contents

• Quick Start with Registry
• Docker Deployment
• Kubernetes Deployment
• Gitea CI/CD Setup
• Configuration
• 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.

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:

   docker-compose up -d
   

2. Access the application:

   • Frontend: http://localhost:8080
   • API: http://localhost:3001

3. View logs:

   docker-compose logs -f
   

4. Stop the application:

   docker-compose down
   

Manual Docker Build

1. Build the image:

   docker build -t sqdc-dashboard:latest .
   

2. Run the container:

   docker run -d \
     --name sqdc-dashboard \
     -p 8080:80 \
     -p 3001:3001 \
     -v $(pwd)/database:/app/database \
     sqdc-dashboard:latest
   

3. Check container status:

   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:

   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:

   ./scripts/deploy.sh gitea.vidoks.fr <registry-user> <registry-password> sortifal/pfee
   

3. Manual deployment:

   # Apply all manifests
   kubectl apply -f k8s/
   
   # Or use kustomize
   kubectl apply -k k8s/
   

4. Verify deployment:

   kubectl get all -n sqdc-dashboard
   

Detailed Steps

1. Create Namespace

kubectl apply -f k8s/namespace.yaml

2. Deploy Application

kubectl apply -f k8s/deployment.yaml

3. Create Service

kubectl apply -f k8s/service.yaml

4. Setup Ingress

kubectl apply -f k8s/ingress.yaml

5. Verify Deployment

# 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

# 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

# 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

  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 main or dashboard branch
• Pull requests to main or dashboard 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 (only on main/dashboard branch)
3. Notify - Sends deployment status

4. First Deployment

# 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:

environment:
  - NODE_ENV=production
  - API_PORT=3001

Kubernetes: Edit k8s/configmap.yaml:

data:
  NODE_ENV: "production"
  API_PORT: "3001"

Ingress Hostname

Edit k8s/ingress.yaml to change the hostname:

spec:
  rules:
  - host: your-domain.com  # Change this

Update /etc/hosts for local testing:

echo "127.0.0.1 sqdc-dashboard.local" | sudo tee -a /etc/hosts

Resource Limits

Edit k8s/deployment.yaml to adjust resources:

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

Storage

Adjust persistent volume size in k8s/deployment.yaml:

resources:
  requests:
    storage: 1Gi  # Change this

---

Troubleshooting

Container Issues

Container won't start:

docker logs sqdc-dashboard
docker inspect sqdc-dashboard

Port already in use:

# Find process using port
lsof -i :8080
# Kill process
kill -9 <PID>

Kubernetes Issues

Pods not running:

kubectl describe pod <pod-name> -n sqdc-dashboard
kubectl logs <pod-name> -n sqdc-dashboard

Image pull errors:

# 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:

# 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:

# 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:

# Run tests locally
npm test

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

---

Monitoring

View Application Logs

Docker:

docker logs -f sqdc-dashboard

Kubernetes:

kubectl logs -f deployment/sqdc-dashboard -n sqdc-dashboard

Check Health Status

Docker:

curl http://localhost:8080
curl http://localhost:3001/categories

Kubernetes:

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

---

Backup and Restore

Backup Database

Docker:

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

Kubernetes:

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

Restore Database

Docker:

docker cp ./backup.db sqdc-dashboard:/app/database/sqdc.db
docker restart sqdc-dashboard

Kubernetes:

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
• Docker Documentation
• Gitea Actions
• Nginx Ingress Controller