Du bist die Person, die den Rechner betreibt. Wer sich nur anmeldet, will die andere Anleitung.

Den PocketContext-Server installieren

Diese Anleitung ist für die Person, die den Rechner betreibt. Du installierst den Server und hängst dann eine Anwendung daran.

Du installierst das CRM, das Wiki oder die anderen Anwendungen nicht als Teil des Server-Downloads. Jede Anwendung wird für sich eingerichtet. Der Server ist das Programm, auf dem sie alle laufen. Er speichert Daten, prüft die Anmeldung und gibt KI-Assistenten einen nur lesenden SQL-Zugang. PocketBase, das Open-Source-Produkt im Server, liefert die Datenbank, die Anmeldung und die Records-API. Die Admin-Oberfläche liegt unter /_/ auf der Adresse, die du auslieferst.

Wer sich nur anmeldet und eine Anwendung nutzt, folgt der Anleitung für Nutzende.

Was du auswählst

Es gibt vier Wege zu einem laufenden Server. Sie unterscheiden sich darin, wem der Rechner gehört und wie die Anwendung darauf kommt.

flowchart TB
  you[Du als Admin]
  you --> own[Ein Rechner, den du schon hast]
  you --> cloud[Ein neuer Cloud-Rechner]

  own --> binary[Veröffentlichtes Programm]
  own --> source[Aus dem Quelltext bauen]
  binary --> oneapp[Eine Anwendung auf diesem Rechner betreiben]
  source --> oneapp

  cloud --> deploy[PocketDeploy]
  deploy --> vps[Ubuntu-Rechner plus der Anwendungscontainer]

Weg	Wann du ihn nutzt
Veröffentlichtes Programm	Du willst den veröffentlichten Server auf Linux oder einem Mac mit Apple Silicon, ohne zu kompilieren.
Aus dem Quelltext bauen	Du entwickelst, oder du brauchst genau den Commit, den eine Anwendung festlegt.
Eine Anwendung auf demselben Rechner	Du willst einen privaten Server auf localhost für eine Anwendung.
PocketDeploy	Du willst einen Cloud-Rechner, DNS und den Anwendungscontainer aus einer Konfigurationsdatei.

Eine Release-Installation legt keine Anwendungsdaten an. pocketcontext --version gibt nur die Version aus. Die Datenbank erscheint, wenn du eine Anwendung auslieferst und --dir auf einen Datenordner zeigst.

So sieht eine laufende Anwendung aus

flowchart LR
  binary[pocketcontext-Programm]
  app[Anwendungsordner]
  data[(pb_data auf der Festplatte)]
  person[Browser oder KI-Assistent]

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

Der Anwendungsordner enthält drei Dinge, die der Server lädt:

Bestandteil	Was es ist
`pb_migrations`	Die Tabellen.
`pb_hooks`	Zusätzliche Prüfungen, wenn Datensätze sich ändern.
`pocketcontext.json`	Welche Tabellen SQL sehen darf.
`POCKETCONTEXT_VERSION`	Der Server-Commit, mit dem diese Anwendung getestet wurde.

Jede Anwendung bekommt ihren eigenen Prozess, ihren eigenen Datenordner und ihre eigenen Einstellungen für die Google-Anmeldung. Wer das Wiki ausliefert, liefert damit nicht das CRM aus.

Halte pb_data außerhalb von Git. Dort liegen die Datenbank und die Zugangsdaten.

1. Veröffentlichtes Programm auf einem Rechner, den du hast

Dieser Weg gilt für Linux auf 64-Bit-Intel oder ARM und für macOS 15 oder neuer auf Apple Silicon. Der veröffentlichte Mac-Build ist nicht für Intel-Macs. Die Linux-Pakete sind auf Ubuntu 24.04, Alpine 3.23 und Debian 12 getestet. Auf dieser Menge wurde das Release geprüft.

Du brauchst curl, tar und entweder sha256sum oder shasum. Du brauchst kein sudo. Das Installationsprogramm ändert dein Shell-Profil nicht.

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

Das Skript lädt das Archiv für dieses Release herunter, prüft seine SHA-256-Prüfsumme und installiert das Programm unter ~/.local/bin/pocketcontext. Eine ältere Kopie ersetzt es erst, nachdem dieser Download geprüft wurde. Führe es später erneut aus, um auf das neuere Release zu wechseln. Stoppe jeden Server, der schon läuft, bevor du das Binary ersetzt, und sichere zuerst pb_data. Ein neues Binary zu installieren migriert die Tabellen einer Anwendung nicht.

Wenn ~/.local/bin nicht in deinem PATH liegt, füge das zu deiner Shell-Konfiguration hinzu und öffne ein neues Terminal:

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

Danach:

pocketcontext --version

Du solltest die PocketContext-Version, die eingebettete PocketBase-Version und einen Quell-Commit sehen. Eine Versionszeile bedeutet, dass das Programm installiert ist. Sie bedeutet nicht, dass eine Anwendung läuft.

Wenn du das Installationsprogramm zuerst lesen willst

Das Skript auf der Website installiert immer das neueste veröffentlichte Release. Um eine Version fest im Blick zu behalten, lade install.sh und checksums.txt dieser Version von GitHub Releases herunter, lies das Skript und führe es dann aus. Das Beispiel für v0.9.1 in der Server-README ist:

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

Um das Programm zu entfernen, lösche ~/.local/bin/pocketcontext. Anwendungsdaten bleiben dort, wo du sie abgelegt hast.

2. Aus dem Quelltext bauen

Nutze das, wenn die README einer Anwendung dich anweist, den Commit in POCKETCONTEXT_VERSION zu bauen, oder wenn du den Server änderst.

Du brauchst Go 1.27 oder neuer und einen C-Compiler. Der SQL-Leser nutzt SQLite über CGO. Baue mit den Tags für Mathematik, Perzentile und Volltext. Ein einfaches go test ohne diese Tags schlägt fehl, weil SQLite Funktionen fehlen, die der Server erwartet.

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

make build schreibt bin/pocketcontext. Rufe dieses Binary über seinen Pfad auf, wenn du eine Anwendung startest. Ein Bau aus dem Quelltext meldet dev als Version, bis es ein Release-Build ist. Wenn in deinem bestehenden Server-Checkout andere Arbeit liegt, nutze einen zweiten Checkout oder einen Git-Worktree für den festgelegten Commit. Richte eine Anwendung nicht auf den Commit, der gerade zufällig ausgecheckt ist.

3. Eine Anwendung auf diesem Rechner betreiben

Lege den Server-Checkout und den Anwendungs-Checkout nebeneinander. DealContext ist das Beispiel, das die Server-README verwendet. Dieselbe Form passt für die anderen Anwendungen: WikiContext, TaskContext, NotifyContext und die übrigen.

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

Aus dem Anwendungsordner, mit dem festgelegten Binary:

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

Gib immer --dir an. Der Standard-Datenort von PocketBase hängt davon ab, wie das Programm gestartet wurde, und ein absoluter Pfad zum Binary kann Daten neben dem Binary ablegen. Migrationen und Hooks werden aus ./pb_migrations und ./pb_hooks gelesen, wenn du im Anwendungsordner startest. Nutze --migrationsDir, --hooksDir und --contextConfig, wenn diese Dateien woanders liegen.

Der erste Start wendet Migrationen an. Es wird niemand angelegt. Den ersten Betreiber legst du selbst an.

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

  Admin->>Server: serve auf 127.0.0.1:8090
  Server->>Disk: Migrationen anwenden
  Admin->>Server: /_/ öffnen und einen Superuser anlegen
  Admin->>Server: ein gewöhnliches Konto anlegen

Lege den Betreiber mit dem Befehl superuser upsert des Servers an, mit demselben --dir und denselben Migrationspfaden. Melde dich über POST /api/collections/_superusers/auth-with-password an, oder nutze das Dashboard unter http://127.0.0.1:8090/_/. Lege dann ein gewöhnliches Konto für die tägliche Arbeit an. Der Name der Collection hängt von der Anwendung ab. DealContext und PeopleContext nutzen agents. Die meisten anderen nutzen die Standard-Collection users von PocketBase. Maßgeblich ist die Liste in der README der Anwendung.

Nutze das gewöhnliche Konto für den KI-Assistenten. Den Superuser hebst du dir für die Wartung auf. Superuser-Token sind keine Abkürzung durch den SQL-Zugang.

Die Regel der Server-README für den Port lautet: Halte die Datenbank auf der lokalen Festplatte und binde an localhost, außer du hast Netzwerkzugriff und TLS eingerichtet. Ein Laptop-Server für dich selbst sollte auf 127.0.0.1 bleiben.

Die Google-Anmeldung ist optional und gilt pro Anwendung. Jede Anwendung braucht ihren eigenen Google-Web-Client, die passende Client-ID und das Secret in den Umgebungsvariablen dieser Anwendung und die Workspace-Domain, wenn die erste Anmeldung ein Konto anlegen soll. Der Callback, den die Kommandozeilenwerkzeuge nutzen, ist http://127.0.0.1:8765/callback. Der Browser-Callback ist https://YOUR-APP-ORIGIN/api/oauth2-redirect. ID und Secret werden gemeinsam gesetzt. Eines ohne das andere stoppt den Start bei den Anwendungen, die das prüfen.

Starte den Server neu, nachdem du pocketcontext.json, verborgene Felder oder Collection-Definitionen geändert hast. SQL erfährt die erlaubten Spalten beim Start.

Mehrere Anwendungen auf einem Rechner

Gib jeder Anwendung ihr eigenes Datenverzeichnis und ihren eigenen Port. Zwei Anwendungen können sich pb_data nicht teilen. LinkContext und NetworkContext dokumentieren beide Port 8095 für einen lokalen Start. Starte deshalb nur eine von beiden auf diesem Port, oder ändere den Port für die zweite.

flowchart TD
  crm["CRM auf 127.0.0.1:8090"]
  wiki["Wiki auf 127.0.0.1:8091"]
  crmdb["pb_data des CRM"]
  wikidb["pb_data des Wikis"]

  crm --> crmdb
  wiki --> wikidb

4. Ein Cloud-Rechner über PocketDeploy

PocketDeploy ist der Weg, wie dieses Projekt einen Server in einem Cloud-Konto anlegt und eine Anwendung darauf setzt. Du startest PocketDeploy von deinem eigenen Rechner. Es spricht mit der Cloud und dann über SSH mit dem neuen Rechner.

Es kann Oracle Cloud, DigitalOcean, Google Cloud oder Hetzner nutzen. Es legt einen Ubuntu-24.04-Rechner mit einer öffentlichen IPv4-Adresse an, plus die Firewall-Regeln, die ihm gehören. Auf diesem Rechner installiert es Docker und ONCE. ONCE ist der App-Runner von Basecamp, hier auf v0.3.3 festgelegt. Die Anwendung kommt als Container-Image. Dieses Image enthält bereits den PocketContext-Server-Build, mit dem die Anwendung veröffentlicht wurde. Du kopierst ~/.local/bin/pocketcontext nicht selbst auf den Cloud-Rechner.

sequenceDiagram
  participant Admin
  participant PD as PocketDeploy auf deinem Rechner
  participant Cloud as Cloud-Konto
  participant VPS as Neuer Ubuntu-Rechner
  participant Vault as VaultContext

  Admin->>PD: plan, dann converge
  PD->>Cloud: Rechner und Firewall anlegen
  PD->>VPS: ONCE und den Anwendungscontainer installieren
  Admin->>PD: vault-save
  PD->>Vault: das Bereitstellungstagebuch speichern

Google Cloud und DigitalOcean haben in den PocketDeploy-Notizen Prüfungen mit Wegwerf-Umgebungen bestanden, darunter HTTPS, Updates, Neustart und eine Mail-Verbindung. Hetzner hat die erste Rechner-Erstellung bestanden. Anwendungsprüfungen auf Hetzner standen noch aus, als diese README geschrieben wurde. Lies pocketdeploy/docs/verification.md, bevor du einen Anbieter als fertig betrachtest.

Was du vorbereitest

PocketDeploy erwartet Nix und devenv auf dem Rechner, von dem aus du arbeitest, und danach:

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

Die devenv-Shell stellt Python 3.12, uv, die Kommandozeilenwerkzeuge von Oracle und Google Cloud, OpenSSH, Git, die GitHub-CLI, curl, jq und SQLite bereit. Der Befehl hcloud von Hetzner ist getrennt. Du installierst ihn selbst und legst ihn in den PATH.

Für eine neue Bereitstellung kopierst du eine Beispiel-colors.yml in ein eigenes Repository. Nutze examples/colors.yml für Oracle Cloud oder examples/colors-digitalocean.yml, examples/colors-gcp.yml oder examples/colors-hcloud.yml für die anderen. Die colors.yml, die schon im PocketDeploy-Checkout liegt, gehört zu einer Testbereitstellung, die am 10. Oktober 2026 gelöscht wurde. Verwende diese Identität nicht wieder.

Setze provider-compute auf oci, digitalocean, gcp oder hcloud. Die Netzwerke, Cloud-Projekte und das Routing, die schon bestehen, bleiben deine. PocketDeploy übernimmt nicht den Produktiv-Stack einer fremden Person, indem es rät.

Es gibt auch einen portablen Starter. Aus der Skill-Installation:

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

Kopiere das Programm pocketdeploy dieses Skills in das Bereitstellungs-Repository und halte es neben colors.yml. Befehle lesen colors.yml nur im aktuellen Verzeichnis. Private Werte gehören in .envrc.private, das nicht committet wird. Das lokale Tagebuch ist .colors.sqlite. SSH-Schlüssel bleiben in .ssh/. Diese drei bleiben außerhalb von Git.

Die Befehle, der Reihe nach

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

init legt die lokale Identität und die Schlüssel an. converge bringt die Cloud mit der Datei in Übereinstimmung. plan zeigt, was sich ändern würde, und es lohnt sich, es vor converge auszuführen, sobald dir etwas daran liegt. vault-save speichert eine verschlüsselte Kopie des Tagebuchs, der privaten Bindungen und der SSH-Autorität in VaultContext. Dafür brauchst du eine VaultContext-Anmeldung und eine entsperrte Sitzung. Der Sicherungspunkt kann das Tagebuch wiederherstellen. Er enthält nicht die Datenbank der Anwendung und keine hochgeladenen Dateien. Die brauchen eine eigene Sicherung.

Ein Betreiber zur Zeit. Die Sperre liegt auf dem Rechner, auf dem PocketDeploy läuft. Sie stimmt nicht zwei Personen auf zwei Rechnern ab.

provider-compute später umzustellen verschiebt den Rechner nicht. Du legst eine neue Bereitstellung an, stellst die Anwendungsdaten mit den eigenen Sicherungsschritten der Anwendung wieder her und stellst das DNS um.

flowchart LR
  yml[colors.yml]
  diary[(.colors.sqlite)]
  machine[Cloud-Rechner]
  appdb[(Anwendungsdatenbank)]
  vault[VaultContext-Sicherungspunkt]

  yml --> machine
  diary --> vault
  appdb -.-> backup[Eigene Sicherung]

Die gepunktete Linie ist Absicht. Den Sicherungspunkt wiederherzustellen stellt appdb nicht wieder her.

Was du einer nutzenden Person gibst

Wenn die Anwendung unter ihrer Adresse antwortet, gib der Person drei Dinge:

Die https://-Origin, oder http://127.0.0.1:PORT, wenn sie nur auf ihrem Rechner liegt.
Die E-Mail-Adresse, die ihr Konto nutzen soll.
Einen Hinweis auf die Anleitung für Nutzende.

Das Superuser-Passwort brauchen sie nicht. Eine Kopie von pb_data brauchen sie nicht.