diff --git a/.gitea/workflows/README.md b/.gitea/workflows/README.md new file mode 100644 index 0000000..7262958 --- /dev/null +++ b/.gitea/workflows/README.md @@ -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`) + - `-` (per ogni commit) + - `-` (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-` - Tag specifico per commit +- `main-` - 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-` - Tag specifico per commit +- `development-` - Tag con timestamp + +#### Branch `staging` +- `staging-latest` - Tag per ambiente di staging +- `staging-latest-windows` - Versione Windows +- `staging-` - Tag specifico per commit +- `staging-` - 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 diff --git a/.gitea/workflows/docker-build.yml b/.gitea/workflows/docker-build.yml new file mode 100644 index 0000000..ba6f87f --- /dev/null +++ b/.gitea/workflows/docker-build.yml @@ -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 diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7d4c16c..52b98a0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 diff --git a/README.md b/README.md index d74a51e..82f3118 100644 --- a/README.md +++ b/README.md @@ -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