Installazione, Deploy e Operazioni

1. Scopo del documento

Questo documento descrive come installare, pubblicare e mantenere operativa la piattaforma in modo professionale.

E' pensato per:

• clienti tecnici
• partner di deployment
• system integrator
• team di supporto

2. Modello di distribuzione

La piattaforma e' distribuita in modalita' self-hosted.

2.1 Struttura di deploy

• il pacchetto che ricevi per installare o aggiornare la piattaforma contiene due blocchi: il backend applicativo e la cartella pubblica del sito, chiamata web_root/ dentro il pacchetto
• la cartella pubblica reale del tuo server puo' chiamarsi public_html/, public/, htdocs/, www/ o altro: il nome non conta, conta solo che ci vada il contenuto giusto
• l'app mobile non fa parte di questo pacchetto: le build native (Android, iOS, PWA) si richiedono dalla pagina "Build Mobile" del pannello e vengono generate da un servizio centrale

2.2 Vantaggi

• maggiore sicurezza
• separazione tra core e parte pubblica
• compatibilita' con hosting tradizionali e VPS Linux

3. Flusso di installazione

L'installazione non richiede setup manuale frammentato, ma usa un wizard guidato.

3.1 Step installativi

1. verifica ambiente
2. configurazione database
3. creazione admin principale
4. attivazione licenza
5. connessione Shopify
6. import iniziale catalogo
7. registrazione webhook
8. branding e servizi
9. completamento

3.2 Cosa produce il wizard

• ambiente Laravel funzionante
• primo admin
• shop iniziale
• collegamento Shopify
• catalogo locale
• webhook registrati
• branding pubblico pronto per app e backoffice

4. Requisiti infrastrutturali

I requisiti precisi possono dipendere dalla configurazione finale, ma l'architettura attuale presuppone un ambiente compatibile con:

• PHP moderno compatibile con Laravel 12
• database SQLite o MySQL/MariaDB a seconda dello scenario
• filesystem scrivibile per storage pubblico
• HTTPS disponibile
• accesso outbound verso Shopify e OneSignal

5. Configurazioni fondamentali

5.1 Database

Il wizard supporta il setup del database e salva i parametri necessari al runtime applicativo.

5.2 Shopify

Per il corretto funzionamento servono:

• dominio Shopify
• client_id
• client_secret
• token Storefront se richiesto dal flusso commerce

5.3 OneSignal

Per le notifiche push servono:

• OneSignal app id
• chiave privata corretta della singola app

5.4 Branding

Configurazioni lato backoffice:

• nome app
• logo
• palette
• supporto
• privacy policy
• terms URL

6. Storage e media

Il prodotto utilizza storage pubblico per:

• logo
• slide home
• immagini push caricate
• immagini custom categorie

6.1 Requisiti pratici

• il disco pubblico deve essere scrivibile
• gli URL media devono essere correttamente esposti
• il collegamento storage pubblico deve essere funzionante

7. Deploy backend

7.1 Principio corretto

Non bisogna esporre l'intera applicazione Laravel come document root. La root pubblica deve servire solo la parte pubblica.

7.2 Modello usato nel progetto

• il core e' in backend/
• la parte esposta dal dominio e' la document root reale del server
• il pacchetto di aggiornamento la chiama web_root/, qualunque sia il nome reale sul tuo server (public_html/, public/, htdocs/, www/ o altro)

7.3 Beneficio

Questo approccio e' molto piu' adatto a un prodotto commerciale distribuibile.

7.4 Come aggiornare un'installazione

Ci sono due modi, entrambi supportati:

• automatico (consigliato): dal pannello admin, sezione Aggiornamenti in Dashboard, pulsante "Aggiorna piattaforma". Scarica il pacchetto, fa un backup, applica le modifiche e riattiva il sito da solo. Non serve accesso FTP/SSH
• manuale: utile se preferisci controllare tu ogni passaggio, o se l'aggiornamento automatico non e' disponibile sul tuo hosting

7.5 Aggiornamento manuale: dove vanno i file

Il pacchetto di aggiornamento contiene sempre due cartelle:

• backend/ -> va copiata nella cartella non pubblica dove gia' risiede il backend dell'installazione (per esempio /home/sito/app/backend)
• web_root/ -> il suo contenuto va copiato nella document root reale del dominio (per esempio /home/sito/public_html)

Esempio pratico:

• backend/ del pacchetto -> /var/www/negozio/backend
• web_root/ del pacchetto -> /var/www/negozio/public

7.6 Cosa non sovrascrivere mai durante un aggiornamento manuale

• .env
• il database (file SQLite oppure la connessione al database del cliente)
• storage/app/ e storage/logs/
• eventuali upload pubblici e asset generati localmente
• chiavi, segreti e configurazioni white-label del cliente

7.7 Flusso dell'aggiornamento manuale

1. scaricare il pacchetto dalla pagina Aggiornamenti
2. estrarre lo zip in una cartella temporanea
3. copiare backend/ sopra la cartella backend reale, senza toccare i file dell'elenco al punto 7.6
4. copiare il contenuto di web_root/ nella document root reale
5. eseguire le migration del database e pulire la cache dell'applicazione
6. verificare che il sito risponda correttamente

7.8 Nota sull'app mobile

L'app mobile non fa parte del pacchetto di aggiornamento del sito: si aggiorna in modo indipendente. Per pubblicare una nuova versione dell'app sugli store, vai sulla pagina "Build Mobile" del pannello e avvia una nuova build: non serve nessuna operazione manuale sul server.

8. Deploy mobile

La mobile app puo' essere compilata per:

• Android
• iOS

8.1 Parametri chiave

• nome visualizzato dell'app
• icona
• splash
• URL base API
• configurazione OneSignal

8.2 Nota operativa

Bundle id (Android) e bundle identifier (iOS) sono configurati come elementi white-label: puoi personalizzarli senza intervenire sul codice.

9. Operativita' quotidiana del merchant

Dal backoffice il merchant puo' gia' gestire:

• accessi admin
• profilo admin
• slide promozionali
• categorie visibili
• immagini categorie
• branding app
• notifiche push manuali
• collegamento Shopify

10. Operativita' catalogo

La vita del catalogo segue questa logica:

1. Shopify resta master
2. Laravel mantiene cache/catalogo locale
3. webhook e sync manuali mantengono allineato il sistema

10.1 Quando usare il sync manuale

E' utile in caso di:

• riallineamento iniziale
• problemi temporanei webhook
• variazioni massive di categoria

11. Operativita' notifiche push

11.1 Notifiche manuali

L'admin puo' inviare:

• titolo
• messaggio
• immagine opzionale
• prodotto opzionale per deep link

11.2 Notifiche automatiche ordini

Il sistema invia push in base agli eventi Shopify:

• ordine creato
• ordine pagato
• ordine annullato

11.3 Requisito funzionale

Perche' la push ordine arrivi al destinatario corretto, il device deve essere associato all'email del cliente.

12. Sicurezza operativa

12.1 Misure gia' adottate

• token sensibili cifrati nel database
• HMAC Shopify validato
• sessioni cliente hashate
• separazione root pubblica e core applicativo
• protezioni sulla gestione admin

12.2 Buone pratiche consigliate

• usare solo HTTPS
• ruotare periodicamente i segreti
• limitare l'accesso al backoffice
• mantenere backup regolari
• testare le notifiche dopo cambi credenziali

13. Backup e continuita' operativa

Per un prodotto commerciale sono consigliati backup regolari di:

• database
• storage pubblico
• file di configurazione necessari al runtime

13.1 Motivo

Il catalogo puo' essere reimportato da Shopify, ma:

• branding
• slide
• immagini custom
• impostazioni
• cronologia locale

sono asset applicativi da proteggere.

14. Health check consigliati

Un controllo operativo sano dovrebbe verificare regolarmente:

• accesso backoffice
• stato installazione
• validita' connessione Shopify
• disponibilita' Storefront token
• invio push di test
• accessibilita' storage pubblico

15. Test e verifiche

La codebase include test backend e verifiche tecniche utili per ridurre regressioni.

15.1 Verifiche consigliate dopo modifiche critiche

• test backend Laravel
• verifica webhook
• test invio push
• test login cliente
• test checkout reale
• test visualizzazione media pubblici

15.2 Verifiche consigliate prima della consegna cliente

• wizard installazione completo
• login admin
• configurazione branding
• import Shopify
• categorie in app
• login cliente
• lista ordini
• push manuale
• push ordine automatico
• checkout reale

16. Troubleshooting operativo

16.1 Le immagini non si vedono

Controllare:

• storage pubblico
• URL media
• permessi filesystem

16.2 Le push non partono

Controllare:

• OneSignal app id
• chiave privata corretta
• device registrati
• opt-in notifiche

16.3 Il catalogo non riflette Shopify

Controllare:

• import iniziale
• webhook registrati
• HMAC valido
• sync manuale dal backoffice

16.4 Il cliente non vede gli ordini

Controllare:

• login cliente funzionante
• sessione valida
• token Storefront corretto
• customer account abilitato correttamente lato Shopify

16.5 Il checkout fallisce

Controllare:

• Storefront token
• pubblicazione prodotto/varianti sul canale corretto
• esistenza locale della variante

17. Evoluzioni operative consigliate

Per aumentare ancora il valore commerciale del prodotto, i passi piu' utili sono:

• guida upgrade versionata
• checklist pre-release formale
• audit log backoffice
• monitor webhook con retry manuale
• ruoli admin avanzati
• dashboard tecnica di salute sistema

18. Conclusione

La piattaforma e' gia' strutturata per essere installata, configurata e gestita come un prodotto reale. Il modello scelto punta a un equilibrio molto forte tra:

• semplicita' di distribuzione
• controllo da backoffice
• potenza di Shopify
• esperienza mobile premium