Dal repository al cloud: anteprima per il cliente e deploy con Harbor

Uno store vale quanto il percorso che il codice compie per raggiungerlo. Tra un repository vuoto e il giorno in cui il cliente clicca un URL pubblico ci sono quattro tappe: il repository, la tua macchina, un link di anteprima e il server di produzione. Harbor, il launcher Docker Compose per Maho, copre la tappa locale; un tunnel Cloudflare trasforma il tuo portatile in un URL da consegnare; MageMEGA si occupa dell’ultimo miglio con un pulsante di deploy. Questo tutorial percorre tutto il giro su Linux, macOS e Windows con WSL, partendo da un repository vuoto. Non importa cosa vende lo store, solo che una modifica passi dall’editor a una pagina pubblica senza sorprese. L’intero flusso entra in quattro comandi:

git push origin main                          # memorizza la modifica
./vendor/bin/harbor tunnel quick --autoconfig # mostrala al cliente
# ... poi premi Deploy nel pannello MageMEGA  # pubblicala

⚓ Nota di bordo. Ogni partenza ha bisogno di un porto che conosca la nave, di una banchina che la tenga e di un faro che il cliente veda dalla riva. Qui il repository è il porto, Harbor è la banchina e il tunnel è il faro.

Requisiti

Gli esempi usano Harbor, il launcher Docker Compose open source di MageMEGA, ispirato a Laravel Sail.

Sulla macchina host servono:

• Docker con il plugin Compose v2: Docker Desktop su macOS e Windows, Docker Desktop o Docker Engine su Linux. Harbor preferisce docker compose e ripiega su docker-compose.
• PHP >= 8.3, solo per eseguire Composer, per creare il progetto e aggiungere Harbor. Tutto il resto gira nel container, che monta PHP 8.4 di default.
• Git e un account su GitHub, GitLab o Bitbucket.
• Un account MageMEGA per l’ultimo passaggio (facoltativo se ti basta l’anteprima locale).

Windows: lavora dentro WSL

Su Windows, esegui ogni comando di questo tutorial dentro una distribuzione WSL2 (Ubuntu è la scelta abituale):

• Installa Docker Desktop con il backend WSL2, oppure Docker Engine dentro la distribuzione.
• Installa Git e PHP/Composer nella distribuzione, non solo sul lato Windows.
• Tieni il progetto nel filesystem Linux, per esempio ~/projects/my-store. Non lavorare sotto /mnt/c: il file watching è lento e i container vedono un mount diverso.
• Apri https://localhost:8443 dal browser di Windows come al solito: WSL2 inoltra localhost.

Quick start: da un repository vuoto a una pagina pubblica

1. Crea il repository

Parti dal lato hosting, non dal portatile. Crea un repository vuoto su GitHub (GitLab e Bitbucket funzionano allo stesso modo): niente README, niente .gitignore, niente licenza, così il primo push non ha nulla da riconciliare. Chiamalo come il progetto, per esempio my-store, e tienilo privato finché è un progetto per un cliente.

Copia l’URL SSH, è simile a [email protected]:<owner>/my-store.git. MageMEGA clona solo via SSH, quindi restiamo su SSH fin dall’inizio. Per fare push tu stesso via SSH ti serve anche la tua chiave aggiunta all’hosting Git: la deploy key che ti fornisce MageMEGA è una chiave separata, lato server, che aggiungiamo al passo 6.

2. Crea il progetto Maho e aggiungi Harbor

composer create-project mahocommerce/maho-starter my-store
cd my-store
composer require --dev empiricompany/harbor   # oppure :dev-main per l'ultima versione

3. Avvia lo stack locale

harbor init genera la cartella .harbor/ con i file del progetto (.env, compose.yaml, docker.override.yaml, docker.install.yaml). Poi costruisci e avvia lo stack: la prima build richiede dai 5 ai 20 minuti, il momento giusto per farsi un caffè invece di premere Ctrl+C.

./vendor/bin/harbor init
./vendor/bin/harbor up -d --build
./vendor/bin/harbor ps

Installa le dipendenze PHP e Maho dentro il container:

./vendor/bin/harbor composer install

./vendor/bin/harbor maho install --license_agreement_accepted yes \
  --locale it_IT --timezone Europe/Rome --default_currency EUR \
  --db_host db --db_name maho --db_user maho --db_pass maho \
  --url 'https://localhost:8443/' --use_secure 1 --secure_base_url 'https://localhost:8443/' \
  --use_secure_admin 1 --admin_username admin --admin_password 'cambiami-forte' \
  --sample_data 1

Lo store ora è su https://localhost:8443/. Da qui sviluppi normalmente: modifichi i file, poi lanci harbor maho cache:flush (e harbor maho migrate dopo aver installato un modulo). Il flusso completo di Harbor, dalla CLI ai profili opzionali, è in Sviluppo locale di Maho con Harbor; qui lo usiamo solo come motore del giro.

4. Collega il repository e fai il primo push

composer create-project scrive il progetto ma non crea un repository Git, quindi inizializzalo e collegalo al remote:

git init
git branch -M main
git remote add origin [email protected]:<owner>/my-store.git
git add -A
git commit -m "Progetto Maho iniziale con Harbor"
git push -u origin main

Esegui git status prima del primo commit e assicurati che vendor/ e i file generati in .harbor/ non siano in stage. harbor init scrive .harbor/.gitignore, che esclude il compose.yaml generato e, soprattutto, .harbor/.env: quel file contiene il token del tunnel e la password del database e non va mai pushato.

5. Passa al cliente un link di anteprima

Un tunnel espone lo store locale su un URL HTTPS pubblico senza aprire nessuna porta sul router. Il quick tunnel non richiede alcun account Cloudflare:

./vendor/bin/harbor tunnel quick --autoconfig

Harbor avvia il tunnel e stampa un URL simile a https://parole-casuali-qui.trycloudflare.com. --autoconfig punta i base URL di Maho all’URL pubblico, disattiva il redirect automatico ai base URL, poi reindicizza e svuota la cache; senza il flag Harbor stampa solo i comandi da eseguire. Copia l’URL, mandalo al cliente e lascialo navigare.

Le email inviate dall’anteprima vengono comunque intercettate da Mailpit sulla tua macchina, quindi il cliente non riceverà messaggi reali: comodo per testare le conferme d’ordine senza spammare nessuno. Le leggi su http://localhost:8025.

L’URL del quick tunnel è effimero: sparisce quando il tunnel si ferma. Per una demo che ripeti, usa un named tunnel con un hostname fisso:

./vendor/bin/harbor tunnel up --autoconfig

tunnel up legge HARBOR_CLOUDFLARED_TOKEN e HARBOR_CLOUDFLARED_HOSTNAME da .harbor/.env. Quando il cliente ha finito, ritira la passerella e rimetti Maho su localhost:

./vendor/bin/harbor tunnel down --autoconfig

⚓ Nota di bordo. Il tunnel è una passerella calata sulla banchina, non un molo nuovo: lo store è ancora sul tuo portatile, ed è raggiungibile dalla riva solo finché la passerella è giù.

6. Configura MageMEGA una volta, poi fai deploy con un pulsante

Apri il sito nel pannello cloud MageMEGA e collegalo al repository. Il pannello fa parte dell’hosting MageMEGA: se non lo conosci, la panoramica è nella pagina Hosting gestito per MahoCommerce. È un lavoro che si fa una volta sola.

1. Vai su Source → Deploy Key e copia la chiave pubblica.
2. Aggiungila al repository Git come deploy key, così il server può clonare il codice:
   • GitHub: Settings → Deploy keys → Add deploy key. Spunta “Allow write access” solo se il server deve fare push.
   • GitLab: Settings → Repository → Deploy keys.
   • Bitbucket: Settings → Access keys.
3. Vai su Source → Repository e compila:
   • Repository URL: l’URL SSH, [email protected]:<owner>/my-store.git. Il pannello accetta solo URL SSH, perché la deploy key non può autenticarsi su HTTPS.
   • Branch: main.

Prima di salvare, il pannello ti ricorda due cose: la deploy key deve essere già stata aggiunta al repository e il branch deve esistere già sul remote. Entrambe le condizioni sono vere dopo il passo 4. Clicca Save & Deploy: il server scarica il codice ed esegue il primo deployment. La scheda Deployment Log mostra cosa è successo.

7. Il ciclo quotidiano

Da questo momento ogni modifica segue lo stesso percorso breve: sviluppa, mostra in anteprima, push, deploy.

# 1. modifica il progetto, poi svuota la cache
./vendor/bin/harbor maho cache:flush

# 2. guardalo sull'URL di anteprima mentre lavori
./vendor/bin/harbor tunnel quick --autoconfig

# 3. memorizza la modifica e mandala al server
git add -A
git commit -m "Aggiunge il nuovo banner in homepage"
git push origin main

Poi apri la scheda del sito nel pannello MageMEGA e premi Deploy. Il server scarica main e rifà il deploy; l’avanzamento e l’esito sono in Deployment Log. Ferma il tunnel di anteprima quando non ti serve più:

./vendor/bin/harbor tunnel down --autoconfig

Il giro in sintesi

repository  →  harbor up -d        →  harbor tunnel quick  →  git push origin main  →  Deploy
 memorizza        avvia in locale        mostra al cliente        salva la modifica      pubblica

Quattro strumenti, un compito ciascuno: il repository memorizza, Harbor avvia, il tunnel mostra, MageMEGA pubblica. Il cliente riceve un link, il codice resta in un solo posto e il resto lo fa il pulsante.

⚓ Ultima nota di bordo. Il porto è segnato sulla carta, la banchina è pronta e il faro è acceso. Non resta che issare la vela e premere Deploy. Buon vento.

Risoluzione dei problemi

./vendor/bin/harbor doctor      # valida Docker, Compose e lo stack
./vendor/bin/harbor ps          # mostra cosa gira
./vendor/bin/harbor logs app    # errori PHP e access log di Caddy
./vendor/bin/harbor config      # mostra la configurazione Compose effettiva

• L’URL del tunnel non si apre. Aspetta qualche secondo dopo tunnel quick: cloudflared deve registrarsi con l’edge. Controlla harbor logs cloudflared-quick.
• I link generati da Maho puntano a localhost dopo il tunnel. Hai dimenticato --autoconfig, oppure hai lanciato tunnel down senza il flag e i base URL sono rimasti sull’host pubblico.
• Il deploy su MageMEGA fallisce in fase di clone. Manca la deploy key sul repository, oppure il Repository URL usa https:// al posto della forma SSH.