# Azure Container Registry - Docker Images Build & Push Guide

Deze guide beschrijft hoe je Docker images bouwt en naar Azure Container Registry (ACR) pusht voor de Zuyderland CMDB GUI applicatie.

## 📋 Inhoudsopgave

1. [Azure Container Registry Setup](#azure-container-registry-setup)
2. [Lokale Build & Push](#lokale-build--push)
3. [Azure DevOps Pipeline](#azure-devops-pipeline)
4. [Docker Compose Configuration](#docker-compose-configuration)
5. [Best Practices](#best-practices)

---

## 🔧 Azure Container Registry Setup

### 1. Azure Container Registry Aanmaken

Als je nog geen ACR hebt, maak er een aan via Azure Portal of Azure CLI:

```bash
# Resource group (als nog niet bestaat)
az group create --name rg-cmdb-gui --location westeurope

# Azure Container Registry aanmaken
az acr create \
  --resource-group rg-cmdb-gui \
  --name zuyderlandcmdbacr \
  --sku Basic \
  --admin-enabled true
```

**ACR SKU Opties:**
- **Basic**: Geschikt voor development/test (~€5/maand)
- **Standard**: Voor productie met geo-replicatie (~€20/maand)
- **Premium**: Voor enterprise met security features (~€50/maand)

### 2. Registry URL

Na aanmaken is je registry beschikbaar op:
```
<acr-name>.azurecr.io
```

Bijvoorbeeld: `zuyderlandcmdbacr.azurecr.io`

### 3. Authentication

ACR ondersteunt meerdere authenticatiemethoden:

**A) Admin Credentials (Eenvoudig, voor development)**
```bash
# Admin credentials ophalen
az acr credential show --name zuyderlandcmdbacr

# Login met Docker
az acr login --name zuyderlandcmdbacr
# OF
docker login zuyderlandcmdbacr.azurecr.io -u <admin-username> -p <admin-password>
```

**B) Azure Service Principal (Aanbevolen voor CI/CD)**
```bash
# Service Principal aanmaken
az ad sp create-for-rbac --name "zuyderland-cmdb-acr-sp" --role acrpull --scopes /subscriptions/<subscription-id>/resourceGroups/rg-cmdb-gui/providers/Microsoft.ContainerRegistry/registries/zuyderlandcmdbacr

# Gebruik de output credentials in CI/CD
```

**C) Managed Identity (Best voor Azure services)**
- Gebruik Managed Identity voor Azure DevOps, App Service, etc.
- Configureer via Azure Portal → ACR → Access Control (IAM)

---

## 🐳 Lokale Build & Push

### Optie 1: Met Script (Aanbevolen)

Gebruik het `build-and-push-azure.sh` script:

```bash
# Maak script uitvoerbaar
chmod +x scripts/build-and-push-azure.sh

# Build en push (gebruikt 'latest' als versie)
./scripts/build-and-push-azure.sh

# Build en push met specifieke versie
./scripts/build-and-push-azure.sh 1.0.0
```

**Environment Variables:**
```bash
export ACR_NAME="zuyderlandcmdbacr"
export REPO_NAME="zuyderland-cmdb-gui"
./scripts/build-and-push-azure.sh 1.0.0
```

### Optie 2: Handmatig met Docker Commands

```bash
# Login
az acr login --name zuyderlandcmdbacr

# Set variabelen
ACR_NAME="zuyderlandcmdbacr"
REGISTRY="${ACR_NAME}.azurecr.io"
REPO_NAME="zuyderland-cmdb-gui"
VERSION="1.0.0"

# Build backend
docker build -t ${REGISTRY}/${REPO_NAME}/backend:${VERSION} \
  -t ${REGISTRY}/${REPO_NAME}/backend:latest \
  -f backend/Dockerfile.prod ./backend

# Build frontend
docker build -t ${REGISTRY}/${REPO_NAME}/frontend:${VERSION} \
  -t ${REGISTRY}/${REPO_NAME}/frontend:latest \
  -f frontend/Dockerfile.prod ./frontend

# Push images
docker push ${REGISTRY}/${REPO_NAME}/backend:${VERSION}
docker push ${REGISTRY}/${REPO_NAME}/backend:latest
docker push ${REGISTRY}/${REPO_NAME}/frontend:${VERSION}
docker push ${REGISTRY}/${REPO_NAME}/frontend:latest
```

---

## 🚀 Azure DevOps Pipeline

### 1. Service Connection Aanmaken

In Azure DevOps:

1. **Project Settings** → **Service connections** → **New service connection**
2. Kies **Docker Registry**
3. Kies **Azure Container Registry**
4. Selecteer je Azure subscription en ACR
5. Geef een naam: `zuyderland-cmdb-acr-connection`

### 2. Pipeline Configuratie

Het project bevat al een `azure-pipelines.yml` bestand. Configureer deze in Azure DevOps:

1. **Pipelines** → **New pipeline**
2. Kies je repository (Azure Repos)
3. Kies **Existing Azure Pipelines YAML file**
4. Selecteer `azure-pipelines.yml`
5. Review en run

### 3. Pipeline Variabelen Aanpassen

Pas de variabelen in `azure-pipelines.yml` aan naar jouw instellingen:

```yaml
variables:
  acrName: 'zuyderlandcmdbacr'  # Jouw ACR naam
  repositoryName: 'zuyderland-cmdb-gui'
  dockerRegistryServiceConnection: 'zuyderland-cmdb-acr-connection'
```

### 4. Automatische Triggers

De pipeline triggert automatisch bij:
- Push naar `main` branch
- Tags die beginnen met `v*` (bijv. `v1.0.0`)

**Handmatig Triggeren:**
```bash
# Tag aanmaken en pushen
git tag v1.0.0
git push origin v1.0.0
```

---

## 📦 Docker Compose Configuration

### Productie Docker Compose met ACR

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

```yaml
version: '3.8'

services:
  backend:
    image: zuyderlandcmdbacr.azurecr.io/zuyderland-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: zuyderlandcmdbacr.azurecr.io/zuyderland-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
```

### Gebruik Specifieke Versies

Voor productie deployments, gebruik specifieke versies:

```yaml
backend:
  image: zuyderlandcmdbacr.azurecr.io/zuyderland-cmdb-gui/backend:v1.0.0

frontend:
  image: zuyderlandcmdbacr.azurecr.io/zuyderland-cmdb-gui/frontend:v1.0.0
```

### Pull en Deploy

```bash
# Login (als nodig)
az acr login --name zuyderlandcmdbacr

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

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

# Status checken
docker-compose -f docker-compose.prod.acr.yml ps

# Logs bekijken
docker-compose -f docker-compose.prod.acr.yml logs -f
```

---

## 🎯 Best Practices

### 1. Versioning

- **Gebruik semantic versioning**: `v1.0.0`, `v1.0.1`, etc.
- **Tag altijd als `latest`**: Voor development/CI/CD
- **Productie**: Gebruik specifieke versies, nooit `latest`

```bash
# Tag met versie
git tag v1.0.0
git push origin v1.0.0

# Build met versie
./scripts/build-and-push-azure.sh 1.0.0
```

### 2. Security

- **Admin credentials uitschakelen** in productie (gebruik Service Principal)
- **Enable Content Trust** voor image signing (optioneel)
- **Scan images** voor vulnerabilities (Azure Security Center)

```bash
# Admin uitschakelen
az acr update --name zuyderlandcmdbacr --admin-enabled false
```

### 3. Image Cleanup

ACR heeft een retention policy voor oude images:

```bash
# Retention policy instellen (bijv. laatste 10 tags behouden)
az acr repository show-tags --name zuyderlandcmdbacr --repository zuyderland-cmdb-gui/backend --orderby time_desc --top 10

# Oude tags verwijderen (handmatig of via policy)
az acr repository delete --name zuyderlandcmdbacr --image zuyderland-cmdb-gui/backend:old-tag
```

### 4. Multi-Stage Builds

De `Dockerfile.prod` bestanden gebruiken al multi-stage builds voor kleinere images.

### 5. Build Cache

Voor snellere builds, gebruik build cache:

```bash
# Build met cache
docker build --cache-from zuyderlandcmdbacr.azurecr.io/zuyderland-cmdb-gui/backend:latest \
  -t zuyderlandcmdbacr.azurecr.io/zuyderland-cmdb-gui/backend:new-tag \
  -f backend/Dockerfile.prod ./backend
```

---

## 🔍 Troubleshooting

### Authentication Issues

```bash
# Check Azure login
az account show

# Re-login
az login
az acr login --name zuyderlandcmdbacr

# Check Docker login
cat ~/.docker/config.json
```

### Build Errors

```bash
# Build met verbose output
docker build --progress=plain -t test-image -f backend/Dockerfile.prod ./backend

# Check lokale images
docker images | grep zuyderland-cmdb-gui
```

### Push Errors

```bash
# Check ACR connectivity
az acr check-health --name zuyderlandcmdbacr

# Check repository exists
az acr repository list --name zuyderlandcmdbacr

# View repository tags
az acr repository show-tags --name zuyderlandcmdbacr --repository zuyderland-cmdb-gui/backend
```

### Azure DevOps Pipeline Errors

- Check **Service Connection** permissions
- Verify **ACR naam** in pipeline variables
- Check **Dockerfile paths** zijn correct
- Review pipeline logs in Azure DevOps

---

## 📝 Usage Examples

### Eenvoudige Workflow

```bash
# 1. Code aanpassen en committen
git add .
git commit -m "Update feature"
git push origin main

# 2. Build en push naar ACR
./scripts/build-and-push-azure.sh

# 3. Deploy (op productie server)
az acr login --name zuyderlandcmdbacr
docker-compose -f docker-compose.prod.acr.yml pull
docker-compose -f docker-compose.prod.acr.yml up -d
```

### Versioned Release

```bash
# 1. Tag release
git tag v1.0.0
git push origin v1.0.0

# 2. Build en push met versie
./scripts/build-and-push-azure.sh 1.0.0

# 3. Update docker-compose met versie
# Edit docker-compose.prod.acr.yml: image: ...backend:v1.0.0

# 4. Deploy
docker-compose -f docker-compose.prod.acr.yml pull
docker-compose -f docker-compose.prod.acr.yml up -d
```

### Azure DevOps Automated

1. Push code naar `main` → Pipeline triggert automatisch
2. Pipeline bouwt images en pusht naar ACR
3. Deploy handmatig of via release pipeline

---

## 📚 Additional Resources

- [Azure Container Registry Documentation](https://docs.microsoft.com/en-us/azure/container-registry/)
- [Azure DevOps Docker Task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/build/docker)
- [ACR Best Practices](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-best-practices)
- [Docker Compose Production Guide](./PRODUCTION-DEPLOYMENT.md)

---

## 🔄 Vergelijking: Gitea vs Azure Container Registry

| Feature | Gitea Registry | Azure Container Registry |
|---------|---------------|-------------------------|
| **Kosten** | Gratis (met Gitea) | €5-50/maand (afhankelijk van SKU) |
| **Security** | Basic | Enterprise-grade (RBAC, scanning) |
| **CI/CD** | Gitea Actions | Azure DevOps, GitHub Actions |
| **Geo-replicatie** | Nee | Ja (Standard/Premium) |
| **Image Scanning** | Nee | Ja (Azure Security Center) |
| **Integratie** | Gitea ecosystem | Azure ecosystem (App Service, AKS, etc.) |

**Aanbeveling:**
- **Development/Test**: Gitea Registry (gratis, eenvoudig)
- **Productie**: Azure Container Registry (security, enterprise features)