IllusionCMS
IT
Manuale · 16

Funzionamento

Opzioni di avvio

Opzione Variabile d’ambiente Predefinito
-addr IC_ADDR :8080 Indirizzo e porta
-data IC_DATA ./data Cartella dati
-cache-mb IC_CACHE_MB 128 Cache delle pagine in MB, 0 = disattivata
-secure-cookies IC_SECURE_COOKIES=1 disattivato Cookie di sessione solo tramite HTTPS – dietro HTTPS attivalo assolutamente
-rate-limit IC_RATE_LIMIT 120 Richieste API al minuto per IP senza accesso (con token/sessione il decuplo), 0 = disattivato – vedi documentazione API
-headless IC_HEADLESS=1 disattivato Senza app admin, accesso e sessioni, in modo forzato – vedi Server headless
– IC_MASTER_TOKEN – Token con permesso di scrittura senza account utente (almeno 32 caratteri) – vedi Server headless
– IC_SETUP_TOKEN – Opzionale: segreto richiesto per la prima configurazione (primo account admin) – protegge un’istanza appena pubblicata e ancora vuota da un estraneo che arrivi per primo. Richiesto nel modulo di configurazione
-media-cache-mb IC_MEDIA_CACHE_MB 512 Cache su disco per i media su S3 in MB, 0 = disattivata – vedi Salvare i media su S3
– IC_ENCRYPTION_KEY – Chiave per le credenziali cifrate nelle impostazioni (almeno 32 caratteri); senza, IllusionCMS crea data/secret.key – vedi Salvare i media su S3

Le variabili d’ambiente per le sorgenti REST ({env.NAME}) le imposti all’avvio. Le variabili con prefisso IC_ (configurazione del CMS, ad es. IC_MASTER_TOKEN) non sono mai leggibili qui. I Workflow non hanno accesso alle variabili d’ambiente.

Inoltre: -version stampa la versione, -create-token "Name" crea un token API con permesso di scrittura, lo stampa e termina, -enable-admin riattiva un admin disattivato nelle impostazioni, -healthcheck interroga /healthz del server in esecuzione e termina con codice di uscita 0 o 1 – pensato per l’HEALTHCHECK di un container Docker.

Docker e Coolify: file Compose pronti (standalone dietro un reverse proxy come Apache, e per Coolify) si trovano in ogni release come illusioncms-vX.Y.Z-deploy.zip (con i binari Linux, istruzioni nel README.md incluso) e nel repository di deployment IllusionCMS-Deployment. Importante dietro un proxy: il proxy deve inoltrare l’header Host (con Apache ProxyPreserveHost On) – altrimenti IllusionCMS non può associare il sito al dominio – e impostare X-Forwarded-Proto, così sitemap e robots.txt usano https://.

Cartella dati e backup

data/
  illusion.db        database (pagine, snippet, CSS/JS, Collections, impostazioni …)
  illusion.db-wal    log di scrittura del database (ne fa parte!)
  media/2026/10/…    file caricati e importati
  backups/           backup automatici: notturni senza media (gli ultimi 7)
                     e prima dell’importazione di un bundle con i media (gli ultimi 3)
  cache/media/       cache su disco per i media da S3 (solo con S3)
  secret.key         chiave per le credenziali cifrate (senza IC_ENCRYPTION_KEY)

Backup automatici: ogni notte dalle 3 (ora del server) IllusionCMS salva l’intero contenuto – pagine, CSS/JS, snippet, Collections, impostazioni dei file … – senza i file multimediali stessi, ma solo se dall’ultimo backup notturno è cambiato qualcosa. Restano gli ultimi 7. Ripristino: in Impostazioni → Sincronizzazione scarica il backup e reimportalo; la cartella dei media resta invariata. Se anche le voci delle Collections con Dati live devono tornare allo stato del backup, durante l’importazione spunta Riprendi dal bundle anche le voci delle Collections con dati live. I file multimediali conviene salvarli in aggiunta insieme alla cartella dati (cambiano raramente e vengono eliminati solo se li elimini esplicitamente).

Backup: il modo più sicuro è fermare brevemente il server e copiare l’intera cartella. Con il server in funzione: sqlite3 data/illusion.db ".backup backup.db" più una copia di media/ – oppure semplicemente scaricare un bundle (contiene tutto il contenuto, ma non account e token).

Salvare i media su S3

Per impostazione predefinita i file caricati e importati si trovano in data/media. In alternativa IllusionCMS li salva in uno storage compatibile S3 – comodo se il server ha poco spazio o se i file devono essere salvati separatamente dal server. Gli indirizzi non cambiano: i file restano raggiungibili sotto /media/…, IllusionCMS li prende da sé dal bucket (anche a intervalli per video e download riprendibili). Il bucket resta privato, non deve essere leggibile pubblicamente.

Dove: Impostazioni → Archiviazione (in modalità remota per il server collegato). In alto vedi lo storage attivo, numero e dimensione dei file e l’occupazione della cache su disco.

Campi:

  • Endpoint – indirizzo del servizio S3, ad es. https://s3.eu-central-1.amazonaws.com.
  • Regione – ad es. eu-central-1; con Garage di solito garage, con Cloudflare R2 auto. Vuoto = us-east-1.
  • Bucket – deve già esistere. Prefisso (facoltativo) – ad es. cms/ se più applicazioni condividono un bucket.
  • Chiave di accesso e chiave segreta – la chiave deve poter leggere, scrivere, eliminare ed elencare. Il secret non viene più mostrato; se in seguito lasci vuoto il campo, resta quello salvato.
  • Path style – indirizzamento endpoint/bucket/file invece di bucket.endpoint/file. Necessario per Garage ed endpoint con indirizzo IP.
Fornitore Endpoint Regione Path style
Garage (self-hosted) http://127.0.0.1:3900 o il tuo indirizzo Garage garage attivo
Hetzner Object Storage https://fsn1.your-objectstorage.com (o nbg1, hel1) fsn1 disattivo
Cloudflare R2 https://<account-id>.r2.cloudflarestorage.com auto attivo
AWS S3 https://s3.eu-central-1.amazonaws.com eu-central-1 disattivo

Testa connessione scrive, legge ed elimina un piccolo oggetto di prova nel bucket e indica chiaramente cosa manca (indirizzo non raggiungibile, chiave sconosciuta, secret errato, bucket mancante, permessi mancanti). Salva memorizza i dati – finché è attivo lo storage locale, solo come bozza.

Trasloco: Passa a S3 … avvia una migrazione guidata in background: tutti i file vengono copiati (ciò che esiste già nella destinazione con la stessa dimensione viene saltato – un trasloco interrotto riprende quindi da lì), poi ogni copia viene verificata, e solo allora IllusionCMS cambia storage e svuota la cache delle pagine. Nel frattempo puoi continuare a lavorare: caricamenti ed eliminazioni finiscono prima nel vecchio storage, vengono registrati e ripresi al passaggio – le scritture si fermano solo per quel breve momento. Con Annulla o in caso di errore resta attivo il vecchio storage. Se Elimina poi i vecchi file è spuntato, IllusionCMS ripulisce il vecchio storage dopo un passaggio riuscito; altrimenti resta come riserva. Torna allo storage locale … funziona allo stesso modo nell’altra direzione. Bucket e prefisso di uno storage S3 attivo si cambiano solo con una migrazione; nuove credenziali per lo stesso bucket valgono subito dopo un test riuscito.

Cache su disco: davanti a S3 c’è una cache locale in data/cache/media (512 MB predefiniti, opzione di avvio -media-cache-mb o IC_MEDIA_CACHE_MB, per istanza anche nelle impostazioni di archiviazione). Velocizza soprattutto le varianti delle immagini e il WebP e continua a consegnare i file in cache se S3 è brevemente irraggiungibile. Un bucket può essere usato da una sola istanza IllusionCMS (la cache presuppone che tutte le modifiche passino da lei) – per una seconda istanza usa un bucket o un prefisso diverso.

Credenziali cifrate: il secret è salvato nel database solo in forma cifrata (AES-256-GCM). La chiave viene dalla variabile d’ambiente IC_ENCRYPTION_KEY (almeno 32 caratteri, ad es. openssl rand -hex 32); se non è impostata, IllusionCMS crea al primo bisogno il file data/secret.key (leggibile solo dal proprietario). Porta con te la chiave quando trasferisci il server – copia anche data/secret.key o imposta la stessa IC_ENCRYPTION_KEY. Se la chiave manca o è diversa, il secret non si può più decifrare: IllusionCMS si avvia allora con i file locali e mostra l’errore nelle impostazioni di archiviazione – inserisci di nuovo il secret e salva, poi S3 torna attivo. I bundle di proposito non contengono l’impostazione di archiviazione.

Cosa è cifrato e cosa no: nel database sono cifrati con la stessa chiave: il secret S3, i secret dei webhook, la password SMTP, i token IllusionDB e i token delle connessioni; i vecchi valori in chiaro restano leggibili e vengono cifrati al salvataggio successivo. I secret salvati (password SMTP, token IllusionDB, secret S3, token di connessione) vengono riutilizzati solo per lo stesso obiettivo – se cambiano host, indirizzo, endpoint o bucket, vanno reinseriti. Non sono cifrati gli header delle sorgenti REST (Authorization …): fanno parte dei contenuti e compaiono quindi in bundle, backup notturni e nel caricamento su un’altra istanza – solo così un’istanza si ripristina completamente. Tratta bundle e backup come credenziali (la cartella data/backups e la cache media sono leggibili solo dall’utente del server); le credenziali per le sorgenti possono anche provenire da variabili d’ambiente ({env.SHOP_TOKEN}) e non sono allora salvate da nessuna parte nel database.

Backup: anche con S3 il database resta in locale in data/illusion.db (come i backup notturni). Per salvarlo di continuo nello stesso bucket è adatto Litestream – un programma separato accanto a IllusionCMS che replica continuamente il database SQLite. Esempio di litestream.yml (un esempio Docker Compose completo si trova nel README.md del pacchetto di deployment):

dbs:
  - path: /data/illusion.db
    replicas:
      - type: s3
        endpoint: https://fsn1.your-objectstorage.com
        bucket: firma-media
        path: litestream/illusion.db
        access-key-id: ${LITESTREAM_ACCESS_KEY_ID}
        secret-access-key: ${LITESTREAM_SECRET_ACCESS_KEY}

Ripristino, a server fermo, con litestream restore -config litestream.yml /data/illusion.db. Il fornitore S3 non salva automaticamente i file media – attiva se possibile il versioning o la replica del bucket presso il fornitore.

Costruire in locale, pubblicare online (bundle)

Puoi costruire un sito in locale e poi portarlo interamente sul tuo server online. Un bundle è un file con estensione .icb (bundle IllusionCMS, tecnicamente uno ZIP) con l’intero contenuto dell’istanza: siti web, pagine, CSS/JS, snippet, file, Collections, sorgenti REST e reindirizzamenti. Account e token API non ne fanno parte – sul server continui ad accedere con il tuo account di lì.

Tutto il necessario si trova in Impostazioni → Sincronizzazione:

  • Scarica – il bundle come file .icb.
  • Carica e importa – sul server online: seleziona il file .icb, Importa e sostituisci. Bundle e backup di versioni precedenti (.zip) si possono ancora importare.
  • Sincronizza con un server – dall’admin locale in un solo passo, tramite una connessione salvata: Carica sostituisce il contenuto del server con quello locale, Scarica porta qui lo stato del server con i dati live (ad es. su un nuovo computer o dopo una correzione d’emergenza online). L’avanzamento viene mostrato. Se sul lato che viene sostituito è cambiato qualcosa dall’ultima sincronizzazione, il CMS avvisa prima – i dati live non contano come modifica.

Da sapere:

  • L’importazione sostituisce l’intero contenuto della destinazione – ciò che è stato modificato solo online va perso. Prima il server salva automaticamente il suo stato precedente (gli ultimi 3 backup sono disponibili per il download nella stessa vista; ripristinare = importare il backup).
  • I dati live restano: le voci delle Collections con la spunta Dati live (ad es. richieste di contatto) restano sempre sulla destinazione – anche quelle che arrivano mentre lavori in locale. Le voci locali di queste Collections non vengono trasferite. Nel verso opposto (importare in locale un bundle dal server live, ripristinare un backup) le riprendi con la spunta Riprendi dal bundle anche le voci delle Collections con dati live.
  • Mantenere i contenuti gestiti online: con Mantieni tutte le voci di Collections del server restano le voci del server (ad es. articoli del blog scritti online) – layout, pagine e codice arrivano comunque dalla versione locale. L’abbinamento avviene tramite lo slug della Collection.
  • Domini: in locale il tuo sito di solito non ha un dominio. In quel caso il sito sul server mantiene i domini inseriti. Se inserisci domini in locale, vengono ripresi.
  • I file invariati non vengono riscritti – i trasferimenti ripetuti sono più veloci. Viene comunque caricato l’intero bundle.
  • Entrambe le istanze dovrebbero avere la stessa versione di IllusionCMS; un server più vecchio rifiuta i bundle di una versione più recente.
  • Se il server gira dietro nginx, client_max_body_size deve essere abbastanza grande per il bundle (Caddy: nessun limite).
  • Automatizzabile: curl -H "Authorization: Bearer <token>" -H "Content-Type: application/zip" --data-binary @bundle.icb https://www.firma.de/api/v1/bundle (vedi API).

Più istanze: lavorare in diretta o sincronizzare

In Impostazioni → Connessioni inserisci altre istanze di IllusionCMS – nome, indirizzo e un token API con permesso di scrittura di quell’istanza (sul server in Impostazioni → Token API, per un server senza admin il master token o tramite -create-token). Il token resta nel database locale, non viene mostrato e non fa parte del bundle. Verifica mostra se il server è raggiungibile, quale versione vi gira e se funziona in modalità headless. Che sul server stesso giri l’admin non importa – serve solo il token. Così gestisci quante istanze vuoi da un’unica app locale; headless è un’opzione aggiuntiva per i server che gestisci esclusivamente in questo modo.

Con una connessione ci sono due modi di lavorare – puoi combinarli:

  • Lavorare in diretta: in alto nel menu è indicato con quale istanza sta lavorando l’admin (Locale). Se lì scegli una connessione, tutte le viste – pagine, file, Collections, statistiche, Workflows, registro 404 … – vanno direttamente a quel server; le modifiche hanno effetto immediato. Il menu mostra allora il nome della connessione con LIVE. Così gestisci più siti su server diversi da un’unica app locale, e vedi i dati live come le richieste di contatto senza deviazioni. In locale restano solo account, token API e le connessioni stesse. Anteprima delle pagine, Pens e indirizzi dei Workflows puntano al server.
  • Costruire in locale e sincronizzare: prova in locale senza che i visitatori vedano nulla, poi carica in Impostazioni → Sincronizzazione (vedi sopra). I dati live sul server restano invariati.

Versioni: l’app admin arriva sempre dalla tua istanza locale. Al cambio di istanza (e a ogni caricamento) verifica se il server ha la stessa versione di IllusionCMS. Se è diversa o il server non è raggiungibile, il selettore diventa rosso invece che giallo e un avviso indica entrambe le versioni; nel menu di selezione, accanto a ogni connessione compaiono la sua versione ed eventualmente un ⚠. Si può comunque lavorare, ma alcune funzioni possono mancare o non riuscire – è meglio aggiornare le due istanze insieme.

Per le correzioni rapide è adatta la modalità live, per le ristrutturazioni più grandi (nuovo layout, molte modifiche CSS) l’istanza locale – le bozze esistono solo per le pagine, un file CSS o uno snippet modificato ha effetto ovunque e subito sul server live.

Server headless (senza admin)

Chi gestisce il proprio server live solo dall’app locale non ha bisogno lì dell’admin. Senza admin il server serve il sito, l’API per i token, gli ingressi HTTP dei Workflows e i Pens pubblici – ma niente /cms-admin, nessun accesso, nessuna sessione e nessuna gestione di account o token (tutto 404). Questo riduce la superficie d’attacco: non c’è nessuna pagina di login che qualcuno possa provare a forzare.

Il modo più semplice – senza alcun account utente: all’avvio imposta un master token e disattiva l’admin:

IC_MASTER_TOKEN=$(openssl rand -hex 32)   # annotalo – è il token per la connessione
IC_HEADLESS=1

Il master token vale come un token API con permesso di scrittura, ma non sta in nessun database e non richiede un account (almeno 32 caratteri, altrimenti il server non si avvia). In locale lo inserisci in Impostazioni → Connessioni. Nella cronologia compare come autore Master-Token. Account e token non li gestisce – questo resta riservato all’admin. Viene bloccato non appena rimuovi la variabile e riavvii.

Disattivare l’admin con l’interruttore: invece di IC_HEADLESS=1 puoi anche usare Impostazioni → Sistema → Disattiva admin – nell’admin del server stesso o, più comodamente, dalla tua app locale in modalità remota. Funziona solo se esiste un token con permesso di scrittura (o è impostato un master token), così non ti chiudi fuori. Per riattivarlo: in modalità remota in Impostazioni → Sistema, tramite API (PUT /api/v1/system) o sul server con illusioncms -enable-admin. Via d’uscita d’emergenza, se non si conosce più nessun token: imposta IC_MASTER_TOKEN, riavvia, connettiti con esso e attiva l’admin. Con IC_HEADLESS=1 invece l’admin è disattivato in modo fisso e l’interruttore è bloccato.

Invece di un master token va bene anche un normale token API: crealo sul server in Impostazioni → Token API finché l’admin è ancora attivo, oppure da riga di comando – nel container Docker ad es. docker exec <container> illusioncms -data /data -create-token "Lokales Admin".

Esportare come sito statico

Un sito si può esportare interamente come pagine HTML statiche – per un semplice spazio web con Apache, senza che lì debba girare IllusionCMS. Nell’editor della home page in Impostazioni → Sito → Esporta come sito statico:

  1. Verifica esportazione – renderizza tutte le pagine e mostra un rapporto: numero di pagine, file e dimensione, pagine con errori di template, link interni che non portano da nessuna parte e file mancanti.
  2. Scarica ZIP ed estrai il contenuto nella directory principale del dominio (ad es. htdocs/ o public_html/).

Cosa contiene:

  • Ogni pagina come pfad/index.html – /leistungen diventa leistungen/index.html. Apache reindirizza automaticamente /leistungen a /leistungen/.
  • Le pagine di dettaglio dietro le pagine Catch-All (singoli articoli del blog) sono incluse se compaiono nella sitemap (Collections o sorgente della sitemap, ad es. IllusionDB) o se sono collegate da qualche parte – ad es. dalla panoramica del blog.
  • robots.txt come nel CMS.
  • La pagina 404 come 404.html e un .htaccess che la include (ErrorDocument 404 /404.html) – con tutti i reindirizzamenti del sito.
  • Tutti i file CSS e JS, sitemap.xml (per il primo dominio del sito o l’URL di base indicato) e le immagini usate con le varianti srcset. Con Includi tutti i file della libreria media viene inclusa l’intera cartella dei media – necessario se il JavaScript compone da sé gli URL delle immagini.
  • I file privati mancano sempre – anche quando si includono tutti i file della gestione media – insieme alle loro varianti e versioni WebP; il rapporto ne indica il numero.

Limiti: tutto è un’istantanea al momento dell’esportazione – dati REST, Collections e modifiche successive richiedono una nuova esportazione. Le pagine con parametri di query (?seite=2) staticamente non esistono, e nemmeno le chiamate /api/v1 da JavaScript. L’esportazione va nella directory principale del dominio, non in una sottocartella (i link iniziano con /).

Controllo dello stato

GET /healthz risponde senza accesso con 200 e {"status":"ok", …} finché il database è raggiungibile, altrimenti con 503. Adatto al monitoraggio dell’uptime, all’HEALTHCHECK di Docker o ai load balancer. La risposta contiene inoltre l’identificativo di build dell’app admin e il commit Git del binario – utile per verificare se un aggiornamento è davvero in funzione.

Dietro un reverse proxy (HTTPS)

IllusionCMS di per sé parla solo HTTP. Per HTTPS metti davanti un proxy, ad es. Caddy (ottiene i certificati automaticamente):

www.firma.de, shop.firma.de {
    reverse_proxy 127.0.0.1:8080
}
firma.de {
    redir https://www.firma.de{uri}
}

Con più siti web inserisci tutti i domini nel proxy; IllusionCMS sceglie il sito in base al dominio richiesto (header Host, che Caddy inoltra invariato).

Avvia poi il server con -addr 127.0.0.1:8080 -secure-cookies. La sitemap riprende dominio e schema da X-Forwarded-Host/X-Forwarded-Proto, che Caddy imposta automaticamente.

Gli header di protezione come HSTS IllusionCMS può inviarli da sé (Header di sicurezza). Il reindirizzamento da http:// a https:// dovrebbe farlo il proxy in modo permanente (301 o 308, predefinito in Caddy). Con Traefik serve a questo scopo permanent: true sul middleware di redirect, altrimenti reindirizza con 302. Per Coolify ci sono istruzioni nel pacchetto di deployment (README.md, sezione Coolify).

IllusionCMS comprime da sé pagine HTML, CSS/JS e la sitemap (gzip). Una compressione nel proxy non è quindi necessaria. Meglio disattivarla lì, altrimenti anche le immagini vengono compresse di nuovo inutilmente.

Come servizio (systemd)

[Unit]
Description=IllusionCMS
After=network.target

[Service]
ExecStart=/opt/illusioncms/illusioncms -addr 127.0.0.1:8080 -data /var/lib/illusioncms -secure-cookies
Environment=SHOP_TOKEN=…
Restart=on-failure
User=illusioncms

[Install]
WantedBy=multi-user.target