cmdb-insight/docs/GITEA-DOCKER-REGISTRY.md

# Gitea Docker Container Registry - Deployment Guide

Deze guide beschrijft hoe je Gitea gebruikt als Docker Container Registry voor het deployen van de Zuyderland CMDB GUI applicatie in productie.

## 📋 Inhoudsopgave

1. [Gitea Container Registry Setup](#gitea-container-registry-setup)
2. [Build & Push Images](#build--push-images)
3. [Docker Compose Configuration](#docker-compose-configuration)
4. [Deployment Workflow](#deployment-workflow)
5. [Automation Scripts](#automation-scripts)

---

## 🔧 Gitea Container Registry Setup

### 1. Enable Container Registry in Gitea

In je Gitea configuratie (`app.ini`), zorg dat de Container Registry enabled is:

```ini
[registry]
ENABLED = true
```

Of via de Gitea UI: **Settings** → **Application** → **Container Registry** → Enable

### 2. Registry URL Format

Gitea Container Registry gebruikt het volgende formaat:
```
<gitea-host>/<username>/<repository-name>
```

Bijvoorbeeld:
- Gitea URL: `https://git.zuyderland.nl`
- Repository: `icmt/cmdb-gui`
- Registry URL: `git.zuyderland.nl/icmt/cmdb-gui`

---

## 🐳 Build & Push Images

### 1. Login to Gitea Registry

```bash
# Login met Gitea credentials
docker login git.zuyderland.nl
# Username: <your-gitea-username>
# Password: <your-gitea-password> (of Personal Access Token)
```

### 2. Build Images

```bash
# Build backend image
docker build -t git.zuyderland.nl/icmt/cmdb-gui/backend:latest -f backend/Dockerfile.prod ./backend

# Build frontend image
docker build -t git.zuyderland.nl/icmt/cmdb-gui/frontend:latest -f frontend/Dockerfile.prod ./frontend
```

### 3. Push Images

```bash
# Push backend image
docker push git.zuyderland.nl/icmt/cmdb-gui/backend:latest

# Push frontend image
docker push git.zuyderland.nl/icmt/cmdb-gui/frontend:latest
```

### 4. Tagging for Versions

Voor versioned releases:

```bash
VERSION="1.0.0"

# Tag and push backend
docker tag git.zuyderland.nl/icmt/cmdb-gui/backend:latest \
  git.zuyderland.nl/icmt/cmdb-gui/backend:v${VERSION}
docker push git.zuyderland.nl/icmt/cmdb-gui/backend:v${VERSION}

# Tag and push frontend
docker tag git.zuyderland.nl/icmt/cmdb-gui/frontend:latest \
  git.zuyderland.nl/icmt/cmdb-gui/frontend:v${VERSION}
docker push git.zuyderland.nl/icmt/cmdb-gui/frontend:v${VERSION}
```

---

## 🚀 Docker Compose Configuration

### Production Docker Compose met Gitea Registry

Maak `docker-compose.prod.registry.yml`:

```yaml
version: '3.8'

services:
  backend:
    image: git.zuyderland.nl/icmt/cmdb-gui/backend:latest
    environment:
      - NODE_ENV=production
      - PORT=3001
    env_file:
      - .env.production
    volumes:
      - backend_data:/app/data
    restart: unless-stopped
    networks:
      - internal
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  frontend:
    image: git.zuyderland.nl/icmt/cmdb-gui/frontend:latest
    depends_on:
      - backend
    restart: unless-stopped
    networks:
      - internal
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
      - nginx_cache:/var/cache/nginx
    depends_on:
      - frontend
      - backend
    restart: unless-stopped
    networks:
      - internal

volumes:
  backend_data:
  nginx_cache:

networks:
  internal:
    driver: bridge
```

### Using Specific Versions

Voor productie deployments, gebruik specifieke versies in plaats van `latest`:

```yaml
backend:
  image: git.zuyderland.nl/icmt/cmdb-gui/backend:v1.0.0

frontend:
  image: git.zuyderland.nl/icmt/cmdb-gui/frontend:v1.0.0
```

---

## 📦 Deployment Workflow

### 1. Build & Push Script

Maak `scripts/build-and-push.sh`:

```bash
#!/bin/bash
set -e

# Configuration
GITEA_HOST="git.zuyderland.nl"
REPO_PATH="icmt/cmdb-gui"
VERSION="${1:-latest}"

echo "🔨 Building Docker images..."
echo "Registry: ${GITEA_HOST}/${REPO_PATH}"
echo "Version: ${VERSION}"

# Build backend
echo "📦 Building backend..."
docker build -t ${GITEA_HOST}/${REPO_PATH}/backend:${VERSION} \
  -f backend/Dockerfile.prod ./backend

# Build frontend
echo "📦 Building frontend..."
docker build -t ${GITEA_HOST}/${REPO_PATH}/frontend:${VERSION} \
  -f frontend/Dockerfile.prod ./frontend

# Push images
echo "📤 Pushing images to registry..."
docker push ${GITEA_HOST}/${REPO_PATH}/backend:${VERSION}
docker push ${GITEA_HOST}/${REPO_PATH}/frontend:${VERSION}

echo "✅ Build and push complete!"
echo ""
echo "To deploy, run:"
echo "  docker-compose -f docker-compose.prod.registry.yml pull"
echo "  docker-compose -f docker-compose.prod.registry.yml up -d"
```

### 2. Deployment Script

Maak `scripts/deploy.sh`:

```bash
#!/bin/bash
set -e

VERSION="${1:-latest}"
COMPOSE_FILE="docker-compose.prod.registry.yml"

echo "🚀 Deploying version: ${VERSION}"

# Update image tags in compose file (if using version tags)
if [ "$VERSION" != "latest" ]; then
  sed -i.bak "s|:latest|:v${VERSION}|g" ${COMPOSE_FILE}
fi

# Pull latest images
echo "📥 Pulling images..."
docker-compose -f ${COMPOSE_FILE} pull

# Deploy
echo "🚀 Starting services..."
docker-compose -f ${COMPOSE_FILE} up -d

# Cleanup old images (optional)
echo "🧹 Cleaning up..."
docker image prune -f

echo "✅ Deployment complete!"
echo ""
echo "Check status:"
echo "  docker-compose -f ${COMPOSE_FILE} ps"
echo ""
echo "View logs:"
echo "  docker-compose -f ${COMPOSE_FILE} logs -f"
```

### 3. CI/CD Integration (Gitea Actions)

Maak `.gitea/workflows/docker-build.yml`:

```yaml
name: Build and Push Docker Images

on:
  push:
    tags:
      - 'v*'
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Gitea Container Registry
        uses: docker/login-action@v2
        with:
          registry: git.zuyderland.nl
          username: ${{ secrets.GITEA_USERNAME }}
          password: ${{ secrets.GITEA_PASSWORD }}

      - name: Determine version
        id: version
        run: |
          if [[ ${{ github.ref }} == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/v}
          else
            VERSION=latest
          fi
          echo "version=${VERSION}" >> $GITHUB_OUTPUT

      - name: Build and push backend
        uses: docker/build-push-action@v4
        with:
          context: ./backend
          file: ./backend/Dockerfile.prod
          push: true
          tags: |
            git.zuyderland.nl/icmt/cmdb-gui/backend:${{ steps.version.outputs.version }}
            git.zuyderland.nl/icmt/cmdb-gui/backend:latest

      - name: Build and push frontend
        uses: docker/build-push-action@v4
        with:
          context: ./frontend
          file: ./frontend/Dockerfile.prod
          push: true
          tags: |
            git.zuyderland.nl/icmt/cmdb-gui/frontend:${{ steps.version.outputs.version }}
            git.zuyderland.nl/icmt/cmdb-gui/frontend:latest
```

---

## 🔐 Authentication

### Personal Access Token (Aanbevolen)

Voor CI/CD en automatisering, gebruik een Personal Access Token:

1. Gitea UI → **Settings** → **Applications** → **Generate New Token**
2. Scopes: `read:repository`, `write:repository`
3. Gebruik token als password bij `docker login`:

```bash
echo $GITEA_TOKEN | docker login git.zuyderland.nl -u <username> --password-stdin
```

### Environment Variables

Voor scripts, gebruik environment variables:

```bash
export GITEA_REGISTRY="git.zuyderland.nl"
export GITEA_USERNAME="your-username"
export GITEA_PASSWORD="your-token"
export REPO_PATH="icmt/cmdb-gui"
```

---

## 📝 Usage Examples

### Build and Push

```bash
# Build and push latest
./scripts/build-and-push.sh

# Build and push specific version
./scripts/build-and-push.sh 1.0.0
```

### Deploy

```bash
# Deploy latest
./scripts/deploy.sh

# Deploy specific version
./scripts/deploy.sh 1.0.0
```

### Manual Deployment

```bash
# Login
docker login git.zuyderland.nl

# Pull images
docker-compose -f docker-compose.prod.registry.yml pull

# Deploy
docker-compose -f docker-compose.prod.registry.yml up -d

# Check status
docker-compose -f docker-compose.prod.registry.yml ps

# View logs
docker-compose -f docker-compose.prod.registry.yml logs -f
```

---

## 🔍 Troubleshooting

### Authentication Issues

```bash
# Check login status
cat ~/.docker/config.json

# Re-login
docker logout git.zuyderland.nl
docker login git.zuyderland.nl
```

### Registry Not Found

- Controleer dat Container Registry enabled is in Gitea
- Verifieer de registry URL format: `<host>/<username>/<repo>`
- Check Gitea logs voor errors

### Image Pull Errors

```bash
# Check if image exists in registry (via Gitea UI)
# Verify network connectivity
curl -I https://git.zuyderland.nl

# Check Docker daemon logs
journalctl -u docker.service
```

---

## 🎯 Best Practices

1. **Use Version Tags**: Gebruik specifieke versies (`v1.0.0`) voor productie, `latest` voor development
2. **Security**: Gebruik Personal Access Tokens in plaats van passwords
3. **CI/CD**: Automatiseer build/push via Gitea Actions
4. **Image Scanning**: Overweeg image vulnerability scanning (Trivy, Clair)
5. **Registry Cleanup**: Regelmatig oude images verwijderen om ruimte te besparen

---

## 📚 Additional Resources

- [Gitea Container Registry Documentation](https://docs.gitea.io/en-us/usage/packages/container/)
- [Docker Registry Authentication](https://docs.docker.com/engine/reference/commandline/login/)
- [Docker Compose Production Guide](./PRODUCTION-DEPLOYMENT.md)