Installazione del server PocketContext

Questa guida è per chi esegue la macchina. Installi il server, poi ci colleghi un’applicazione.

Non stai installando il CRM, il wiki o le altre app come parte del download del server. Ogni app si configura per conto suo. Il server è il programma su cui girano tutte. Conserva i dati, verifica l’accesso e offre agli assistenti di programmazione una porta SQL in sola lettura. PocketBase, il prodotto open source dentro il server, fornisce il database, l’accesso e l’API dei record. La schermata di amministrazione è su /_/ all’indirizzo che servi.

Chi accede soltanto e usa un’app deve seguire la guida per chi accede.

Che cosa stai scegliendo

Ci sono quattro modi per avere un server in esecuzione. Differiscono per chi possiede il computer e per come l’app ci arriva.

flowchart TB
  you[Tu, l’amministratore]
  you --> own[Un computer che hai già]
  you --> cloud[Una nuova macchina cloud]

  own --> binary[Binario della release]
  own --> source[Compilazione dal codice sorgente]
  binary --> oneapp[Esegui un’app su quel computer]
  source --> oneapp

  cloud --> deploy[PocketDeploy]
  deploy --> vps[Macchina Ubuntu più il container dell’app]

Modo	Usalo quando
Binario della release	Vuoi il server pubblicato su Linux o su un Mac Apple Silicon, senza compilare.
Compilazione dal codice sorgente	Stai sviluppando, oppure ti serve il commit esatto che un’applicazione fissa.
Un’app su quello stesso computer	Vuoi un server privato su localhost per una sola applicazione.
PocketDeploy	Vuoi una macchina cloud, il DNS e il container dell’applicazione creati da un file di configurazione.

Un’installazione da release non crea i dati dell’applicazione. pocketcontext --version stampa soltanto la versione. Il database compare quando servi un’applicazione e punti --dir a una cartella dati.

La forma di un’app in esecuzione

flowchart LR
  binary[programma pocketcontext]
  app[Cartella dell’applicazione]
  data[(pb_data su disco)]
  person[Browser o assistente]

  app --> binary
  binary --> data
  person --> binary

La cartella dell’applicazione contiene tre cose che il server carica:

Pezzo	Che cos’è
`pb_migrations`	Le tabelle.
`pb_hooks`	Controlli aggiuntivi quando i record cambiano.
`pocketcontext.json`	Quali tabelle SQL può vedere.
`POCKETCONTEXT_VERSION`	Il commit del server con cui quell’applicazione è stata verificata.

Ogni applicazione ha il proprio processo, la propria cartella dati e le proprie impostazioni di accesso Google. Servire il wiki non serve il CRM.

Tieni pb_data fuori da Git. Contiene il database e le credenziali.

1. Binario della release su un computer che hai

Questo è il percorso per Linux su Intel o ARM a 64 bit, e per macOS 15 o successivo su Apple Silicon. La build Mac pubblicata non è per i Mac Intel. I pacchetti Linux sono verificati su Ubuntu 24.04, Alpine 3.23 e Debian 12. È l’insieme su cui la release è stata provata.

Ti servono curl, tar e sha256sum oppure shasum. Non ti serve sudo. L’installer non modifica il profilo della shell.

curl -fsSL https://pocketcontext.com/pocketcontext/install.sh | sh

Lo script scarica l’archivio di questa release, ne verifica il checksum SHA-256 e installa il programma in ~/.local/bin/pocketcontext. Sostituisce una copia più vecchia solo dopo che quel download risulta corretto. Eseguilo di nuovo in seguito per passare alla release più recente. Ferma qualsiasi server che hai già in esecuzione prima di sostituire il binario, e fai prima un backup di pb_data. Installare un nuovo binario non migra le tabelle di un’applicazione.

Se ~/.local/bin non è nel tuo PATH, aggiungi questo alla configurazione della shell e apri un nuovo terminale:

export PATH="$HOME/.local/bin:$PATH"

Poi:

pocketcontext --version

Dovresti vedere la versione di PocketContext, la versione di PocketBase incorporata e un commit del codice sorgente. Una riga di versione significa che il programma è installato. Non significa che un’applicazione sia in esecuzione.

Se vuoi leggere prima l’installer

Lo script del sito installa sempre l’ultima release pubblicata. Per fissare lo sguardo su una versione, scarica install.sh e checksums.txt di quella versione da GitHub Releases, leggi lo script, poi eseguilo. L’esempio v0.9.1 nel README del server è:

curl -fL -o install.sh https://github.com/pocketcontext/pocketcontext/releases/download/v0.9.1/install.sh
# Read install.sh, then:
sh install.sh

Per rimuovere il programma, elimina ~/.local/bin/pocketcontext. I dati dell’applicazione restano dove li hai messi.

2. Compilazione dal codice sorgente

Usalo quando il README di un’applicazione ti dice di compilare il commit in POCKETCONTEXT_VERSION, oppure quando stai modificando il server.

Ti servono Go 1.27 o successivo e un compilatore C. Il lettore SQL usa SQLite tramite CGO. Compila con i tag math, percentile e full-text. Un semplice go test senza quei tag fallisce perché a SQLite mancano funzionalità che il server si aspetta.

git clone https://github.com/pocketcontext/pocketcontext.git
cd pocketcontext
git checkout THE_COMMIT_THE_APP_PINS
make build

make build scrive bin/pocketcontext. Chiama quel binario con il suo percorso quando servi un’app. Una build dal codice sorgente riporta dev come versione finché non è una build di release. Se il checkout del server che hai già contiene altro lavoro, usa un secondo checkout o un worktree Git per il commit fissato. Non puntare un’applicazione al commit che capita sia estratto.

3. Esegui un’applicazione su quel computer

Metti il checkout del server e il checkout dell’applicazione uno accanto all’altro. DealContext è l’esempio che usa il README del server. La stessa forma vale per le altre app: WikiContext, TaskContext, NotifyContext e le altre.

somewhere/
├── pocketcontext/
└── dealcontext/

Dalla directory dell’applicazione, con il binario fissato:

../pocketcontext/bin/pocketcontext serve \
  --dir ./pb_data \
  --http 127.0.0.1:8090

Passa sempre --dir. La posizione predefinita dei dati di PocketBase dipende da come è stato avviato il programma, e un percorso assoluto al binario può mettere i dati accanto al binario. Migrazioni e hook vengono letti da ./pb_migrations e ./pb_hooks quando avvii nella directory dell’applicazione. Usa --migrationsDir, --hooksDir e --contextConfig quando quei file sono altrove.

Il primo avvio applica le migrazioni. Non viene creato nessun utente iniziale. Il primo operatore lo crei tu.

sequenceDiagram
  participant Admin
  participant Server as pocketcontext serve
  participant Disk as pb_data

  Admin->>Server: servi su 127.0.0.1:8090
  Server->>Disk: applica le migrazioni
  Admin->>Server: apri /_/ e crea un superutente
  Admin->>Server: crea un account ordinario

Crea l’operatore con il comando superuser upsert del server, usando gli stessi --dir e percorsi delle migrazioni. Accedi con POST /api/collections/_superusers/auth-with-password, oppure usa la dashboard su http://127.0.0.1:8090/_/. Poi crea un account ordinario per il lavoro quotidiano. Il nome della collection dipende dall’app. DealContext e PeopleContext usano agents. La maggior parte delle altre usa la collection predefinita users di PocketBase. Il README dell’app è l’elenco che conta.

Usa l’account ordinario per l’assistente. Lascia il superutente per la manutenzione. I token da superutente non sono una scorciatoia attraverso la porta SQL.

La regola del README del server per la porta è: tieni il database sul disco locale e collegati a localhost, a meno che tu non abbia configurato l’accesso di rete e TLS. Un server sul laptop, per te, deve restare su 127.0.0.1.

L’accesso con Google è facoltativo e vale per ogni applicazione. Ogni app vuole il proprio client Google Web, l’id client e il secret corrispondenti nelle variabili d’ambiente di quell’app, e il dominio Workspace quando vuoi che il primo accesso crei un account. Il callback usato dagli strumenti da riga di comando è http://127.0.0.1:8765/callback. Il callback del browser è https://YOUR-APP-ORIGIN/api/oauth2-redirect. Id e secret si impostano insieme. Uno senza l’altro interrompe l’avvio nelle app che lo verificano.

Riavvia il server dopo aver modificato pocketcontext.json, i campi nascosti o le definizioni delle collection. SQL apprende le colonne consentite all’avvio.

Più app su un computer

Dai a ogni app la propria directory dati e la propria porta. Due app non possono condividere pb_data. LinkContext e NetworkContext documentano entrambi la porta 8095 per un’esecuzione locale, quindi avviane solo una su quella porta, oppure cambia la porta per la seconda.

flowchart TD
  crm["CRM su 127.0.0.1:8090"]
  wiki["Wiki su 127.0.0.1:8091"]
  crmdb["pb_data del CRM"]
  wikidb["pb_data del wiki"]

  crm --> crmdb
  wiki --> wikidb

4. Una macchina cloud, tramite PocketDeploy

PocketDeploy è il modo in cui questo progetto crea un server su un account cloud e ci mette un’applicazione. Esegui PocketDeploy dal tuo computer. Parla con il cloud, poi con la nuova macchina tramite SSH.

Può usare Oracle Cloud, DigitalOcean, Google Cloud o Hetzner. Crea una macchina Ubuntu 24.04 con un indirizzo IPv4 pubblico, più le regole firewall di cui è proprietario. Su quella macchina installa Docker e ONCE. ONCE è l’esecutore di app di Basecamp, fissato qui alla v0.3.3. L’applicazione arriva come immagine container. Quell’immagine contiene già la build del server PocketContext con cui l’app è stata pubblicata. Non copi tu ~/.local/bin/pocketcontext sulla macchina cloud.

sequenceDiagram
  participant Admin
  participant PD as PocketDeploy sul tuo computer
  participant Cloud as Account cloud
  participant VPS as Nuova macchina Ubuntu
  participant Vault as VaultContext

  Admin->>PD: plan, poi converge
  PD->>Cloud: crea la macchina e il firewall
  PD->>VPS: installa ONCE e il container dell’app
  Admin->>PD: vault-save
  PD->>Vault: conserva il diario del deployment

Google Cloud e DigitalOcean hanno superato verifiche usa e getta nelle note di PocketDeploy, inclusi HTTPS, aggiornamenti, riavvio e una connessione di posta. Hetzner ha superato la prima creazione della macchina. Le verifiche dell’applicazione su Hetzner erano ancora in sospeso quando quel README è stato scritto. Leggi pocketdeploy/docs/verification.md prima di considerare un provider come completato.

Che cosa prepari

PocketDeploy vuole Nix e devenv sul computer da cui operi, poi:

devenv shell
uv sync --locked --extra test
pocketdeploy --help

La shell devenv fornisce Python 3.12, uv, gli strumenti da riga di comando di Oracle e Google Cloud, OpenSSH, Git, la GitHub CLI, curl, jq e SQLite. Il comando hcloud di Hetzner è separato. Lo installi tu e lo metti nel PATH.

Per un nuovo deployment, copia un colors.yml di esempio in un repository tutto suo. Usa examples/colors.yml per Oracle Cloud, oppure examples/colors-digitalocean.yml, examples/colors-gcp.yml o examples/colors-hcloud.yml per gli altri. Il colors.yml già presente nel checkout di PocketDeploy appartiene a un deployment di prova eliminato il 10 ottobre 2026. Non riusare quell’identità.

Imposta provider-compute su oci, digitalocean, gcp o hcloud. Le reti, i progetti cloud e il routing che esistono già restano tuoi. PocketDeploy non adotta lo stack di produzione di un estraneo per ipotesi.

C’è anche un launcher portatile. Dall’installazione dello skill:

npx skills add pocketcontext/pocketdeploy --skill pocketdeploy --agent codex --yes

Copia il programma pocketdeploy di quello skill nel repository del deployment e tienilo accanto a colors.yml. I comandi leggono colors.yml solo nella directory corrente. I valori privati vanno in .envrc.private, che non viene committato. Il diario locale è .colors.sqlite. Le chiavi SSH restano in .ssh/. Questi tre restano fuori da Git.

I comandi, in ordine

pocketdeploy init
pocketdeploy vault-save
pocketdeploy converge
pocketdeploy vault-save

init crea l’identità locale e le chiavi. converge fa corrispondere il cloud al file. plan mostra che cosa cambierebbe, e vale la pena eseguirlo prima di converge su qualsiasi cosa a cui tieni già. vault-save conserva una copia cifrata del diario, dei binding privati e dell’autorità SSH in VaultContext. Per quello ti servono un accesso a VaultContext e una sessione sbloccata. Il checkpoint può ricostruire il diario. Non contiene il database dell’applicazione né i file caricati. Quelli hanno bisogno di un backup proprio.

Un operatore alla volta. Il lock è sul computer che esegue PocketDeploy. Non coordina due persone su due computer.

Cambiare provider-compute in seguito non sposta la macchina. Crei un nuovo deployment, ripristini i dati dell’applicazione con i passaggi di backup dell’app e sposti il DNS.

flowchart LR
  yml[colors.yml]
  diary[(.colors.sqlite)]
  machine[Macchina cloud]
  appdb[(Database dell’applicazione)]
  vault[Checkpoint di VaultContext]

  yml --> machine
  diary --> vault
  appdb -.-> backup[Backup separato]

La linea tratteggiata è voluta. Ripristinare il checkpoint non ripristina appdb.

Che cosa consegni a un utente finale

Quando l’app risponde al suo indirizzo, consegna alla persona tre cose:

L’origine https://, oppure http://127.0.0.1:PORT se è solo sulla sua macchina.
L’indirizzo email che il suo account deve usare.
Un rimando a la guida per chi accede.

Non serve la password del superutente. Non serve una copia di pb_data.