Manuelle Installation

Dieser Weg installiert dieselbe Opfield-Grundlage wie das öffentliche Installationsprogramm, lädt aber kein Shell-Skript herunter und führt keines aus. Sie installieren Docker, wählen die Opfield-Version, prüfen die Compose-Datei, erstellen Secrets und starten die Dienste selbst. Eine optionale Digest-Prüfung steht für strengere Release-Richtlinien weiterhin zur Verfügung.

Die manuelle Installation ist nützlich, wenn eine Unternehmensrichtlinie verlangt, dass jedes heruntergeladene Artefakt und jeder Befehl separat geprüft wird. Sie ist bewusst ausführlicher als der empfohlene Weg mit dem Installationsprogramm.

Achtung

Verwenden Sie die manuelle Anleitung, die zu dem Opfield-Release gehört, das Sie installieren. Die Dienstgrundlage kann sich zwischen Releases ändern. Bei manuellen Updates müssen Sie alle Änderungen an der Grundlage prüfen; nur die Version zu ändern, ist kein unterstütztes Update-Verfahren.

Was Sie installieren

Die Compose-Grundlage startet fünf Dienste auf einem dedizierten Opfield-Host:

• Opfield-Anwendung – die Weboberfläche, API, Koordination und der persistente Zustand von Opfield;
• Opfield Relay – der authentifizierte Verbindungsweg, den verwaltete Nodes verwenden;
• PostgreSQL – die dauerhafte Anwendungsdatenbank von Opfield;
• Redis – kurzlebiger Koordinations- und Warteschlangenzustand;
• private Registry – Speicher, der von den unterstützten Build-Abläufen von Opfield benötigt wird.

Opfield erhält bewusst Zugriff auf den Docker-Socket des Hosts für signierte Updates, Wiederherstellung, Housekeeping und verwaltete lokale Dienste. Verwenden Sie eine dedizierte vertrauenswürdige VM oder einen dedizierten Host. Betreiben Sie dort keine fremden Workloads und legen Sie dort keine fremden Zugangsdaten ab.

1. Den Host vorbereiten

Beginnen Sie mit einem unterstützten Linux-Host, der die Kapazitäts- und Netzwerkanforderungen erfüllt. Installieren Sie diese Werkzeuge aus den Repositories Ihres Betriebssystems:

• curl;
• jq;
• python3;
• OpenSSL;
• Docker Engine und das Docker-Compose-v2-Plugin.

Installieren Sie Docker aus dem offiziellen Docker-Engine-Repository für Ihre Distribution. Die benötigten Pakete bei Repository-basierten Linux-Installationen sind normalerweise docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin und docker-compose-plugin.

Bestätigen Sie, dass der Daemon und das Compose-Plugin funktionieren, bevor Sie fortfahren:

sudo docker info
sudo docker compose version

Erstellen Sie das Installationsverzeichnis und machen Sie es für den aktuellen Operator beschreibbar:

sudo install -d -m 0750 /opt/opfield
sudo chown "$(id -u):$(id -g)" /opt/opfield
cd /opt/opfield

Alle weiteren Befehle gehen davon aus, dass /opt/opfield das aktuelle Verzeichnis ist.

2. Die Opfield-Version wählen

Die normale manuelle Installation benötigt einen Release-Wert: OPFIELD_VERSION. Verwenden Sie den stabilen Opfield-Release-Tag aus der generierten Umgebungsdatei, ohne Komponentensuffix. Compose leitet daraus die passenden Tags für Opfield, Relay und den Secure-Link-Connector ab.

Wenn Ihre Richtlinie eine kryptografische Prüfung und das Festlegen von Digests verlangt, klappen Sie den optionalen Abschnitt unten auf. Andernfalls fahren Sie mit der Compose-Datei fort und legen die Version in .env fest.

Optional: Signaturen prüfen und exakte Image-Digests festlegen

Das aktuelle stabile Release auswählen

Der Release-Dienst liefert sowohl Opfield-Releases als auch unabhängig versionierte Node-Komponenten. Der folgende Befehl wählt den neuesten Tag ohne Vorschau aus, der nur die Produktversion enthält:

OPFIELD_VERSION="$(
  curl -fsSL https://get.opfield.dev/opfield/releases |
  jq -r '[.[] | select(.prerelease == false and (.tag_name | test("^v[0-9]+\\.[0-9]+\\.[0-9]+$")))] | sort_by(.published_at) | last | .tag_name'
)"
test -n "$OPFIELD_VERSION" && test "$OPFIELD_VERSION" != "null"
RELAY_TAG="${OPFIELD_VERSION}-relay"
printf 'Opfield: %s\nRelay: %s\n' "$OPFIELD_VERSION" "$RELAY_TAG"

Halten Sie die ausgewählte Version in Ihrem Änderungsticket fest. Wenn Sie stattdessen ein bestimmtes freigegebenes Release benötigen, setzen Sie OPFIELD_VERSION und RELAY_TAG ausdrücklich.

Signierte Release-Metadaten herunterladen und prüfen

Laden Sie die beiden kleinen Manifeste herunter. Sie enthalten unveränderliche Image-Digests, keine Container-Zugangsdaten oder Anwendungs-Secrets:

curl -fSLo gateway-image.update.json \
  "https://get.opfield.dev/opfield/opfield/${OPFIELD_VERSION}/gateway-image.update.json"
curl -fSLo relay-image.update.json \
  "https://get.opfield.dev/opfield/relay/${RELAY_TAG}/relay-image.update.json"

Speichern Sie den öffentlichen Schlüssel, mit dem Opfield-Releases signiert werden:

cat > opfield-update-signing-key.pem <<'KEY'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAxLXGD8vCYQCYboK301miZXyAaoOLc43zFVnMlH3FeWg=
-----END PUBLIC KEY-----
KEY

Der folgende sichtbare Python-Befehl wandelt lediglich die Base64URL-Felder des Manifests in die ursprünglichen Payload- und Signaturdateien um. Führen Sie ihn einmal für jedes Manifest aus:

python3 - gateway-image.update.json opfield-release.json opfield-release.sig <<'PY'
import base64, json, pathlib, sys

document = json.loads(pathlib.Path(sys.argv[1]).read_text())
for field, output in (("payload", sys.argv[2]), ("signature", sys.argv[3])):
    value = document[field]
    pathlib.Path(output).write_bytes(
        base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
    )
PY

python3 - relay-image.update.json relay-release.json relay-release.sig <<'PY'
import base64, json, pathlib, sys

document = json.loads(pathlib.Path(sys.argv[1]).read_text())
for field, output in (("payload", sys.argv[2]), ("signature", sys.argv[3])):
    value = document[field]
    pathlib.Path(output).write_bytes(
        base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
    )
PY

Prüfen Sie beide Ed25519-Signaturen. Fahren Sie nicht fort, wenn einer der Befehle Signature Verification Failure meldet:

openssl pkeyutl -verify -rawin -pubin \
  -inkey opfield-update-signing-key.pem \
  -in opfield-release.json -sigfile opfield-release.sig

openssl pkeyutl -verify -rawin -pubin \
  -inkey opfield-update-signing-key.pem \
  -in relay-release.json -sigfile relay-release.sig

Bestätigen Sie nun, dass die signierten Payloads das angeforderte Produkt, die Version und die erwarteten Image-Repositories beschreiben:

jq -e --arg version "$OPFIELD_VERSION" '
  .kind == "gateway-image" and
  .version == $version and
  .image == "ghcr.io/opfield/opfield" and
  .imageRef == (.image + "@" + .digest)
' opfield-release.json

jq -e --arg version "$OPFIELD_VERSION" --arg tag "$RELAY_TAG" '
  .kind == "relay-image" and
  .version == $version and
  .tag == $tag and
  .image == "ghcr.io/opfield/opfield/relay" and
  .imageRef == (.image + "@" + .digest) and
  (.protocolMajor | type) == "number" and
  (.secureLinkConnectorImage | test("^ghcr\\.io/opfield/opfield/secure-link-connector@sha256:[a-f0-9]{64}$"))
' relay-release.json

Diese Prüfungen verhindern, dass ein veränderlicher Tag oder ein unerwartetes Repository in die Installation gelangt. Opfield-Images werden unter ghcr.io/opfield/opfield veröffentlicht. Damit Compose die geprüften Artefakte verwendet, ersetzen Sie die drei abgeleiteten Image-Werte in .env: Kopieren Sie imageRef aus opfield-release.json sowie imageRef und secureLinkConnectorImage aus relay-release.json.

3. Die Compose-Grundlage prüfen

Laden Sie die deklarative Compose-Datei herunter, die diese Anleitung verwendet:

curl -fSLo docker-compose.yml \
  https://docs.opfield.dev/install/docker-compose.manual.yml
less docker-compose.yml

Sie können die Compose-Datei auch im Browser öffnen, bevor Sie sie herunterladen. Prüfen Sie Images, Ports, Volumes, Health Checks, Log-Limits und den Mount des Docker-Sockets. Die Datei ist Konfiguration; sie wird nicht von der Shell ausgeführt. Wie das Installationsprogramm übernimmt sie die per Digest festgelegten Images für PostgreSQL, Redis und die Registry aus .env und stoppt PostgreSQL mit einem Smart Shutdown, damit Opfield zuerst sein eigenes Herunterfahren abschließen kann.

4. Lokale Secrets und Einstellungen erstellen

Laden Sie die Umgebungsvorlage als .env herunter oder öffnen Sie sie im Browser und kopieren Sie sie manuell:

curl -fSLo .env https://docs.opfield.dev/install/opfield.env.example
chmod 600 .env

Öffnen Sie .env in Ihrem Editor und legen Sie das Release fest, das Sie installieren möchten:

OPFIELD_VERSION=v2.12.3

Dieser eine Wert wählt alle drei offiziellen Release-Images aus. Die übrigen Release-Zeilen werden automatisch abgeleitet und müssen nicht bearbeitet werden. Ersetzen Sie die drei Image-Zeilen nur, wenn Sie den Prüfabschnitt durchlaufen haben und exakte Digests festlegen möchten.

Ersetzen Sie die übrigen drei Werte REPLACE_WITH_... durch lokal erzeugte Secrets:

openssl rand -hex 24  # DB_PASSWORD
openssl rand -hex 32  # PKI_MASTER_KEY
openssl rand -hex 32  # OPFIELD_REGISTRY_HTTP_SECRET

Bevor Sie fortfahren, darf dieser Befehl nichts ausgeben:

grep -n 'REPLACE_WITH_' .env

Die erzeugten Secrets verlassen Ihren Host nur, wenn Sie sie an einen anderen Ort kopieren.

Die Vorlage legt PostgreSQL, Redis und die Registry per Digest auf den Opfield-Image-Mirror auf ghcr.io fest. Wenn der Host ghcr.io nicht erreichen kann, ersetzen Sie diese drei Zeilen durch die Docker-Hub-Referenzen derselben Digests, die in den Kommentaren der Vorlage aufgeführt sind.

Internes HTTPS ist die sichere Voreinstellung. Wenn ein vertrauenswürdiger Reverse Proxy TLS terminiert und die interne Strecke bewusst unverschlüsselt ist, ändern Sie vor dem ersten Start WEB_TLS_BOOTSTRAP_MODE=https in WEB_TLS_BOOTSTRAP_MODE=http.

Behandeln Sie .env und die persistenten Volumes als sensiblen Installationszustand. Sichern Sie sie gemäß Updates und Backups, fügen Sie ihren Inhalt aber niemals in Chats oder Tickets ein.

5. Opfield validieren und starten

Lassen Sie Compose die vollständige Konfiguration rendern und validieren, bevor ein Image bezogen wird:

sudo docker compose config --quiet

Beziehen Sie dann die geprüften Images und starten Sie den Stack:

sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

Der erste Start kann mehrere Minuten dauern, während Images heruntergeladen und der persistente Zustand initialisiert wird. Sehen Sie sich nur begrenzte Logs an, wenn ein Dienst nicht fehlerfrei startet:

sudo docker compose logs --tail=200 app relay postgres redis registry

Löschen Sie keine Volumes und erzeugen Sie .env nicht neu, um einen Startfehler zu beheben. Ermitteln Sie zuerst den fehlgeschlagenen Dienst und bewahren Sie die ursprünglichen Belege.

6. Zustand prüfen und den Einrichtungscode abrufen

Prüfen Sie im voreingestellten internen HTTPS-Modus den lokalen Endpunkt:

curl -kfsS https://127.0.0.1:3000/health

Lassen Sie bei einer bewussten HTTP-Installation -k weg und verwenden Sie http://.

Erzeugen Sie den einmaligen Einrichtungscode aus dem laufenden Anwendungscontainer:

sudo docker compose exec -T app node dist/cli/setup-code.js

Die Ausgabe enthält den Code, seinen Ablaufzeitpunkt und den Fingerabdruck der Opfield System CA. Geben Sie den Code nur auf der Opfield-Einrichtungsseite ein. Speichern Sie ihn nicht in einem Ticket, einem Chat, im Befehlsverlauf oder auf einem Screenshot.

Fahren Sie mit der Ersteinrichtung fort. Opfield vermerkt den Abschluss der Einrichtung und bietet den Einrichtungsassistenten nach einer erfolgreichen Konfiguration nicht erneut an.

Checkliste für die manuelle Installation

• Docker Engine und Compose v2 stammen aus einem freigegebenen Repository.
• OPFIELD_VERSION benennt ein freigegebenes stabiles Release.
• Wenn Digests festgelegt wurden, haben beide Signaturen die Prüfung bestanden und alle drei Überschreibungen stammen aus den geprüften Payloads.
• docker-compose.yml wurde vor der Verwendung geprüft.
• .env hat den Modus 600 und wurde nicht in ein unsicheres System kopiert.
• Alle fünf Dienste laufen und die benötigten Health Checks sind erfolgreich.
• Der Einrichtungscode wurde nur in der Opfield-Browsersitzung eingegeben.
• Kanonische URL, DNS, Authentifizierung und erster Administrator wurden geprüft, bevor Produktions-Nodes hinzugefügt wurden.