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

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

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)

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

# 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

# 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):

- 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

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

❌ 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)

✅ 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à

# 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

# 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:

# 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