Data-Coupler/GITHUB_ACTIONS_SETUP.md

Configurazione GitHub Actions per Docker Container Registry

🔧 Setup Iniziale

Questa guida spiega come configurare il repository GitHub per abilitare la build automatica e il push delle immagini Docker.

📋 Prerequisiti

1. Repository GitHub con il codice sorgente
2. Abilitazione GitHub Packages per il repository
3. Permessi di scrittura sui packages

⚙️ Configurazione Repository

1. Abilitazione GitHub Packages

Le GitHub Actions sono già configurate per usare il GITHUB_TOKEN automatico. Non è necessario creare token aggiuntivi.

2. Configurazione Secrets (Opzionale)

Se vuoi usare un registry diverso da GitHub Container Registry, aggiungi questi secrets:

1. Vai su: Settings → Secrets and variables → Actions
2. Click su New repository secret
3. Aggiungi:
   • REGISTRY_USERNAME: Username del registry
   • REGISTRY_PASSWORD: Password o token del registry

3. Abilitazione Workflow

Il workflow è già configurato in .github/workflows/docker-build.yml e si attiverà automaticamente su:

• Push su branch main, dev, staging
• Manualmente tramite workflow_dispatch

🚀 Utilizzo

Build Automatica

Ogni volta che fai push su uno dei branch configurati, il workflow:

1. ✅ Compila il progetto .NET
2. 🐳 Crea immagini Docker per Linux e Windows
3. 📤 Fa push su GitHub Container Registry
4. 🏷️ Applica i tag appropriati basati sul branch

Tag Generati

Branch Main

• latest (multi-platform)
• latest-windows (solo Windows)
• main-{sha} (commit specifico)
• main-{date} (timestamp)

Branch Dev

• dev-latest (multi-platform)
• dev-latest-windows (solo Windows)
• dev-{sha} (commit specifico)
• dev-{date} (timestamp)

Branch Staging

• staging-latest (multi-platform)
• staging-latest-windows (solo Windows)
• staging-{sha} (commit specifico)
• staging-{date} (timestamp)

Build Manuale

Per avviare una build manuale:

1. Vai su Actions nel repository GitHub
2. Seleziona il workflow Build and Push Docker Images
3. Click su Run workflow
4. Seleziona il branch
5. (Opzionale) Spunta Force build per forzare la build
6. Click su Run workflow

🔐 Gestione Visibilità Container

Rendere il Container Pubblico (No Authentication Required)

Per consentire il pull senza autenticazione:

1. Vai su: https://github.com/[YOUR_USERNAME]/Data-Coupler/packages
2. Seleziona il package data-coupler
3. Click su Package settings (icona ingranaggio)
4. Scroll down fino a Danger Zone
5. Click su Change visibility
6. Seleziona Public
7. Digita il nome del repository per confermare
8. Click su I understand, change package visibility

⚠️ Attenzione: Un container pubblico può essere scaricato da chiunque su internet.

Container Privato con Accesso Team

Per mantenere il container privato ma accessibile al team:

1. Vai su Package settings
2. Nella sezione Manage Actions access:
   • Seleziona Inherit access from source repository
3. Per dare accesso a utenti specifici:
   • Scroll alla sezione Manage teams and people access
   • Click su Add teams o Add people
   • Seleziona l'utente/team e il livello di accesso (Read, Write, Admin)

Token per Pull Privati

Se il container rimane privato, gli utenti dovranno autenticarsi:

# 1. Crea un Personal Access Token
#    GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
#    Scope richiesto: read:packages

# 2. Login
echo "ghp_YOUR_TOKEN" | docker login ghcr.io -u YOUR_USERNAME --password-stdin

# 3. Pull
docker pull ghcr.io/alessiodalsi/data-coupler:latest

🔍 Verifica Build

Check Status Workflow

1. Vai su Actions nel repository
2. Verifica che il workflow sia completato con successo (✅)
3. Click sul workflow per vedere i dettagli

Verifica Immagini Pubblicate

1. Vai su: https://github.com/[YOUR_USERNAME]/Data-Coupler/packages
2. Verifica che il package data-coupler sia presente
3. Click sul package per vedere tutti i tag disponibili

Test Pull Immagine

# Test pull (se pubblico)
docker pull ghcr.io/alessiodalsi/data-coupler:latest

# Verifica immagine
docker images | grep data-coupler

# Test run
docker run -d -p 7550:7550 ghcr.io/alessiodalsi/data-coupler:latest

# Verifica funzionamento
curl http://localhost:7550/health

📊 Monitoraggio

Visualizzare Log di Build

1. Vai su Actions
2. Click sul workflow run
3. Espandi i job build-linux e build-windows
4. Visualizza i log dettagliati di ogni step

Statistiche Package

Nella pagina del package puoi vedere:

• 📈 Download totali
• 📦 Dimensione immagini
• 🏷️ Tag disponibili
• 📅 Data ultima modifica

🛠️ Troubleshooting

Workflow Fallisce

Errore: Permessi insufficienti

Error: failed to solve: failed to push: insufficient_scope

Soluzione: Verifica che le Actions abbiano permessi di scrittura:

• Settings → Actions → General
• Sezione Workflow permissions
• Seleziona Read and write permissions
• Salva

Errore: Build timeout

Error: The operation was canceled

Soluzione:

• Verifica che non ci siano file grandi non necessari
• Controlla il .dockerignore
• Aumenta il timeout nel workflow (default: 360 minuti)

Push Fallisce

Errore: Authentication required

Error: failed to authorize: failed to fetch anonymous token

Soluzione: Il GITHUB_TOKEN dovrebbe funzionare automaticamente. Se persiste:

1. Vai su Settings → Actions → General
2. Verifica che GITHUB_TOKEN abbia permessi packages

Immagine Non Si Avvia

Errore: Database not initialized

Error: Timeout durante l'inizializzazione del database

Soluzione: Monta un volume per persistere i dati:

docker run -d \
  -v /var/lib/data-coupler:/var/lib/Data_Coupler \
  ghcr.io/alessiodalsi/data-coupler:latest

📚 Risorse Aggiuntive

• GitHub Packages Documentation
• GitHub Actions Docker Build
• Docker Best Practices

🆘 Supporto

Se riscontri problemi:

1. Controlla i log del workflow su GitHub Actions
2. Verifica la documentazione in DOCKER_DEPLOYMENT.md
3. Apri una issue sul repository GitHub

---

Ultimo Aggiornamento: Gennaio 2026
Versione Workflow: 1.0