Usa il tuo storage + CDN

Disponibile con: i piani API Velocity e Momentum. Non disponibile con Ignite (non include una CDN), nella sandbox per sviluppatori (i file della sandbox sono temporanei) né con i piani WordPress (usano la CDN gestita di smallPict).

In breve: in modalità BYO, smallPict scrive i tuoi originali e le immagini ottimizzate nel tuo bucket, e la tua CDN li distribuisce. Storage e CDN sono sempre collegati insieme: non puoi portare l’uno senza l’altra.

Che cos’è BYO

Velocity e Momentum offrono due modalità di distribuzione. Ne scegli una in Dashboard → CDN e storage.

• Gestita (predefinita): smallPict conserva i tuoi originali nel proprio storage crittografato (spostati in un archivio a lungo termine dopo 90 giorni) e distribuisce le immagini ottimizzate da cdn.smallpict.app. Nessuna configurazione necessaria.
• Usa il tuo storage + CDN (BYO): colleghi un bucket compatibile con S3 nel tuo account e una CDN nel tuo account. Ogni nuovo job scrive l’originale e il file ottimizzato nel tuo bucket, e l’API restituisce URL sul dominio della tua CDN.

Il vincolo esiste perché smallPict deve poter gestire entrambe le metà della distribuzione: scrivere i file ed eliminare dalla cache le copie obsolete. Un bucket senza CDN lascerebbe le purghe della cache senza destinazione; una CDN senza bucket non avrebbe nulla da distribuire.

Gestita vs. BYO

Provider supportati

Storage (disponibili oggi): Amazon S3, Cloudflare R2, Google Cloud Storage (interoperabilità S3), Alibaba Cloud OSS, Tencent Cloud COS, DigitalOcean Spaces, SumoPod Storage, MinIO e qualsiasi altro servizio compatibile con S3 tramite un endpoint personalizzato (ad esempio Hetzner, Vultr o Wasabi).

CDN (disponibili oggi): Cloudflare e Amazon CloudFront.

Previsti: Azure Blob Storage e altre CDN. Puoi richiedere l’accesso anticipato nella pagina Provider cloud.

Prima di iniziare

1. Hai un piano API Velocity o Momentum e hai effettuato l’accesso come amministratore dell’account.
2. Hai un bucket e una CDN che distribuisce i file di quel bucket tramite HTTPS.
3. L’endpoint dello storage è raggiungibile da Internet tramite HTTPS. Gli endpoint privati, interni e in HTTP semplice vengono rifiutati.
4. Hai creato chiavi con permessi limitati per smallPict (vedi Permessi minimi più avanti). Non usare le chiavi root o di amministratore del tuo account.

Poi apri Dashboard → CDN e storage, scegli Usa il tuo storage + CDN, compila entrambe le parti e seleziona Salva storage + CDN. smallPict esegue la verifica della connessione (descritta più avanti) e passa alla modalità BYO solo se la verifica viene superata.

Guide alla configurazione

A. Amazon S3 + Amazon CloudFront

1. Crea il bucket nella regione che preferisci, ad esempio my-images in ap-southeast-1. Lascia attivo Block Public Access.
2. Crea una distribuzione CloudFront con il bucket come origine. Usa Origin access control (OAC) in modo che CloudFront possa leggere il bucket mentre resta privato, e applica la bucket policy che CloudFront ti propone.
3. Facoltativo: il tuo dominio. Aggiungi un nome di dominio alternativo (ad esempio images.example.com) e un certificato alla distribuzione, e fai puntare un record DNS alla distribuzione.
4. Crea un utente IAM (o un ruolo) per lo storage con questa policy:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "s3:PutObject",        "s3:GetObject",        "s3:DeleteObject"      ],      "Resource": "arn:aws:s3:::my-images/*"    }  ]}

5. Crea un utente IAM per CloudFront (può essere lo stesso utente) con questa policy. cloudfront:GetDistribution è facoltativo; con questo permesso, smallPict può rilevare il dominio della distribuzione quando lasci vuoto il dominio CDN.

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "cloudfront:CreateInvalidation",        "cloudfront:GetDistribution"      ],      "Resource": "arn:aws:cloudfront::123456789012:distribution/E2QWRUHAPOMQZL"    }  ]}

6. Nella dashboard:
   • Provider di storage Amazon S3, bucket my-images, regione ap-southeast-1, endpoint vuoto (viene usato l’endpoint standard della regione), più l’access key ID e il secret dello storage.
   • CDN Amazon CloudFront, il Distribution ID (ad esempio E2QWRUHAPOMQZL), l’access key ID e il secret di CloudFront e, facoltativamente, il dominio CDN (https://images.example.com). Lascia vuoto il dominio per usare il dominio *.cloudfront.net della distribuzione.

B. Cloudflare R2 + Cloudflare

1. Crea un bucket R2, ad esempio my-images.
2. Collega un dominio personalizzato al bucket (R2 → il tuo bucket → Settings → Custom Domains), ad esempio images.example.com, su una zona dello stesso account Cloudflare. Le richieste a quel dominio passano dalla cache di Cloudflare. Non usare l’URL di sviluppo r2.dev in produzione.
3. Crea un token API R2 (R2 → Manage API tokens) con Object Read & Write, limitato solo a questo bucket. Copia l’Access Key ID e la Secret Access Key mostrati.
4. Crea un token API Cloudflare (My Profile → API Tokens) per la zona con Zone → Cache Purge → Purge. Zone → Zone → Read è facoltativo.
5. Nella dashboard:
   • Provider di storage Cloudflare R2, bucket my-images, endpoint https://<account_id>.r2.cloudflarestorage.com (indicato nei dettagli S3 API del bucket), regione auto, più l’Access Key ID e la Secret Access Key di R2.
   • CDN Cloudflare, lo Zone ID (pagina Overview del dominio, sezione API), il token API e il dominio CDN https://images.example.com.

C. Google Cloud Storage + Cloudflare

Google Cloud Storage si collega tramite la sua XML API compatibile con S3, con chiavi HMAC.

1. Crea il bucket, ad esempio my-images.
2. Crea un service account e assegnagli il ruolo Storage Object User (roles/storage.objectUser) solo su questo bucket.
3. Crea una chiave HMAC per il service account: Cloud Storage → Settings → Interoperability → Create a key for a service account. Copia l’access ID e il secret.
4. Rendi i file ottimizzati leggibili dalla tua CDN. Cloudflare recupera i file da Cloud Storage tramite HTTPS, quindi gli oggetti sotto optimized/ devono essere leggibili pubblicamente. Con l’uniform bucket-level access, concedere a allUsers il ruolo Storage Object Viewer rende leggibile l’intero bucket, originals/ compreso. Se i tuoi originali devono restare privati, metti davanti un livello di autenticazione (ad esempio un Cloudflare Worker che firma le richieste al bucket).
5. Fai puntare un record DNS Cloudflare con proxy a Cloud Storage, ad esempio images.example.com. Puoi dare al bucket il nome dell’hostname e usare un CNAME con proxy verso c.storage.googleapis.com, oppure usare una Cloudflare Origin Rule che invia le richieste a storage.googleapis.com con il nome del bucket all’inizio del percorso.
6. Crea un token API Cloudflare per la zona con Zone → Cache Purge → Purge (Zone → Zone → Read facoltativo).
7. Nella dashboard: provider di storage Google Cloud Storage, bucket, endpoint https://storage.googleapis.com, regione auto, l’access ID e il secret HMAC; CDN Cloudflare, Zone ID, token API e dominio CDN https://images.example.com.

D. MinIO o qualsiasi storage compatibile con S3 + Cloudflare

Questa sezione riguarda MinIO e i servizi compatibili con S3 come Hetzner, Wasabi, Vultr, SumoPod, Alibaba Cloud OSS, Tencent Cloud COS e DigitalOcean Spaces.

1. Crea il bucket e una chiave limitata a quel bucket con put, get e delete sugli oggetti (vedi Permessi minimi più avanti).
2. Rendi optimized/ leggibile dalla tua CDN, ad esempio con una bucket policy che consenta s3:GetObject anonimo solo su optimized/*. Su MinIO:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "AWS": [          "*"        ]      },      "Action": [        "s3:GetObject"      ],      "Resource": [        "arn:aws:s3:::my-images/optimized/*"      ]    }  ]}

3. Metti Cloudflare davanti al bucket: un record DNS con proxy per images.example.com che punti all’host pubblico del bucket. Se il provider richiede il proprio hostname nella richiesta, aggiungi una Cloudflare Origin Rule che riscriva l’header Host (e, per gli host path-style, aggiunga il nome del bucket al percorso).
4. Crea un token API Cloudflare per la zona con Zone → Cache Purge → Purge (Zone → Zone → Read facoltativo).
5. Nella dashboard: scegli il provider dalla tabella, inserisci bucket, endpoint, regione (auto se il provider non ne ha una) e chiavi; attiva le richieste path-style dove la tabella lo indica; poi CDN Cloudflare, Zone ID, token API e dominio CDN.

Permessi minimi

Dai a smallPict chiavi che possano fare solo ciò che serve, su un solo bucket.

La verifica della connessione

Ogni volta che salvi (e quando selezioni Ripeti verifica), smallPict verifica l’intera connessione prima di usarla:

1. Storage: scrive un piccolo file di prova in .smallpict-probe/ nel tuo bucket, lo rilegge e lo elimina.
2. Cloudflare: invia alla tua zona una purga di prova per un singolo URL.
3. CloudFront: crea un’invalidazione di prova per un percorso /.smallpict-probe/.... Viene conteggiata nei percorsi di invalidazione CloudFront del mese.

Se un passaggio non riesce, non viene cambiato nulla. La dashboard mostra il motivo accanto al campo interessato, ad esempio il nome del bucket o il token API. La verifica della connessione è limitata a 5 tentativi al minuto.

Accesso al bucket per la tua CDN

• optimized/ deve essere leggibile dalla tua CDN: con lettura pubblica su quel prefisso oppure con l’accesso origine della CDN a un bucket privato (origin access control di CloudFront o un dominio personalizzato R2).
• originals/ può restare privato. La tua CDN non ne ha mai bisogno.
• CORS serve solo se i browser recuperano le immagini cross-origin da JavaScript (ad esempio fetch() o un canvas). I normali tag <img> non ne hanno bisogno. Se ti serve, consenti GET e HEAD dall’origine del tuo sito.

Struttura degli oggetti e URL

Il dominio CDN può includere un prefisso di percorso, ad esempio https://example.com/images; in tal caso l’URL diventa https://example.com/images/optimized/<job_id>.<ext>.

Header di cache

I file ottimizzati vengono scritti con Cache-Control: public, max-age=31536000, immutable. Ogni job riceve una chiave univoca, quindi un nuovo risultato ha sempre un nuovo URL e la purga serve raramente. Evita che le regole di caching della tua CDN sovrascrivano questo header con una durata più breve.

Purga della cache

• Le richieste di purga effettuate tramite l’API (POST /v1/purge) vanno alla tua CDN, raggruppate in batch.
• Su Cloudflare, i file vengono purgati per URL. "Purge all" purga solo il tuo host di distribuzione e il prefisso di percorso, non l’intera zona.
• Su CloudFront, i file vengono purgati con invalidazioni. "Purge all" crea un’invalidazione /*. I percorsi di invalidazione oltre la quota gratuita mensile di CloudFront vengono addebitati da AWS sul tuo account.

Cambiare modalità

Cambiare modalità non sposta i file esistenti. I file già distribuiti mantengono i loro URL attuali; solo i nuovi job usano la nuova modalità.

• Gestita → BYO: i nuovi job vanno nel tuo bucket e vengono distribuiti dalla tua CDN. I file già su cdn.smallpict.app restano lì.
• BYO → gestita: i nuovi job tornano a usare storage e CDN gestiti. Le impostazioni e le chiavi BYO restano salvate ma non in uso, così puoi tornare indietro senza reinserirle, finché non selezioni Disconnetti.
• Disconnetti: elimina le chiavi e le impostazioni BYO salvate e ti riporta alla modalità gestita. I file nel tuo bucket non vengono toccati.

Quando qualcosa non funziona

• Se smallPict non riesce a scrivere nel tuo bucket, riprova e poi fa fallire il job con un motivo che puoi leggere nella risposta dell’API.
• La dashboard mostra l’ultimo errore e quando si è verificato, con un pulsante Ripeti verifica.
• Ricevi un’email per incidente, non una per ogni job non riuscito.
• smallPict non ripiega mai sullo storage gestito. I tuoi file non vengono mai salvati in un luogo che non hai scelto.

Sicurezza

• Le chiavi sono conservate in un archivio di segreti crittografato. Non vengono mai più mostrate, non vengono mai restituite dall’API e non vengono mai scritte nei log.
• Per ruotare una chiave, inserisci quella nuova e salva; la verifica della connessione viene eseguita con la nuova chiave. Lascia vuoto un campo chiave per mantenere la chiave salvata.
• Gli endpoint di storage e CDN devono usare HTTPS. Gli endpoint che si risolvono in indirizzi privati, di loopback, link-local o comunque interni vengono rifiutati.
• Usa chiavi separate e con permessi limitati per smallPict, e revocale nella console del provider se smetti di usare BYO.