LiveContext self-hosted: requisiti, Docker e backup

Che cos'è LiveContext e quanto costa eseguirlo

Per eseguire LiveContext in modalità self-hosted serve un VPS con circa 8 GB di RAM. LiveContext CE è una piattaforma open source per l'automazione che esegue agenti AI all'interno dell'automazione stessa. Viene distribuita come stack Docker Compose composto da sei container e basato su un backend Java. Il README upstream indica 4 GB come requisito minimo e 8 GB come valore consigliato. Il file Compose mostra come viene utilizzata questa memoria.

Il progetto si trova su livecontext-ai/livecontext-ce in GitHub ed è distribuito con licenza AGPL-3.0. La release corrente ad agosto 2026 è v0.2.11, pubblicata il 3 agosto 2026. Tutte le immagini sono compilate soltanto per linux/amd64, quindi i piani Arm economici non sono compatibili. Questa guida fissa quel tag, pubblica lo stack dietro un reverse proxy e descrive la procedura di backup che manca nella documentazione upstream.

Dimensionare il VPS prima di installare LiveContext

Ogni servizio incluso nel file Compose fornito ha un limite di memoria esplicito, quindi puoi dimensionare il server prima di noleggiarlo. Questi sono i limiti definiti nel file Compose v0.2.11, non i consumi misurati.

[
  {
    "label": "livecontext (backend)",
    "memory_limit_mb": 1536
  },
  {
    "label": "bridge",
    "memory_limit_mb": 512
  },
  {
    "label": "redis",
    "memory_limit_mb": 384
  },
  {
    "label": "postgres",
    "memory_limit_mb": 256
  },
  {
    "label": "minio",
    "memory_limit_mb": 256
  },
  {
    "label": "websearch (optional)",
    "memory_limit_mb": 2048
  },
  {
    "label": "searxng (optional)",
    "memory_limit_mb": 512
  },
  {
    "label": "renderer (optional)",
    "memory_limit_mb": 1024
  }
]

Il backend ha un limite di 1536 MB. Il limite si applica a un processo Java 21, quindi la JVM utilizzerà gran parte della memoria disponibile e tenderà a mantenerla allocata. I cinque servizi di base raggiungono complessivamente poco meno di 3 GB, mentre il frontend non ha alcun limite e utilizza la memoria richiesta da Node. Su un VPS da 4 GB rimane quindi quasi nulla per il kernel e la page cache. Per questo 4 GB è indicato come requisito minimo, non come configurazione consigliata.

Sono i profili opzionali a portare il requisito a 8 GB. Il profilo browser agent aggiunge un container Chromium con un limite di 2048 MB e un'istanza di ricerca SearXNG. Il profilo renderer aggiunge altri 1024 MB per screenshot e PDF. Nessuno dei due profili viene avviato finché non lo abiliti, quindi lasciali disattivati fino a quando non sono necessari. Il container SearXNG serve come backend di ricerca dell'agent. Le pagine restituite vengono quindi inserite nei prompt come testo non attendibile. Questo è il confine di attendibilità attraverso cui funziona fornire a un AI agent la ricerca web di SearXNG in dettaglio.

Se esegui già n8n, pianifica di sostituirlo invece di aggiungerlo. Lo stack descritto nella nostra guida all'esecuzione di n8n su un VPS con Docker e HTTPS comprende un processo Node accanto a Postgres e funziona bene su un server di piccole dimensioni. Il solo backend di LiveContext riserva più memoria dell'intero stack. Due piattaforme di automazione su un VPS da 8 GB funzionano fino a quando entrambe non eseguono un job nello stesso minuto. Se condividi comunque l'host, imposta limiti espliciti anche per tutti gli altri servizi, usando il metodo descritto nel nostro articolo sull'impostazione dei limiti di memoria in Docker Compose, così un workflow fuori controllo non può esaurire le risorse e bloccare il server.

Installare LiveContext con Docker Compose, fissato a un tag

Partire da un VPS Ubuntu 24.04 pulito, con Docker Engine 24 o versione successiva e Compose v2. Se Docker non è ancora installato, seguire prima la nostra guida di base a Docker Compose per un VPS, quindi tornare qui.

Il README offre npx livecontext per l'avvio con una sola riga. Su un laptop può andare bene. Su un server è preferibile avere il file Compose in una directory sotto il proprio controllo. In questo modo un aggiornamento consiste in un git checkout e si può verificare esattamente che cosa è cambiato.

sudo apt update && sudo apt install -y git
git clone https://github.com/livecontext-ai/livecontext-ce.git
cd livecontext-ce
git tag --list 'v*' | tail -5
git checkout v0.2.11
cp docker/.env.ce.example docker/.env.ce
chmod 600 docker/.env.ce

Il file Compose fissa già ogni immagine al relativo release tag, ad esempio ghcr.io/livecontext-ai/livecontext-ce:v0.2.11. Il checkout del tag Git corrispondente mantiene allineati il file Compose e le immagini, perché il file Compose per v0.2.11 è stato scritto per quelle immagini. Non modificare i tag in latest. Un tag latest può cambiare senza preavviso e il backend esegue le migrazioni del database a ogni avvio. Un pull accidentale può quindi portare avanti lo schema alle 3 del mattino, senza possibilità di ripristino se non tramite un restore.

Modificare docker/.env.ce prima del primo avvio; la sezione successiva indica che cosa cambiare. Quindi avviare lo stack.

docker compose --env-file docker/.env.ce up -d
docker compose --env-file docker/.env.ce ps

Usare lo stesso flag --env-file in ogni comando Compose di questa guida. Compose rilegge il file a ogni invocazione. Un comando senza quel flag usa quindi i valori predefiniti incorporati nel file Compose e può pubblicare porte diverse da quelle configurate.

L'healthcheck del backend ha un start_period di 120s ed esegue il polling di /actuator/health. Per questo docker compose ps segnala il servizio livecontext come health: starting per circa i primi due minuti, mentre vengono eseguite le migrazioni dello schema e la registrazione dello strumento. È un comportamento normale. Un controllo rapido dal server:

curl -s localhost:8080/actuator/health

Il comando dovrebbe stampare {"status":"UP"}. Quando accade, aprire l'interfaccia web sulla porta 3000. Il primo account creato diventa l'account amministratore, quindi creare il proprio prima che la porta sia raggiungibile da altri. Questo è il motivo principale per non pubblicare la porta 3000 su Internet il primo giorno.

I valori di ambiente da modificare

Il file di esempio include valori predefiniti funzionanti, quindi lo stack può essere avviato su un laptop. Alcuni di questi valori non sono sicuri su un server pubblico.

POSTGRES_PASSWORD=<random>
MINIO_ROOT_USER=<not minioadmin>
MINIO_ROOT_PASSWORD=<random>
CREDENTIAL_ENCRYPTION_PASSWORD=<random>
CREDENTIAL_ENCRYPTION_SALT=<random>
ANTHROPIC_API_KEY=sk-ant-...
FRONTEND_PORT=3000
BACKEND_PORT=8080
GATEWAY_PUBLIC_URL=https://lc-api.example.com

Genera ogni valore casuale con openssl rand -base64 32. Presta attenzione ai valori che possono creare problemi:

• POSTGRES_PASSWORD e MINIO_ROOT_PASSWORD sono forniti rispettivamente come postgres e minioadmin. Nessuna delle due porte del database è pubblicata sull'host, quindi non è esposta direttamente. Tuttavia, qualsiasi container collegato in seguito alla stessa rete può raggiungere entrambi i database usando il valore predefinito documentato.
• CREDENTIAL_ENCRYPTION_PASSWORD e CREDENTIAL_ENCRYPTION_SALT vengono generati automaticamente se lasciati vuoti. Impostali invece manualmente. Le credenziali salvate dai tuoi workflow vengono crittografate con questa coppia di valori. Se ripristini un dump del database su un nuovo server senza la stessa password e lo stesso salt, le righe contenenti le credenziali non saranno leggibili. Impostali una sola volta e considera quindi docker/.env.ce parte del backup.
• FRONTEND_PORT e BACKEND_PORT vengono sostituiti nei mapping delle porte con ${FRONTEND_PORT:-3000}:3000 e ${BACKEND_PORT:-8080}:8080. Il file env di esempio imposta esplicitamente entrambi i valori, che non sono sempre 3000 e 8080. Leggi il tuo file invece di dare per scontati questi valori.
• GATEWAY_PUBLIC_URL è l'origine del backend visibile dal browser. Diventa importante non appena interviene un reverse proxy. Consulta la sezione successiva.
• Le chiavi dei modelli (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY e, facoltativamente, MISTRAL_API_KEY o DEEPSEEK_API_KEY) si trovano qui in chiaro. Compila soltanto il provider che utilizzi effettivamente.

Cosa fanno i sei container

• postgres esegue pgvector/pgvector:pg16 nel container livecontext-db e contiene il database denominato livecontext. L'estensione pgvector serve per la ricerca tramite embedding, quindi un'immagine postgres:16 standard non è sufficiente.
• redis esegue redis:7-alpine con appendonly yes e --maxmemory-policy noeviction. Questa policy è intenzionale: qui Redis contiene lo stato delle code e delle esecuzioni, quindi quando raggiunge il limite di memoria restituisce un errore al processo di scrittura invece di eliminare le chiavi senza segnalarlo. Un errore visibile è preferibile a un'elaborazione che scompare.
• minio è l'object store compatibile con S3 per i file che transitano nei workflow. Un container minio-init esegue una sola volta mc mb myminio/workflow-files --ignore-existing all'avvio, crea il bucket e termina. Vedere minio-init come exited (0) in docker compose ps indica uno stato corretto.
• bridge contiene gli adapter CLI e gli strumenti MCP (model context protocol). È in ascolto sulla porta 8093 all'interno della rete Docker e non è pubblicato sull'host.
• livecontext è il backend: un monolite Java 21 sulla porta 8080. Esegue il motore dei workflow, gli scheduler e gli agenti.
• frontend è l'interfaccia web Next.js sulla porta 3000. Solo questi ultimi due container sono pubblicati sull'host.

Lo stato è memorizzato in cinque volumi denominati: livecontext_data per Postgres, livecontext_redis, livecontext_minio, livecontext_keys e livecontext_logs. Compose antepone loro il nome del progetto, che per impostazione predefinita corrisponde al nome della directory, quindi il volume effettivo sul disco avrà un nome simile a livecontext-ce_livecontext_minio. Esegui docker volume ls e copia i nomi esatti prima di scrivere uno script di backup che li utilizzi.

docker compose down -v elimina tutti e cinque i volumi. È il metodo documentato per ricominciare da zero, ma è anche il modo più rapido per perdere ogni workflow creato. La presenza di -v fa tutta la differenza.

Pubblicazione tramite Traefik invece della porta 3000

Pubblicare le porte 3000 e 8080 su un VPS pubblico espone l'applicazione senza TLS (transport layer security) e senza un controllo davanti alla registrazione degli amministratori. Una regola ufw non è sufficiente, perché Docker inserisce le proprie regole iptables per le porte pubblicate prima della catena gestita da ufw. Di conseguenza, una porta pubblicata su 0.0.0.0 resta raggiungibile anche quando ufw indica che la porta è negata.

La soluzione corretta consiste nel non pubblicare alcuna porta e nel consentire al proxy di raggiungere i container tramite una rete Docker condivisa. Crea docker-compose.override.yml nella directory radice del repository:

services:
  frontend:
    ports: !override []
    networks:
      - default
      - proxy
  livecontext:
    ports: !override []
    networks:
      - default
      - proxy

networks:
  proxy:
    external: true

Due dettagli determinano il corretto funzionamento. !override sostituisce l'elenco delle porte invece di unirlo a quello esistente. Questa funzione richiede Compose v2.24 o versioni successive: verifica con docker compose version. Con una versione precedente di Compose, i due elenchi vengono uniti e le porte restano pubblicate. Inoltre, default deve restare in ogni elenco networks, perché specificare una rete sostituisce quella predefinita. Se la ometti, il frontend non può più raggiungere Postgres e Redis. Verifica il risultato della configurazione combinata prima di avviare qualsiasi servizio:

docker compose --env-file docker/.env.ce config

I router, il resolver dei certificati e il redirect da HTTP a HTTPS sono uguali a quelli di qualsiasi altra applicazione. Segui quindi la nostra guida al reverse proxy Traefik per eseguire più applicazioni su un unico VPS invece di scrivere qui una nuova configurazione TLS. Instrada un hostname verso frontend sulla porta 3000 e un secondo hostname verso livecontext sulla porta 8080.

Il secondo hostname è obbligatorio. L'interfaccia web chiama il backend dal browser, quindi il backend deve avere un'origine propria raggiungibile dal browser. Imposta GATEWAY_PUBLIC_URL in docker/.env.ce sull'URL del backend, ad esempio https://lc-api.example.com. Se lo ometti, la pagina viene caricata normalmente, ma ogni operazione non riesce, perché l'interfaccia determina l'origine del backend dall'indirizzo utilizzato per aprirla e chiama una porta che il proxy non ha pubblicato.

Poiché la pagina di registrazione è aperta al primo utente che la raggiunge, conviene applicare la forward auth al router del frontend. In questo modo nessuno può visualizzare la pagina senza autenticarsi tramite il proxy. È proprio questo che aggiunge l'esecuzione di Authentik come livello SSO proprietario alla stessa configurazione Traefik.

Dove viene usata la chiave del modello e perché un'istanza inattiva continua a costare

Gli agenti vengono eseguiti all'interno dell'automazione, e questo cambia l'economia del sistema rispetto a un semplice strumento per workflow. La chiave del provider si trova in docker/.env.ce come ANTHROPIC_API_KEY o OPENAI_API_KEY, viene letta dal backend e dal bridge all'avvio e si applica all'intera istanza. Non è associata al singolo utente. Chiunque disponga di un account sulla tua istanza e possa creare un agente utilizza quella chiave, e il primo utente a registrarsi è un amministratore.

Tre pratiche aiutano a mantenere prevedibile la spesa. Crea una chiave del provider separata per questo VPS, così puoi revocarla senza intervenire su altro. Imposta un limite massimo di spesa nella console del provider, perché questo è l'unico limite esterno alla macchina che stai proteggendo. Usa quindi i budget di credito per agente e le metriche per agente esposte da LiveContext, in modo che un singolo ciclo non esaurisca la chiave prima che tu te ne accorga.

Quando un agente è configurato con una pianificazione, il costo non è nullo nemmeno se resta inattivo. Il trigger pianificato si attiva anche se nessuno lo sta monitorando, e ogni attivazione invia token. Una pianificazione ogni cinque minuti equivale a 288 esecuzioni al giorno, e un agente che legge una pagina e decide di non fare nulla comporta comunque un costo per la lettura della pagina. Configura i primi agenti con un trigger webhook o chat, monitora la spesa effettiva per una settimana e passa a una pianificazione solo dopo aver determinato il costo per esecuzione.

Eseguire il backup di Postgres e dell'object store

Sono presenti due archivi dati e un secret. La perdita di uno qualsiasi dei tre comporta la perdita dell'istanza. Eseguire il backup del database e del bucket nella stessa finestra temporale, con il backend arrestato, in modo che nessun file possa essere scritto dopo l'esportazione della relativa riga del database.

cd ~/livecontext-ce
mkdir -p ~/backups
docker compose --env-file docker/.env.ce stop livecontext frontend
docker compose --env-file docker/.env.ce exec -T postgres \
  pg_dump -U postgres -d livecontext --clean --if-exists \
  | gzip > ~/backups/livecontext-db-$(date +%F).sql.gz

Usare al posto di postgres il valore impostato per DB_USERNAME, se è stato modificato. Copiare quindi il volume dell'object store usando il nome con prefisso visualizzato da docker volume ls:

docker run --rm \
  -v livecontext-ce_livecontext_minio:/data \
  -v ~/backups:/backup \
  alpine tar czf /backup/livecontext-minio-$(date +%F).tgz -C /data .
docker compose --env-file docker/.env.ce start livecontext frontend
cp docker/.env.ce ~/backups/env.ce.$(date +%F)

Verificare che il dump non sia vuoto prima di considerarlo valido: gunzip -c ~/backups/livecontext-db-*.sql.gz | head -20 dovrebbe mostrare istruzioni CREATE TABLE e DROP TABLE, non un errore su una sola riga. Copiare quindi tutti e tre i file fuori dal server. Un backup che risiede solo sulla macchina che protegge non è un backup.

Per eseguire il ripristino su un server nuovo, installare lo stesso tag, ripristinare il valore salvato di docker/.env.ce in modo che la password e il salt per la cifratura delle credenziali corrispondano, avviare una volta lo stack affinché i volumi vengano creati, arrestare il backend, quindi caricare il dump:

gunzip -c livecontext-db-2026-08-10.sql.gz \
  | docker compose --env-file docker/.env.ce exec -T postgres psql -U postgres -d livecontext

Aggiornamenti e ripristino in caso di problemi

Esegui prima un dump, ogni volta. Il backend applica le migrazioni dello schema all'avvio e le migrazioni procedono in una sola direzione. Dopo un aggiornamento non riuscito, il checkout del tag precedente lascia in esecuzione il codice precedente su uno schema più recente. Il rollback consiste nel ripristinare il dump. Per questo il dump viene eseguito per primo.

cd ~/livecontext-ce
git fetch --tags
git tag --list 'v*' | tail -5
TAG=v0.2.11
git checkout "$TAG"
docker compose --env-file docker/.env.ce pull
docker compose --env-file docker/.env.ce up -d
docker compose --env-file docker/.env.ce logs -f livecontext

Imposta TAG sul tag scelto dall'elenco stampato dal terzo comando. Monitora il log del backend finché l'endpoint di health check non risponde di nuovo. Il tuo docker-compose.override.yml non è tracciato, quindi un git checkout lo lascia invariato. Tuttavia, leggi il diff di docker-compose.yml tra i tag, perché un nuovo servizio o la ridenominazione di un servizio può rendere obsoleto il tuo override senza produrre alcun messaggio di errore.

Modalità di errore e stringhe visualizzate

Un container continua a riavviarsi e docker compose ps mostra exited (137). Si tratta dell'out-of-memory killer del kernel. docker inspect livecontext-app lo conferma con "OOMKilled": true nel blocco dello stato. Il backend ha raggiunto il limite di 1536M oppure l'host ha esaurito la memoria prima. Controlla free -m prima di aumentare qualsiasi limite, perché aumentare il limite di un container su un host senza memoria disponibile sposta semplicemente l'arresto forzato su un altro container.

Il pull non riesce con no matching manifest for linux/arm64/v8 in the manifest list entries. Le immagini sono pubblicate solo per linux/amd64. Un VPS Arm non può eseguire questo stack usando le immagini pubblicate. L'emulazione tramite QEMU è troppo lenta per una JVM con Chromium. Passa a un piano x86.

Bind for 0.0.0.0:3000 failed: port is already allocated. Un altro processo sull'host utilizza già quella porta. Modifica FRONTEND_PORT in docker/.env.ce oppure applica l'override precedente e non pubblicare alcuna porta.

La UI è attiva, ma la richiesta di login non riesce dopo l'aggiunta del proxy. Il browser chiama il backend tramite un'origine che il proxy non serve. Apri la scheda Network del browser e controlla l'host della richiesta non riuscita. Imposta GATEWAY_PUBLIC_URL sull'URL pubblico del backend e ricrea il container frontend, perché questo valore viene letto all'avvio.

Tutto è operativo, ma i file caricati in un workflow scompaiono. Controlla che minio-init mostri exited (0) invece di un codice diverso da zero. Se il bucket workflow-files non è mai stato creato, il backend non ha una destinazione in cui archiviare gli oggetti.

Scegliere LiveContext o n8n

Scegli LiveContext quando l'agente è il punto centrale: vuoi che il modello crei ed esegua l'automazione e accetti un server da 8 GB e un servizio Java come compromesso. Scegli n8n quando vuoi workflow deterministici, una libreria di nodi ampia e un'impronta che consenta di condividere un VPS con altri servizi. I numeri di versione riportati qui sono recenti, v0.2.11 ad agosto 2026; quindi fissa il tuo tag e leggi le note di rilascio prima di ogni aggiornamento. Per una panoramica più ampia, compresi gli strumenti che si collocano tra queste due opzioni, consulta la nostra panoramica delle alternative self-hosted a n8n invece di leggere un confronto limitato a queste due soluzioni.

FAQ

Quanta RAM richiede un'istanza self-hosted di LiveContext?

Prevedere 8 GB. Il README upstream indica 4 GB come requisito minimo e 8 GB come valore consigliato; anche il file compose fornito segue questa indicazione: il solo backend è limitato a 1536 MB e i cinque servizi di base richiedono complessivamente poco meno di 3 GB, senza considerare il container frontend senza limite. L'abilitazione del profilo browser agent aggiunge altri 2048 MB per Chromium, oltre a un container SearXNG. A quel punto, 8 GB diventano necessari.

Posso eseguire LiveContext su un VPS Arm?

No. Tutte le immagini pubblicate sono compilate per linux/amd64, quindi docker compose up su un piano Arm fallisce durante il pull con no matching manifest for linux/arm64/v8 in the manifest list entries. In teoria è possibile eseguirlo con l'emulazione QEMU, ma in pratica le prestazioni sono inutilizzabili per un carico JVM. Scegliere un piano x86.

Dove inserisco la chiave API del modello?

In docker/.env.ce, come ANTHROPIC_API_KEY, OPENAI_API_KEY o GOOGLE_API_KEY, prima del primo avvio. Il backend e il bridge la leggono all'avvio e la chiave si applica all'intera istanza, non a un singolo utente. Mantenere il file con modalità 600 e usare una chiave creata esclusivamente per questo server, così da poterla revocare separatamente. Impostare inoltre un limite di spesa nella console del provider, perché questo è l'unico limite gestito al di fuori della macchina.

Come eseguo il backup di LiveContext?

Servono tre elementi: un pg_dump del database livecontext, una copia del volume MinIO e il file docker/.env.ce. Arrestare i servizi livecontext e frontend durante i primi due backup, così il database e l'object store restano coerenti. Il file env è importante perché le credenziali memorizzate nei workflow sono cifrate con CREDENTIAL_ENCRYPTION_PASSWORD e CREDENTIAL_ENCRYPTION_SALT. Un ripristino senza questi valori lascia righe relative alle credenziali che nessun componente del nuovo server può leggere.

Perché il backend resta su health: starting per alcuni minuti dopo l'avvio?

L'healthcheck di compose imposta start_period: 120s ed esegue il polling di /actuator/health. Docker indica quindi il servizio come in avvio mentre vengono eseguite le migrazioni dello schema e la registrazione degli strumenti. Al primo avvio, attendere da 2 a 3 minuti è normale. Se il servizio non diventa mai healthy, leggere docker compose logs -f livecontext. Quando lo stack si arresta durante la fase di migrazione, di solito è configurato per usare un volume del database proveniente da una release più recente.