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:

```bash
# 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

```bash
# 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:
```bash
docker run -d \
  -v /var/lib/data-coupler:/var/lib/Data_Coupler \
  ghcr.io/alessiodalsi/data-coupler:latest
```

## 📚 Risorse Aggiuntive

- [GitHub Packages Documentation](https://docs.github.com/en/packages)
- [GitHub Actions Docker Build](https://docs.github.com/en/actions/publishing-packages/publishing-docker-images)
- [Docker Best Practices](https://docs.docker.com/develop/dev-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