NextPDF Connect implementeren

In het kort

REST- en gRPC-transports draaien in RoadRunner-workerpools. Het pakket bevat drie RoadRunner-profielen: alleen HTTP, alleen gRPC en een gecombineerd profiel. Het MCP-transport draait als een normaal subproces en heeft geen supervisor nodig.

Installeren

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

Conceptueel overzicht

RoadRunner is de processupervisor. Die beheert de workerpool, herstart workers bij geheugendruk en routeert elk verzoek naar een beschikbare worker. Het PHP-pakket levert het worker-instappunt: bin/nextpdf-server voor HTTP en bin/nextpdf-grpc voor gRPC. RoadRunner plaatst dat instappunt in een pool. Elke worker verwerkt één verzoek tegelijk.

Het MCP-transport werkt anders. bin/nextpdf-mcp is één enkel PHP-proces. Het communiceert via JSON-RPC over stdio en wordt rechtstreeks door de client gestart.

API-oppervlak

RoadRunner-profielen

Profiel	Transports	Commando
`.rr.yaml`	Alleen REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	Alleen gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Het HTTP-profiel bindt de REST-listener aan 0.0.0.0:8080. Het stelt een status-endpoint beschikbaar op :2114 en metrics op :2112. Het bepaalt de grootte van de workerpool op basis van NEXTPDF_WORKER_COUNT, standaard vier. In de meegeleverde profielen beperkt de supervisor elke worker tot 256 MB.

Het gecombineerde profiel voegt de gRPC-workerpool toe op tcp://0.0.0.0:9090. Het bepaalt de grootte van die pool op basis van NEXTPDF_GRPC_WORKER_COUNT, standaard twee. Daarnaast configureert het gRPC met wederzijdse TLS.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Draai een productiecontainer met het gecombineerde profiel, bestandsgebaseerde sleutels en gedeelde Redis-gebaseerde stores:

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

Randgevallen en valkuilen

In-memory stores worden niet tussen meerdere workers gedeeld. Zonder Redis houdt elke worker zijn eigen rate-limitstores, idempotentiestores en documentstores bij. In een pool met meerdere workers leiden in-memory stores tot inconsistente rate limiting en kunnen er documenten tussen workers verloren gaan. Stel voor elke pool met meer dan één worker NEXTPDF_REDIS_HOST in en installeer ext-redis. De server valt automatisch terug op in-memory stores als de Redis-verbinding mislukt. Controleer de Redis-gezondheid; ga er niet zomaar van uit dat Redis gezond is.
De jobstore is SQLite in WAL-modus. Async jobs worden bewaard in één SQLite-bestand dat door alle HTTP-workers en gRPC-workers wordt gedeeld. Plaats dat bestand op een volume waarop alle workers kunnen schrijven. Wanneer een worker afsluit, markeert hij zijn nog lopende jobs op best-effort-basis als mislukt, zodat die jobs niet verweesd achterblijven.
bin/nextpdf-prune is een onderhoudsinstappunt. Het wordt meegeleverd in de repository, niet in vendor/bin/. Roep het rechtstreeks aan om stores op te schonen. Het is geen servertransport.
De PHP-versie in het image heeft mogelijk geen ext-redis. De meegeleverde Dockerfile bouwt ext-redis op best-effort-basis. De build gaat verder zonder de extensie als er geen compatibele release bestaat voor de basis-PHP. Controleer of de extensie aanwezig is in het draaiende image voordat je op Redis-gebaseerde stores vertrouwt.

Prestaties

Stel NEXTPDF_WORKER_COUNT in op basis van de beschikbare CPU en het beschikbare geheugen. Elke worker is een PHP-proces dat wordt begrensd door het geheugenplafond van de supervisor. Begin voor renderintensieve workloads met één worker per core en stem vervolgens af op basis van het metrics-endpoint. Bepaal de grootte van de gRPC-pool onafhankelijk. Die is doorgaans kleiner dan de HTTP-pool, omdat gRPC-clients meestal minder talrijk zijn en langer actief blijven.

Beveiligingsnotities

gRPC met wederzijdse TLS

Het gecombineerde profiel configureert het gRPC-transport voor wederzijdse Transport Layer Security (TLS): de server presenteert een certificaat en vereist daarna een clientcertificaat en verifieert dat. Lever de serversleutel, het servercertificaat en de client-CA als deployment-secrets aan, niet in het image ingebakken. Genereer en roteer ze buiten de band; draai het gRPC-transport niet met een plaintext-listener op een onvertrouwd netwerk.

REST TLS-terminatie

Het REST-profiel bindt een plaintext-HTTP-listener. Termineer TLS daarvoor met een reverse proxy, load balancer of service mesh en bind de listener alleen aan het interne netwerk. Geef de clientidentiteit ongewijzigd door via de Authorization-header; de server voert zijn eigen sleutelvalidatie uit. De listener biedt op zichzelf geen veilig transport; deze deployment-configuratie wel.

Secrets

Koppel API-sleutels door NEXTPDF_API_KEYS_FILE naar een secret-bestand te laten verwijzen, in plaats van de inline variabele NEXTPDF_API_KEYS te gebruiken. De bestandsgebaseerde store laadt bij wijzigingen direct opnieuw, zodat rotatie geen herstart vereist. Bak nooit sleutels of privé TLS-materiaal in het image. Zie /connect/security-and-operations/.

Conformiteit

Het deployment-mechanisme doet geen normatieve protocolbeweringen. Citaten voor authenticatie en transportbeveiliging zijn vastgelegd op /connect/security-and-operations/.

Commerciële context

Installeer nextpdf/premium in het image om de aanvullende Pro-tools en Enterprise-tools binnen dezelfde workers te registreren. Er is geen apart proces of poort bij betrokken. De packaging-grens bepaal je tijdens het bouwen van het image.

Zie ook

/connect/configuration/ — workeraantal, Redis en niveauplafonds
/connect/security-and-operations/ — TLS, wederzijdse TLS, secrets, dreigingsmodel
/transports/rest/ · /transports/grpc/ — runtimedetails per transport
/connect/production-usage/ — health probes, schalen en observability
/connect/troubleshooting/ — worker-fouten, store-fouten en auth-fouten diagnosticeren