2026-01-24 18:17:53 +01:00
4 changed files with 554 additions and 0 deletions
@@ -0,0 +1,287 @@
+# Gitea Actions per Data-Coupler
+
+## 📋 Panoramica
+
+Questo repository utilizza **Gitea Actions** per automatizzare la build e la pubblicazione delle immagini Docker del progetto Data-Coupler.
+
+## 🔧 Configurazione
+
+### Prerequisiti
+
+Per utilizzare Gitea Actions su questo repository, è necessario:
+
+1. **Gitea Account**: Avere un account su Gitea (gitea.com o istanza self-hosted)
+2. **Repository Settings**: Abilitare Gitea Actions nelle impostazioni del repository
+3. **Container Registry**: Avere accesso al Gitea Container Registry
+4. **Secret Configuration**: Configurare il secret `GITEA_TOKEN`
+
+### Configurazione del Secret REGISTRY_TOKEN
+
+Il workflow richiede un token di accesso per pubblicare le immagini Docker sul registry:
+
+1. Vai su **Settings → Secrets** nel repository Gitea
+2. Crea un nuovo secret chiamato `REGISTRY_TOKEN`
+3. Il valore deve essere un Personal Access Token con i seguenti permessi:
+   - `write:packages` - Per pubblicare container images
+   - `read:packages` - Per leggere images esistenti
+
+#### Come Creare un Personal Access Token su Gitea
+
+1. Vai su **Settings → Applications** nel tuo profilo Gitea
+2. Clicca su **Generate New Token**
+3. Nome del token: `Data-Coupler Docker Build`
+4. Seleziona i seguenti scopes:
+   - `write:packages`
+   - `read:packages`
+5. Clicca su **Generate Token**
+6. Copia il token generato (sarà mostrato solo una volta)
+
+### Configurazione del Repository Path
+
+Nel file `.gitea/workflows/docker-build.yml`, verifica le variabili di registry:
+
+```yaml
+env:
+  REGISTRY: gitea.home-nas-ds.org  # La tua istanza Gitea self-hosted
+  IMAGE_NAME: alessio/data-coupler  # username/repo sulla tua istanza
+```
+
+**Importante**: 
+- `REGISTRY` deve puntare alla tua istanza Gitea con Container Registry abilitato
+- `IMAGE_NAME` deve essere nel formato `username/repo` della tua istanza
+- Assicurati che il Container Registry sia abilitato su Gitea (Settings → Packages)
+
+## 🚀 Workflow
+
+### Docker Build Workflow
+
+**File**: `.gitea/workflows/docker-build.yml`
+
+#### Trigger Events
+
+Il workflow si attiva automaticamente su:
+- **Push** sui branch: `main`, `development`, `staging`
+- **Manual dispatch** tramite interfaccia web
+
+#### Jobs
+
+Il workflow è composto da 3 job principali:
+
+##### 1. `build-linux` - Build Immagine Linux
+- **Runner**: `ubuntu-latest`
+- **Dockerfile**: `./Dockerfile`
+- **Platform**: `linux/amd64`
+- **Tags generati**:
+  - `latest` (per branch `main` e `development`)
+  - `development-latest` (per branch `development`)
+  - `staging-latest` (per branch `staging`)
+  - `<branch>-<sha>` (per ogni commit)
+  - `<branch>-<timestamp>` (con data/ora)
+
+##### 2. `build-windows` - Build Immagine Windows
+- **Runner**: `windows-2022`
+- **Dockerfile**: `./Dockerfile.windows`
+- **Platform**: Windows Server 2022
+- **Tags generati**: Come Linux ma con suffisso `-windows`
+
+##### 3. `create-manifest` - Multi-Platform Manifest
+- **Runner**: `ubuntu-latest`
+- **Dipendenze**: `build-linux`, `build-windows`
+- Crea manifest multi-piattaforma che combinano le immagini Linux e Windows
+
+### Strategia di Tagging
+
+#### Branch `main`
+- `latest` - Tag condiviso per versione stabile
+- `latest-windows` - Versione Windows
+- `main-<sha>` - Tag specifico per commit
+- `main-<timestamp>` - Tag con timestamp
+
+#### Branch `development`
+- `latest` - Tag condiviso per ultime funzionalità
+- `development-latest` - Tag specifico per development
+- `latest-windows` / `development-latest-windows` - Versioni Windows
+- `development-<sha>` - Tag specifico per commit
+- `development-<timestamp>` - Tag con timestamp
+
+#### Branch `staging`
+- `staging-latest` - Tag per ambiente di staging
+- `staging-latest-windows` - Versione Windows
+- `staging-<sha>` - Tag specifico per commit
+- `staging-<timestamp>` - Tag con timestamp
+
+## 📦 Utilizzo delle Immagini
+
+### Pull delle Immagini
+
+#### Da Gitea Container Registry
+
+```bash
+# Ultima versione stabile (main/development)
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest
+
+# Versione development specifica
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:development-latest
+
+# Versione staging
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:staging-latest
+
+# Versione Windows
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest-windows
+```
+
+### Docker Compose
+
+Modifica il `docker-compose.yml` per usare le immagini Gitea:
+
+```yaml
+services:
+  data-coupler:
+    image: gitea.home-nas-ds.org/alessio/data-coupler:latest
+    # ... resto della configurazione
+```
+
+## 🔍 Monitoraggio
+
+### Visualizzare lo Stato dei Workflow
+
+1. Vai nella tab **Actions** del repository Gitea
+2. Seleziona il workflow **Build and Push Docker Images**
+3. Visualizza i dettagli di ogni esecuzione
+
+### Log e Debug
+
+- I log di ogni job sono disponibili nell'interfaccia Gitea Actions
+- Per debug dettagliato, attiva il manual dispatch con opzione `force_build`
+
+## 🔄 Differenze con GitHub Actions
+
+### Principali Differenze
+
+1. **Context Variables**:
+   - Gitea Actions usa le **stesse variabili** di GitHub Actions: `github.*`
+   - Esempio: `github.ref`, `github.sha`, `github.actor`
+   - **Nota**: Anche se il servizio è Gitea, le variabili mantengono il prefisso `github` per compatibilità
+
+2. **Username**:
+   - Nel workflow è hardcoded come `alessio` per semplicità
+   - Puoi usare `${{ github.actor }}` se preferisci (utente che ha triggerato il workflow)
+
+3. **Registry**:
+   - GitHub: `ghcr.io` → Gitea: `gitea.home-nas-ds.org` (istanza self-hosted)
+   - Gitea non ha un registry pubblico centralizzato come GitHub
+
+4. **Secret Name**:
+   - GitHub: `GITHUB_TOKEN` (automatico) → Gitea: `REGISTRY_TOKEN` (configurato manualmente)
+   - **Nota**: Il secret non può iniziare con `GITEA_` per limitazioni di Gitea
+
+4. **Attestation**:
+   - Il job di attestation non è presente su Gitea (feature GitHub specifica)
+
+### Compatibilità
+
+Gitea Actions è compatibile con la maggior parte delle GitHub Actions disponibili su GitHub Marketplace, incluse:
+- `actions/checkout@v4`
+- `docker/setup-buildx-action@v3`
+- `docker/login-action@v3`
+- `docker/build-push-action@v5`
+- `docker/metadata-action@v5`
+
+## 🛠️ Troubleshooting
+
+### Verificare che il Container Registry sia Abilitato
+
+Prima di tutto, verifica che il Container Registry sia abilitato sulla tua istanza Gitea:
+
+1. **Controlla la configurazione Gitea** (`app.ini`):
+   ```ini
+   [packages]
+   ENABLED = true
+   ```
+
+2. **Verifica accesso al registry**:
+   ```bash
+   curl https://gitea.home-nas-ds.org/v2/
+   # Dovrebbe rispondere con status 401 (richiede autenticazione)
+   # Se ottieni 404, il registry non è abilitato
+   ```
+
+3. **Test autenticazione**:
+   ```bash
+   echo "YOUR_TOKEN" | docker login gitea.home-nas-ds.org -u alessio --password-stdin
+   ```
+
+### Errore di Autenticazione
+
+Se ottieni errori di autenticazione:
+1. Verifica che il secret `REGISTRY_TOKEN` sia configurato correttamente
+2. Assicurati che il token abbia i permessi `write:packages`
+3. Controlla che il token non sia scaduto
+
+### Build Fallita
+
+Se la build fallisce:
+1. Controlla i log del job specifico
+2. Verifica che i Dockerfile siano presenti e corretti
+3. Assicurati che le dipendenze NuGet siano accessibili
+
+### Immagini Non Pubblicate
+
+Se le immagini non vengono pubblicate:
+1. Verifica che `IMAGE_NAME` sia corretto
+2. Controlla che il registry sia accessibile
+3. Verifica i permessi del token
+
+## 📚 Risorse
+
+- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
+- [GitHub Actions Compatibility](https://docs.gitea.io/en-us/usage/actions/comparison/)
+- [Docker Build Push Action](https://github.com/docker/build-push-action)
+
+## 📝 Note
+
+- **Registry Self-Hosted**: Questo workflow è configurato per usare un'istanza Gitea self-hosted (`gitea.home-nas-ds.org`)
+- **Container Registry**: Assicurati che il Container Registry sia abilitato nella tua istanza Gitea (Settings → Packages)
+- **Accesso Pubblico/Privato**: Le immagini sono private per default; configura le impostazioni del package per renderle pubbliche se necessario
+- **Esecuzione Manuale**: Il workflow supporta anche l'esecuzione manuale tramite `workflow_dispatch`
+- **Manifest Multi-Platform**: I manifest multi-platform permettono di usare lo stesso tag per Linux e Windows
+- **Alternative Registry**: Se non hai un'istanza Gitea con registry, puoi configurare Docker Hub o altri registry modificando la variabile `REGISTRY`
+
+### 🐳 Configurazione Registry Alternativi
+
+Se il Container Registry di Gitea non è disponibile, puoi usare alternative:
+
+#### Docker Hub
+```yaml
+env:
+  REGISTRY: docker.io
+  IMAGE_NAME: username/data-coupler
+
+# Nel login step:
+- name: Log in to Docker Hub
+  uses: docker/login-action@v3
+  with:
+    username: ${{ secrets.DOCKER_USERNAME }}
+    password: ${{ secrets.DOCKER_TOKEN }}
+```
+
+#### GitHub Container Registry (come fallback)
+```yaml
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: alessio/data-coupler
+
+# Nel login step:
+- name: Log in to GHCR
+  uses: docker/login-action@v3
+  with:
+    registry: ghcr.io
+    username: ${{ github.actor }}
+    password: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+**Versione**: 1.0  
+**Ultimo Aggiornamento**: 24 Gennaio 2026  
+**Maintainer**: Alessio Dalsanto
@@ -0,0 +1,228 @@
+name: Build and Push Docker Images
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+  workflow_dispatch:
+    inputs:
+      force_build:
+        description: 'Force build even without code changes'
+        required: false
+        default: false
+        type: boolean
+
+env:
+  # Gitea Container Registry (self-hosted instance)
+  REGISTRY: gitea.home-nas-ds.org
+  # Repository path (format: owner/repo)
+  IMAGE_NAME: alessio/data-coupler
+
+jobs:
+  build-linux:
+    name: Build Linux Container
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Debug - Check registry access
+        run: |
+          echo "Testing registry access..."
+          curl -v https://gitea.home-nas-ds.org/v2/ || echo "Registry not accessible"
+          echo "Registry: ${{ env.REGISTRY }}"
+          echo "Image: ${{ env.IMAGE_NAME }}"
+        continue-on-error: true
+
+      - name: Debug - Verify secret is configured
+        run: |
+          if [ -z "${{ secrets.REGISTRY_TOKEN }}" ]; then
+            echo "::error::REGISTRY_TOKEN secret is not configured or is empty!"
+            exit 1
+          else
+            echo "REGISTRY_TOKEN secret is configured (length: ${#REGISTRY_TOKEN})"
+          fi
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Log in to Gitea Container Registry
+        run: |
+          echo "${{ secrets.REGISTRY_TOKEN }}" | docker login ${{ env.REGISTRY }} -u alessio --password-stdin
+        shell: bash
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            # Tag based on branch
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/development' }}
+            type=raw,value=development-latest,enable=${{ github.ref == 'refs/heads/development' }}
+            type=raw,value=dev-latest,enable=${{ github.ref == 'refs/heads/dev' }}
+            type=raw,value=staging-latest,enable=${{ github.ref == 'refs/heads/staging' }}
+            # Tag with commit sha
+            type=sha,prefix={{branch}}-,format=short
+            # Tag with date
+            type=raw,value={{branch}}-{{date 'YYYYMMDD-HHmmss'}}
+          flavor: |
+            latest=false
+
+      - name: Build and push Linux Docker image
+        id: build
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64
+
+  build-windows:
+    name: Build Windows Container
+    runs-on: windows
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Checkout repository with Git
+        run: |
+          git clone --depth 1 --branch ${{ github.ref_name }} https://alessio:%REGISTRY_TOKEN%@gitea.home-nas-ds.org/${{ github.repository }}.git .
+          if not exist Dockerfile.windows (
+            echo ERROR: Dockerfile.windows not found
+            exit /b 1
+          )
+          echo SUCCESS: Repository cloned
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        shell: cmd
+
+      - name: Debug - Verify files
+        run: |
+          echo Working directory:
+          cd
+          echo.
+          echo Dockerfiles found:
+          dir Dockerfile* /B 2>nul || echo No Dockerfiles found
+        shell: cmd
+        continue-on-error: true
+
+      - name: Debug - Verify secret
+        run: |
+          if "${{ secrets.REGISTRY_TOKEN }}"=="" (
+            echo ERROR: REGISTRY_TOKEN not configured!
+            exit /b 1
+          ) else (
+            echo REGISTRY_TOKEN is configured
+          )
+        shell: cmd
+
+      - name: Log in to Gitea Container Registry
+        run: echo ${{ secrets.REGISTRY_TOKEN }} | docker login ${{ env.REGISTRY }} -u alessio --password-stdin
+        shell: cmd
+
+      - name: Build and push Windows Docker image
+        run: |
+          set IMAGE_LOWER=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          set BRANCH=${{ github.ref_name }}
+          set SHA=${{ github.sha }}
+          set SHORT_SHA=%SHA:~0,7%
+          
+          REM Determine tags based on branch
+          set TAGS=
+          if "%BRANCH%"=="main" (
+            set TAGS=%IMAGE_LOWER%:latest-windows
+            set TAGS=%TAGS% %IMAGE_LOWER%:main-windows-%SHORT_SHA%
+          )
+          if "%BRANCH%"=="development" (
+            set TAGS=%IMAGE_LOWER%:latest-windows
+            set TAGS=%TAGS% %IMAGE_LOWER%:development-latest-windows
+            set TAGS=%TAGS% %IMAGE_LOWER%:development-windows-%SHORT_SHA%
+          )
+          if "%BRANCH%"=="staging" (
+            set TAGS=%IMAGE_LOWER%:staging-latest-windows
+            set TAGS=%TAGS% %IMAGE_LOWER%:staging-windows-%SHORT_SHA%
+          )
+          
+          echo Building Windows Docker image...
+          docker build -t temp-windows -f Dockerfile.windows .
+          if errorlevel 1 (
+            echo Build failed!
+            exit /b 1
+          )
+          
+          echo Tagging and pushing images...
+          for %%t in (%TAGS%) do (
+            echo Tagging: %%t
+            docker tag temp-windows %%t
+            echo Pushing: %%t
+            docker push %%t
+          )
+          
+          echo Cleaning up temporary image...
+          docker rmi temp-windows
+          
+          echo Windows build completed successfully!
+        shell: cmd
+
+  create-manifest:
+    name: Create Multi-Platform Manifest
+    runs-on: ubuntu-latest
+    needs: [build-linux, build-windows]
+    permissions:
+      contents: read
+      packages: write
+      
+    steps:
+      - name: Log in to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: alessio
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Create and push manifest for main branch
+        if: github.ref == 'refs/heads/main'
+        run: |
+          IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]')
+          docker buildx imagetools create -t ${IMAGE_LOWER}:latest \
+            ${IMAGE_LOWER}:latest \
+            ${IMAGE_LOWER}:latest-windows
+
+      - name: Create and push manifest for development branch
+        if: github.ref == 'refs/heads/development'
+        run: |
+          IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]')
+          docker buildx imagetools create -t ${IMAGE_LOWER}:latest \
+            ${IMAGE_LOWER}:latest \
+            ${IMAGE_LOWER}:latest-windows
+          docker buildx imagetools create -t ${IMAGE_LOWER}:development-latest \
+            ${IMAGE_LOWER}:development-latest \
+            ${IMAGE_LOWER}:development-latest-windows
+
+      - name: Create and push manifest for dev branch
+        if: github.ref == 'refs/heads/dev'
+        run: |
+          IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]')
+          docker buildx imagetools create -t ${IMAGE_LOWER}:dev-latest \
+            ${IMAGE_LOWER}:dev-latest \
+            ${IMAGE_LOWER}:dev-latest-windows
+
+      - name: Create and push manifest for staging branch
+        if: github.ref == 'refs/heads/staging'
+        run: |
+          IMAGE_LOWER=$(echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]')
+          docker buildx imagetools create -t ${IMAGE_LOWER}:staging-latest \
+            ${IMAGE_LOWER}:staging-latest \
+            ${IMAGE_LOWER}:staging-latest-windows
@@ -368,15 +368,26 @@
 - `hotfix/*`: Fix urgenti

 ### CI/CD Pipeline:
+
+#### GitHub Actions (`.github/workflows/docker-build.yml`)
 - **Branch `main`**: Pubblica immagini Docker con tag `latest`
 - **Branch `development`**: Pubblica immagini Docker con tag `latest` e `development-latest`
 - **Branch `staging`**: Pubblica immagini Docker con tag `staging-latest`
 - **Ogni commit**: Crea tag con SHA e timestamp per tracciabilità
+- **Registry**: GitHub Container Registry (`ghcr.io`)
+
+#### Gitea Actions (`.gitea/workflows/docker-build.yml`)
+- **Stessa configurazione** di GitHub Actions
+- **Registry**: Gitea Container Registry (`gitea.home-nas-ds.org`)
+- **Supporto**: Istanza Gitea self-hosted con registry abilitato
+- **Setup**: Richiede secret `REGISTRY_TOKEN` con permessi `write:packages`
+- **Documentazione**: `.gitea/workflows/README.md`

 **Note sui Tag Docker**:
 - `latest`: Condiviso tra `main` e `development` per garantire accesso alle ultime funzionalità
 - `development-latest`: Specifico per il branch `development`, utile per distinguere le versioni in sviluppo
 - `staging-latest`: Dedicato al branch `staging` per test pre-produzione
+- Disponibile su **entrambi** i registry (GitHub e Gitea)

 ### Commit Messages:
 - Formato: `[Tipo] Descrizione breve`
@@ -399,6 +410,7 @@
 - **DELETION_SYNC_IMPLEMENTATION.md**: Sincronizzazione eliminazioni
 - **DOCKER_DEPLOYMENT.md**: Guida deployment Docker
 - **WINDOWS_SERVICE_DEPLOYMENT.md**: Deploy come Windows Service
+- **.gitea/workflows/README.md**: Configurazione Gitea Actions

 ## 🎓 Best Practices per AI Assistants

@@ -167,6 +167,33 @@ docker build -t data-coupler:local-windows -f Dockerfile.windows .

 📚 **Documentazione Docker Completa**: Vedi [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md) e [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md)

+### 🔄 CI/CD Pipeline
+
+Il progetto supporta pipeline CI/CD automatiche su:
+
+**GitHub Actions** (`.github/workflows/docker-build.yml`):
+- Build automatica su push ai branch `main`, `development`, `staging`
+- Pubblicazione su GitHub Container Registry (`ghcr.io`)
+- Multi-platform manifest (Linux + Windows)
+
+**Gitea Actions** (`.gitea/workflows/docker-build.yml`):
+- Stessa configurazione di GitHub Actions
+- Pubblicazione su Gitea Container Registry (`gitea.home-nas-ds.org`)
+- Istanza Gitea self-hosted con registry abilitato
+- Configurazione: `.gitea/workflows/README.md`
+
+**Immagini su Gitea** (self-hosted):
+```bash
+# Pull da Gitea Container Registry
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest
+
+# Versioni disponibili
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:development-latest
+docker pull gitea.home-nas-ds.org/alessio/data-coupler:staging-latest
+```
+
+📚 **Setup Gitea**: Vedi [.gitea/workflows/README.md](.gitea/workflows/README.md)
+
 ## Caratteristiche di Sicurezza

 - **Crittografia**: Le password vengono crittografate prima del salvataggio