Déployer NextPDF Connect

En bref

Les transports REST et gRPC s’exécutent dans des pools de workers RoadRunner. Le package fournit trois profils RoadRunner : HTTP seul, gRPC seul et un profil combiné. Le transport MCP s’exécute comme un simple sous-processus et n’a besoin d’aucun superviseur.

Installation

composer require nextpdf/server
./vendor/bin/rr get-binary

Vue d’ensemble conceptuelle

RoadRunner est le superviseur de processus. Il gère le pool de workers, redémarre les workers en cas de pression mémoire et achemine chaque requête vers un worker libre. Le package PHP fournit le point d’entrée du worker : bin/nextpdf-server pour HTTP et bin/nextpdf-grpc pour gRPC. RoadRunner construit le pool autour de ce point d’entrée. Chaque worker traite une requête à la fois.

Le transport MCP fonctionne différemment. bin/nextpdf-mcp est un unique processus PHP. Il parle JSON-RPC sur stdio, et le client le lance directement.

Surface d’API

Profils RoadRunner

Profil	Transports	Commande
`.rr.yaml`	REST seul	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	gRPC seul	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Le profil HTTP attache l’écouteur REST à 0.0.0.0:8080. Il expose un endpoint de statut sur :2114 et les métriques sur :2112. Il dimensionne le pool de workers à partir de NEXTPDF_WORKER_COUNT, dont la valeur par défaut est quatre. Le superviseur limite la mémoire par worker à 256 MB dans les profils livrés.

Le profil combiné ajoute le pool de workers gRPC sur tcp://0.0.0.0:9090, dimensionné à partir de NEXTPDF_GRPC_WORKER_COUNT, dont la valeur par défaut est deux. Il configure aussi le TLS mutuel gRPC.

Exemple de code — Démarrage rapide

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Exemple de code — Production

Lance un conteneur de production avec le profil combiné, des clés stockées dans un fichier et des stores partagés adossés à Redis :

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

Cas limites et pièges

Les stores en mémoire ne se partagent pas entre plusieurs workers. Sans Redis, chaque worker conserve ses propres stores de rate-limit, d’idempotence et de documents. Un pool multi-workers avec des stores en mémoire entraîne un rate limiting incohérent et des pertes de documents entre workers. Dès qu’un pool dépasse un seul worker, définis NEXTPDF_REDIS_HOST et installe ext-redis. Le serveur se replie automatiquement sur la mémoire si la connexion Redis échoue. Vérifie la santé de Redis ; ne la suppose pas.
Le store de jobs utilise SQLite en mode WAL. Les jobs asynchrones sont persistés dans un seul fichier SQLite partagé par tous les workers HTTP et gRPC. Place ce fichier sur un volume accessible en écriture par tous les workers. Quand un worker s’arrête, il marque dans la mesure du possible ses jobs encore en cours comme échoués, afin que ces jobs ne restent pas orphelins.
bin/nextpdf-prune est un point d’entrée de maintenance. Il est livré dans le dépôt, pas dans vendor/bin/. Invoque-le directement pour les tâches de purge des stores. Ce n’est pas un transport de serveur.
La version PHP de l’image peut ne pas disposer de ext-redis. Le Dockerfile livré construit ext-redis dans la mesure du possible. Il continue sans l’extension si aucune version compatible n’existe pour le PHP de base. Confirme la présence de l’extension dans l’image en cours d’exécution avant de compter sur les stores adossés à Redis.

Performances

Dimensionne NEXTPDF_WORKER_COUNT en fonction du CPU et de la mémoire disponibles. Chaque worker est un processus PHP soumis au plafond mémoire du superviseur. Pour les charges de travail très intensives en rendu, commence avec un worker par cœur, puis ajuste en fonction de l’endpoint de métriques. Dimensionne le pool gRPC indépendamment. Il est généralement plus petit que le pool HTTP, car les clients gRPC sont habituellement moins nombreux et restent connectés plus longtemps.

Notes de sécurité

TLS mutuel gRPC

Le profil combiné configure le transport gRPC avec TLS mutuel : le serveur présente un certificat, et exige puis vérifie un certificat client. La clé du serveur, le certificat du serveur et la CA cliente sont fournis comme secrets de déploiement, sans être intégrés dans l’image. Gère leur génération et leur rotation hors bande ; n’exécute pas le transport gRPC avec un écouteur en clair sur un réseau non fiable.

Terminaison TLS pour REST

Le profil REST attache un écouteur HTTP en clair. Termine le TLS en amont — via un reverse proxy, un répartiteur de charge ou un service mesh — et attache l’écouteur uniquement au réseau interne. Transmets l’identité du client via l’en-tête Authorization sans le modifier ; le serveur effectue sa propre validation de clé. L’écouteur ne fournit pas à lui seul un transport sécurisé ; c’est la configuration de déploiement qui l’apporte.

Secrets

Monte les clés d’API via NEXTPDF_API_KEYS_FILE, qui pointe vers un fichier de secret, plutôt qu’avec la variable inline NEXTPDF_API_KEYS ; le store basé sur fichier se recharge à chaud lorsqu’il change, si bien que la rotation ne nécessite aucun redémarrage. N’intègre jamais de clés ni de matériel privé TLS dans l’image. Voir /connect/security-and-operations/.

Conformité

Le mécanisme de déploiement ne formule aucune revendication normative de protocole. Les citations d’authentification et de sécurité du transport sont rattachées à /connect/security-and-operations/.

Contexte commercial

Installe nextpdf/premium dans l’image pour enregistrer les outils Pro et Enterprise supplémentaires dans les mêmes workers. Aucun processus ni port distinct n’est nécessaire. La frontière de packaging est fixée au moment de la construction de l’image.

Voir aussi

/connect/configuration/ — nombre de workers, Redis et plafonds de niveau
/connect/security-and-operations/ — TLS, TLS mutuel, secrets, modèle de menace
/transports/rest/ · /transports/grpc/ — détails d’exécution par transport
/connect/production-usage/ — sondes de santé, mise à l’échelle et observabilité
/connect/troubleshooting/ — diagnostic des défaillances de worker, de store et d’authentification