NextPDF Gotenberg 설치

한눈에 보기

브리지 설치는 두 부분으로 이루어집니다. 첫 번째는 PHP 패키지와 해당 PSR HTTP 의존성이며 Composer로 설치합니다. 두 번째는 패키지가 호출하는 Gotenberg 서비스입니다. 브리지는 변환 작업을 이 서비스에 넘기므로, Gotenberg 인스턴스에 도달할 수 없으면 어떤 변환도 수행할 수 없습니다.

변환 코드를 작성하기 전에 두 부분을 모두 준비합니다.

요구 사항

요구 사항	제약 조건	이유
PHP	>=8.4 <9.0	패키지는 composer.json에서 이 범위를 선언합니다.
NextPDF core	^3.0	composer.json에 선언된 직접 의존성입니다.
PSR-18 HTTP 클라이언트	^1.0	브리지는 주입된 Psr\Http\Client\ClientInterface를 통해 요청을 보냅니다.
PSR-17 HTTP 팩토리	^1.1	브리지는 주입된 PSR-17 팩토리를 통해 요청과 스트림을 생성합니다.
PSR-3 로거	^3.0 (선택 사항)	요청 수준의 디버그 로깅을 위해 로거를 주입할 수 있습니다.
Gotenberg 서비스	HTTPS로 도달 가능	변환은 이 패키지가 아니라 외부 서비스에 의해 수행됩니다.

브리지는 PSR-18 클라이언트나 PSR-17 팩토리를 함께 제공하지 않습니다. 구현체는 직접 선택해야 합니다. 예를 들어 Guzzle 기반 클라이언트를 해당 PSR-17 팩토리와 함께 사용하거나, Symfony HTTP 클라이언트를 nyholm/psr7과 함께 사용할 수 있습니다. 브리지는 특정 라이브러리가 아니라 인터페이스에만 의존하므로, 관련 PSR 계약을 준수하는 구현체라면 무엇이든 동작합니다.

1 단계 — 패키지 설치

Composer로 패키지를 추가합니다:

composer require nextpdf/gotenberg

이 명령은 nextpdf/core ^3.0과 PSR HTTP 계약인 psr/http-client, psr/http-factory, psr/log를 해결합니다. 구체적인 HTTP 클라이언트는 설치하지 않습니다.

2 단계 — PSR-18 클라이언트와 PSR-17 팩토리 설치

PSR-18 클라이언트 하나와 그에 맞는 PSR-17 팩토리 세트를 설치합니다. Guzzle을 사용하는 경우:

composer require guzzlehttp/guzzle guzzlehttp/psr7

또는 Symfony HTTP 클라이언트와 Nyholm PSR-7을 사용하는 경우:

composer require symfony/http-client nyholm/psr7

브리지는 이들을 생성자 인수로 받습니다. HTTP 클라이언트를 직접 생성하지 않습니다. 따라서 어떤 구현체를 사용할지는 전적으로 사용자에게 달려 있으며, 브리지를 연결할 때 그 선택을 반영합니다. 생성자 형태는 /integrations/gotenberg/configuration/를, 완전한 연결 예시는 /integrations/gotenberg/quickstart/를 참고합니다.

3 단계 — Gotenberg 서비스 준비

브리지는 Gotenberg의 LibreOffice 변환 경로를 호출하므로, 브리지가 도달할 수 있는 Gotenberg 인스턴스가 필요합니다. 업스트림 프로젝트는 컨테이너 이미지를 게시합니다. 로컬 개발을 위한 표준 명령은 다음과 같습니다:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

이 명령은 Gotenberg를 일반 HTTP로 포트 3000에 노출하며, 이 방식은 로컬 개발에만 적합합니다. 브리지는 구성된 API URL에 대해 HTTPS를 요구합니다. 브리지는 요청을 보내기 전에 일반 http://를 거부합니다. 로컬 실험을 넘어서는 경우에는 Gotenberg를 TLS를 종료하는 리버스 프록시나 서비스 메시 뒤에 배치한 다음, 브리지가 HTTPS 엔드포인트를 가리키도록 합니다. /integrations/gotenberg/security-and-operations/에서는 프로덕션 배포 형태, 네트워크 노출, 인증을 다룹니다.

여기에 표시된 이미지 태그(gotenberg/gotenberg:8)는 업스트림 Gotenberg 메이저 라인을 가리킵니다. 이 프로젝트의 자체 README와 통합 기준선은 해당 라인을 참조합니다. 프로덕션에서는 이동하는 메이저 태그를 추적하기보다 특정 패치 태그로 고정합니다. 또한 배포하는 Gotenberg 버전에 대해 경로(/forms/libreoffice/convert, /health)를 검증합니다. 브리지는 이 두 경로를 가정하며, 서비스에 대해 그 밖의 어떤 가정도 하지 않습니다.

4 단계 — 연결 검증

이제 패키지와 HTTP 클라이언트가 설치되었고, Gotenberg에 HTTPS로 도달할 수 있습니다. 실제 변환을 시도하기 전에 내장 상태 프로브로 브리지에서 서비스가 보이는지 확인합니다:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(apiUrl: 'https://gotenberg.example.com');

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable()은 먼저 구성된 URL을 검증합니다. URL이 비어 있거나, HTTPS가 아니거나, 사설 주소인 경우에는 네트워크 트래픽을 전혀 발생시키지 않고 false를 반환합니다. 그런 다음 <apiUrl>/health로 HEAD 요청을 보내고, 상태가 500 미만이면 서비스를 사용할 수 있다고 보고합니다. 네트워크 오류는 던져지지 않고 포착되어 사용 불가로 보고됩니다.

버전 참고

이 문서는 패키지를 ^3.0 라인 기준으로 설명합니다. 이 라인은 composer.json 요구 사항 및 SECURITY.md 지원 매트릭스와 일치하며, 해당 매트릭스에서는 3.x는 지원되고 2.x는 지원되지 않습니다. 저장소 내 스켈레톤 페이지의 이전 0.x 참조는 3.0 라인보다 앞선 것이며, composer.json 제약이 이를 대체합니다.

함께 보기

• /integrations/gotenberg/overview/ — 브리지가 수행하는 일과 변환 형식.
• /integrations/gotenberg/configuration/ — 모든 생성자 인수와 구성 필드.
• /integrations/gotenberg/quickstart/ — 완전하며 실행 가능한 첫 변환.
• /integrations/gotenberg/security-and-operations/ — Gotenberg 의존성을 안전하게 운영하는 방법.
• /integrations/gotenberg/boot-and-discovery/ — 프레임워크 자동 연결.