Installation manuelle

Ce chemin installe la même base Opfield que l’installateur public, mais sans télécharger ni exécuter de script shell. Vous installez Docker, choisissez la version d’Opfield, inspectez le fichier Compose, créez les secrets et démarrez les services vous-même. Une vérification facultative des empreintes reste disponible pour les politiques de version plus strictes.

L’installation manuelle est utile lorsque la politique de l’entreprise exige que chaque artefact téléchargé et chaque commande soient examinés séparément. Elle est volontairement plus détaillée que le chemin d’installation recommandé.

Attention

Utilisez le guide manuel qui correspond à la version d’Opfield que vous installez. La base de services peut changer d’une version à l’autre. Les mises à jour manuelles vous imposent d’examiner les changements de la base ; modifier uniquement la version n’est pas une procédure de mise à jour prise en charge.

Ce que vous allez installer

La base Compose démarre cinq services sur un hôte Opfield dédié :

• application Opfield — l’interface web, l’API, la coordination et l’état persistant d’Opfield ;
• Opfield Relay — le chemin de connexion authentifié utilisé par les nœuds gérés ;
• PostgreSQL — la base de données applicative durable d’Opfield ;
• Redis — l’état de coordination et de files d’attente de courte durée ;
• registre privé — le stockage requis par les processus de build Opfield pris en charge.

Opfield reçoit intentionnellement l’accès au socket Docker de l’hôte pour les mises à jour signées, la reprise, les tâches de maintenance et les services locaux managés. Utilisez une VM ou un hôte de confiance dédié. N’y placez pas de charges de travail ni d’identifiants sans rapport.

1. Préparer l’hôte

Partez d’un hôte Linux pris en charge qui répond aux exigences de capacité et de réseau. Installez ces outils depuis les dépôts de votre système d’exploitation :

• curl ;
• jq ;
• python3 ;
• OpenSSL ;
• Docker Engine et le plugin Docker Compose v2.

Installez Docker depuis le dépôt officiel Docker Engine de votre distribution. Les paquets requis sur les installations Linux basées sur un dépôt sont normalement docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin et docker-compose-plugin.

Vérifiez que le démon et le plugin Compose fonctionnent avant de continuer :

sudo docker info
sudo docker compose version

Créez le répertoire d’installation et rendez-le accessible en écriture à l’opérateur actuel :

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

Toutes les commandes suivantes supposent que /opt/opfield est le répertoire courant.

2. Choisir la version d’Opfield

L’installation manuelle normale nécessite une seule valeur de version : OPFIELD_VERSION. Utilisez le tag de version stable d’Opfield indiqué dans le fichier d’environnement généré, sans suffixe de composant. Compose en déduit les tags correspondants d’Opfield, de Relay et du connecteur Secure Link.

Si votre politique exige une vérification cryptographique et l’épinglage par empreinte, dépliez la section facultative ci-dessous. Sinon, passez au fichier Compose et définissez la version dans .env.

Facultatif : vérifier les signatures et épingler les empreintes exactes des images

Sélectionner la version stable actuelle

Le service de versions renvoie à la fois les versions d’Opfield et les composants de nœuds versionnés indépendamment. La commande ci-dessous sélectionne le tag hors préversion le plus récent qui ne contient que la version du produit :

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"

Consignez la version sélectionnée dans votre ticket de changement. Si vous avez besoin d’une version approuvée précise, définissez explicitement OPFIELD_VERSION et RELAY_TAG.

Télécharger et vérifier les métadonnées de version signées

Téléchargez les deux petits manifestes. Ils contiennent des empreintes d’images immuables, et non des identifiants de conteneurs ou des secrets applicatifs :

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"

Enregistrez la clé publique de signature des versions d’Opfield :

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

La commande Python visible ci-dessous se contente de convertir les champs Base64URL du manifeste en fichiers de charge utile et de signature d’origine. Exécutez-la une fois pour chaque manifeste :

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

Vérifiez les deux signatures Ed25519. Ne continuez pas si l’une des commandes signale Signature Verification Failure :

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

Confirmez ensuite que les charges utiles signées décrivent le produit, la version et les dépôts d’images attendus :

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

Ces vérifications empêchent un tag modifiable ou un dépôt inattendu d’entrer dans l’installation. Les images Opfield sont publiées dans ghcr.io/opfield/opfield. Pour que Compose utilise les artefacts vérifiés, remplacez les trois valeurs d’images déduites dans .env : copiez imageRef depuis opfield-release.json, ainsi que imageRef et secureLinkConnectorImage depuis relay-release.json.

3. Inspecter la base Compose

Téléchargez le fichier Compose déclaratif utilisé par ce guide :

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

Vous pouvez aussi ouvrir le fichier Compose dans le navigateur avant de le télécharger. Examinez les images, les ports, les volumes, les vérifications de santé, les limites de journaux et le montage du socket Docker. Ce fichier est une configuration ; il n’est pas exécuté par le shell. Comme l’installateur, il prend les images de PostgreSQL, Redis et du registre dans .env, épinglées par empreinte, et arrête PostgreSQL par un arrêt « smart » afin qu’Opfield puisse d’abord terminer son propre arrêt.

4. Créer les secrets et les paramètres locaux

Téléchargez le modèle d’environnement sous le nom .env, ou ouvrez-le dans le navigateur et copiez-le manuellement :

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

Ouvrez .env dans votre éditeur et définissez la version à installer :

OPFIELD_VERSION=v2.12.3

Cette seule valeur sélectionne les trois images officielles de la version. Les autres lignes de version sont déduites automatiquement et n’ont pas besoin d’être modifiées. Ne remplacez les trois lignes d’images que si vous avez effectué la vérification de la section dépliable et souhaitez un épinglage exact par empreinte.

Remplacez les trois valeurs REPLACE_WITH_... restantes par des secrets générés localement :

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

Avant de continuer, cette commande ne doit rien afficher :

grep -n 'REPLACE_WITH_' .env

Les secrets générés ne quittent jamais votre hôte, sauf si vous les copiez ailleurs.

Le modèle épingle PostgreSQL, Redis et le registre par empreinte sur le miroir d’images Opfield de ghcr.io. Si l’hôte ne peut pas joindre ghcr.io, remplacez ces trois lignes par les références Docker Hub des mêmes empreintes, indiquées dans les commentaires du modèle.

Le HTTPS interne est l’option sûre par défaut. Si un reverse proxy de confiance doit terminer TLS et que le saut interne est intentionnellement en clair, remplacez WEB_TLS_BOOTSTRAP_MODE=https par WEB_TLS_BOOTSTRAP_MODE=http avant le premier démarrage.

Considérez .env et les volumes persistants comme un état d’installation sensible. Sauvegardez-les conformément à Mises à jour et sauvegardes, mais ne collez jamais leur contenu dans une discussion ou un ticket.

5. Valider et démarrer Opfield

Demandez à Compose de produire et de valider la configuration complète avant de récupérer la moindre image :

sudo docker compose config --quiet

Récupérez ensuite les images vérifiées et démarrez la pile :

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

Le premier démarrage peut prendre plusieurs minutes, le temps de télécharger les images et d’initialiser l’état persistant. Si un service ne devient pas sain, n’examinez que des journaux limités :

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

Ne supprimez pas de volumes et ne régénérez pas .env pour corriger une erreur de démarrage. Identifiez d’abord le service en échec et préservez les éléments de preuve d’origine.

6. Vérifier la santé et obtenir le code de configuration

Pour le mode HTTPS interne par défaut, vérifiez le point de terminaison local :

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

Pour une installation HTTP délibérée, omettez -k et utilisez http://.

Générez le code de configuration à usage unique depuis le conteneur de l’application en cours d’exécution :

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

La sortie comprend le code, son heure d’expiration et l’empreinte de la System CA d’Opfield. Saisissez le code uniquement dans la page de configuration d’Opfield. Ne le conservez pas dans un ticket, une discussion, l’historique des commandes ou une capture d’écran.

Poursuivez avec la configuration initiale. Opfield enregistre la fin du processus de configuration et ne proposera plus l’assistant d’amorçage après une configuration réussie.

Liste de contrôle de l’installation manuelle

• Docker Engine et Compose v2 proviennent d’un dépôt approuvé.
• OPFIELD_VERSION désigne une version stable approuvée.
• Si l’épinglage par empreinte a été activé, les deux signatures ont été validées et les trois remplacements proviennent des charges utiles vérifiées.
• docker-compose.yml a été examiné avant utilisation.
• .env est en mode 600 et n’a pas été copié vers un système non sûr.
• Les cinq services sont en cours d’exécution et les vérifications de santé requises réussissent.
• Le code de configuration n’a été saisi que dans la session de navigateur Opfield.
• L’URL canonique, le DNS, l’authentification et le premier administrateur ont été vérifiés avant l’ajout de nœuds de production.