Data-Coupler/PUBLIC_CONTAINER_SETUP.md

# 🔓 Configurazione Container Pubblico - Guida Step-by-Step

## Obiettivo
Rendere il container Docker pull-able **senza credenziali** da chiunque.

## ⚠️ Considerazioni Importanti

### Pro e Contro

#### ✅ Vantaggi Container Pubblico
- Nessuna autenticazione richiesta per pull
- Facile distribuzione per utenti finali
- Ideale per progetti open source
- Riduce friction nell'adozione
- Nessun token management per utenti

#### ⚠️ Svantaggi Container Pubblico
- Il codice compilato è accessibile pubblicamente
- Chiunque può scaricare e analizzare l'immagine
- Nessun controllo su chi usa il container
- Potenziale esposizione di configurazioni hardcoded

## 🔒 Alternative al Container Pubblico

Se la privacy è importante, considera invece:

### Opzione 1: Container Privato + GitHub Team Access
```yaml
Configurazione:
1. Container rimane privato
2. Aggiungi membri team con permessi read
3. Team members usano loro GitHub PAT per pull

Vantaggi:
- Controllo accessi granulare
- Audit trail degli accessi
- Solo team autorizzato può scaricare
```

### Opzione 2: Container Privato + Deploy Keys
```yaml
Configurazione:
1. Container rimane privato
2. Crea bot account per CI/CD
3. Bot account ha read-only access al package
4. Deploy keys distribuite solo a server autorizzati

Vantaggi:
- Nessun accesso umano diretto
- Token rotativi per sicurezza
- Adatto per production deployments
```

### Opzione 3: Azure Container Registry / AWS ECR (Privati)
```yaml
Configurazione:
1. Push su registry privato Azure/AWS
2. Usa managed identities per pull
3. Nessuna credenziale hardcoded

Vantaggi:
- Integrazione nativa cloud
- Nessun costo GitHub Package storage
- Policy avanzate di retention
```

## 📋 Se Decidi per Container Pubblico

### Step 1: Verifica Prima Build Completata

```bash
# 1. Fai push del codice su GitHub
git add .
git commit -m "Add Docker support and CI/CD"
git push origin main

# 2. Vai su GitHub Actions
# https://github.com/[USERNAME]/Data-Coupler/actions

# 3. Attendi completamento workflow "Build and Push Docker Images"
# Deve mostrare ✅ verde su tutti i job
```

### Step 2: Trova il Package

```
1. Vai al tuo repository GitHub
   URL: https://github.com/[USERNAME]/Data-Coupler

2. Click sulla tab "Packages" (lato destro)
   Oppure: https://github.com/[USERNAME]?tab=packages

3. Dovresti vedere il package "data-coupler"
   Se non lo vedi, verifica che la build sia completata con successo
```

### Step 3: Cambia Visibilità a Pubblico

```
1. Click sul package "data-coupler"

2. Click su "Package settings" (icona ingranaggio in alto a destra)

3. Scroll fino alla sezione "Danger Zone" (in fondo alla pagina)

4. Trova "Change package visibility"

5. Click sul pulsante "Change visibility"

6. Nella dialog che appare:
   - Seleziona "Public"
   - Leggi il warning
   - Digita il nome completo del repository: [USERNAME]/Data-Coupler
   - Click "I understand the consequences, change package visibility"

7. Conferma con la tua password se richiesto
```

### Step 4: Verifica Configurazione Pubblica

```
1. Logout da GitHub (o usa finestra incognito)

2. Vai a: https://github.com/[USERNAME]/Data-Coupler/pkgs/container/data-coupler

3. Dovresti vedere:
   - Badge "Public" vicino al nome
   - Pull command senza autenticazione:
     docker pull ghcr.io/[username]/data-coupler:latest

4. La sezione "Installation" mostra come fare pull senza credenziali
```

### Step 5: Test Pull Senza Autenticazione

```bash
# 1. Logout da GitHub Container Registry (se sei loggato)
docker logout ghcr.io

# 2. Pull senza credenziali
docker pull ghcr.io/[username]/data-coupler:latest

# Se funziona, vedrai:
# latest: Pulling from [username]/data-coupler
# [hash]: Pull complete
# ...
# Status: Downloaded newer image for ghcr.io/[username]/data-coupler:latest

# 3. Test run
docker run -d -p 7550:7550 --name data-coupler-test \
  ghcr.io/[username]/data-coupler:latest

# 4. Verifica funzionamento
sleep 10
curl http://localhost:7550/health
# Output: {"status":"healthy","timestamp":"..."}

# 5. Cleanup
docker stop data-coupler-test
docker rm data-coupler-test
```

## 🔧 Configurazione GitHub Actions per Pubblico

Le GitHub Actions sono già configurate correttamente per container pubblici. Non servono modifiche.

**Configurazione Attuale** (`.github/workflows/docker-build.yml`):
```yaml
- name: Log in to GitHub Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}  # ✅ Usa token automatico
```

Il `GITHUB_TOKEN` ha già i permessi necessari se:
1. ✅ Workflow permissions = "Read and write"
2. ✅ Package è pubblico

## 📝 Aggiorna Documentazione

Dopo aver reso pubblico il container, aggiorna i riferimenti:

### File da Aggiornare

1. **README.md**
```markdown
## Quick Start

\`\`\`bash
# Pull e run (nessuna autenticazione richiesta)
docker run -d -p 7550:7550 ghcr.io/[username]/data-coupler:latest
\`\`\`
```

2. **DOCKER_DEPLOYMENT.md**
Assicurati che la sezione "Pull senza autenticazione" sia prominente.

3. **GITHUB_ACTIONS_SETUP.md**
Aggiungi nota che il container è configurato come pubblico.

## 🔄 Come Tornare Privato

Se cambi idea:

```
1. Package settings → Danger Zone → Change visibility
2. Seleziona "Private"
3. Conferma

Da quel momento in poi, il pull richiederà autenticazione:
docker login ghcr.io -u USERNAME
Password: [GitHub PAT]
```

## 📊 Monitoraggio Container Pubblico

### Statistiche Disponibili

Nel package settings puoi vedere:
- **📈 Download count**: Quante volte è stato scaricato
- **📦 Storage used**: Spazio occupato su GitHub
- **🏷️ Tags**: Tutte le versioni disponibili
- **📅 Activity**: Storia degli aggiornamenti

### Costi

**GitHub Container Registry:**
- ✅ Container pubblici: Storage **GRATUITO** illimitato
- ✅ Pull pubblici: Bandwidth **GRATUITO** illimitato
- ⚠️ Container privati: 500MB storage gratuito, poi $0.008/GB/mese

## 🚨 Security Best Practices (Anche per Container Pubblici)

### 1. Non Hardcodare Secrets
```dockerfile
❌ MAI:
ENV API_KEY="hardcoded-secret-key"
ENV PASSWORD="admin123"

✅ SEMPRE:
ENV API_KEY=""  # Impostato a runtime con -e
```

### 2. Multi-Stage Build (Già Implementato)
```dockerfile
✅ Il Dockerfile usa multi-stage:
FROM sdk AS build    # Immagine grande con compilatori
FROM aspnet AS final # Solo runtime, immagine piccola
# Risultato: codice sorgente NON incluso nell'immagine finale
```

### 3. Scan delle Vulnerabilità
```bash
# Usa Trivy per scan sicurezza
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy image ghcr.io/[username]/data-coupler:latest

# Oppure integra in GitHub Actions (future enhancement)
```

### 4. Firma delle Immagini
```yaml
# GitHub Actions già genera attestazioni (configurato)
- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v1
  # Crea firma crittografica verificabile
```

## ✅ Checklist Finale

Prima di rendere pubblico, verifica:

- [ ] Build GitHub Actions completata con successo
- [ ] Nessun secret hardcodato nei Dockerfile
- [ ] Database path configurato correttamente per volumes
- [ ] Health endpoint funziona
- [ ] Test pull e run eseguiti con successo
- [ ] Documentazione aggiornata con nuovo registry URL
- [ ] Team informato del cambio di visibilità

## 📞 Rollback Plan

Se qualcosa va storto:

```bash
# 1. Torna privato immediatamente
# Package settings → Private

# 2. Se serve, elimina tag specifico
docker rmi ghcr.io/[username]/data-coupler:problematic-tag

# 3. Re-build e re-push
git revert [commit-hash]
git push origin main
# GitHub Actions ri-builda automaticamente
```

---

**Data Creazione**: 16 Gennaio 2026  
**Versione Guida**: 1.0  
**Raccomandazione**: ✅ Pubblico per Open Source | ⚠️ Privato per Enterprise