Alessio
f3afede0e1
- Aggiunto step debug per verificare accesso al registry - Documentazione completa su come verificare Container Registry - Aggiunte istruzioni per registry alternativi (Docker Hub, GHCR) - Guida per testare autenticazione manualmente
288 lines
9.0 KiB
Markdown
288 lines
9.0 KiB
Markdown
# 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
|