Für die Verwendung von Puppeteer zum Rendern von mehrseitigen HTML-Dokumenten wurde ein Runtime-Image bereitgestellt:

registry.brandbox.host/runtime/puppeteer:1.0.0

Enthaltene Software

Software	Version
Debian	10
Node.js	14.21.3

Konfiguration für `docker-compose.yml`

Das Image kann in einer docker-compose.yml wie folgt eingebunden werden:

puppeteer:
    image: registry.brandbox.host/runtime/puppeteer:1.0.0
    domainname: local.brandbox.de
    volumes:
      - /mnt/nfsstorage/${COMPOSE_PROJECT_NAME}/temp:/var/www/temp/
      - /mnt/nfsstorage/${COMPOSE_PROJECT_NAME}/share:/var/www/share/
    env_file:
      - brandbox.docker.env
    working_dir: /var/www
    networks:
      internal:
        aliases:
          - puppeteer.${COMPOSE_PROJECT_NAME}
    labels:
      traefik.enable: "false"
    ports:
      - "8080"

Die Umgebungsvariablen PUPPETEER_HOST und PUPPETEER_PROTOCOL müssen wie folgt befüllt werden:

Umgebungsvariable	Wert
`PUPPETEER_HOST`	`puppeteer.${COMPOSE_PROJECT_NAME}:8080` Die Definition dieser Umgebungsvariable sollte über die `docker-compose.yml` vorgenommen werden.
`PUPPETEER_PROTOCOL`	`http`

Cluster-Konfiguration (Kubernetes)

Es muss ein Deployment mit dem Image registry.brandbox.host/runtime/puppeteer:1.0.0 eingerichtet werden
Es muss ein Service mit dem Namen service-puppeteer eingerichtet werden, der auf dieses Deployment verweist

Die Umgebungsvariablen PUPPETEER_HOST und PUPPETEER_PROTOCOL müssen wie folgt befüllt werden

Umgebungsvariable	Wert
`PUPPETEER_HOST`	`service-puppeteer:8080`
`PUPPETEER_PROTOCOL`	`http`

Diese Standardwerte existieren bereits im Rancher-Manager und werden beim Redeploy über die Gitlab-Pipeline automatisch gesetzt.

Verwendung

Das Image stellt verschiedene HTTP-Schnittstellen zur Verarbeitung von HTML-Dokumenten zur Verfügung.

`GET https://[HOSTNAME]:8080/puppeteer?source=[SOURCE]&target=[TARGET]`

Mit dieser Schnittstelle kann ein HTML-Dokument auf einzelne Seiten verteilt und abgelegt werden.

Parameter (`GET`)

Bezeichnung	Beschreibung
`source`	Das zu verarbeitende HTML-Dokument. Die Angabe erfolgt als URL und kann entweder ein Dateipfad oder eine Webadresse darstellen. Dateipfad (bspw. in einem eingehangenen Volume): `file:///var/www/share/private/document.html` Webadresse: `https://[HOSTNAME]/something/something.html?optional=parameter`
`target`	Ein Ordnerpfad für die Ablage des verarbeiteten HTML-Dokuments. Es wird immer ein Gesamtdokument sowie die Einzelseiten abgelegt.
`timeout` OPTIONAL	Die Anzahl an Millisekunden, die der Verarbeitungsprozess auf eine Reaktion wartet. Standardmäßig wird hier `60.000` für 60 Sekunden gesetzt.
`request` OPTIONAL	Die Anzahl an Millisekunden, die der Verarbeitungsprozess auf das Quelldokument (`source`-Parameter) wartet. Standardmäßig wird hier `30.000` für 30 Sekunden gesetzt.
`abort` OPTIONAL	Wird dieser Parameter definiert und enthält den Wert `1`, wird der Verarbeitungsprozess bei einem Fehler sofort abgebrochen. Andernfalls werden Fehlermeldungen zwar protokolliert aber übergangen.

Rückgabewerte (`JSON`)

Bezeichnung		Beschreibung
`result`		Im Erfolgsfall `true`, andernfalls `false`.
`log`		Eine Zusammenfassung des Verarbeitungsprozesses sowie Zusatzinformationen für eine Protokollierung. Diese Information wird als JSON-Objekt übergeben.
	`source`	Die im `source`-Parameter übergebene URL zum Quelldokument.
	`target`	Der im `target`-Parameter übergebene Ordnerpfad für die Ablage der verarbeiteten Dokumente.
	`requests`	Die innerhalb des Verarbeitungsprozesses ausgeführten HTTP-Anfragen und deren Ergebnisse (Status oder Fehlertext).
	`messages`	Die innerhalb des Verarbeitungsprozesses eingesammelten Logmeldungen sowie deren Typ.
	`duration`	Laufzeit des Verarbeitungsprozesses in Sekunden.
	`additional`	Zusatzinformationen aus der Anfrage oder dem Verarbeitungsprozess.

Beispiel

// GET http://[HOSTNAME]:8080/puppeteer?source=https%3A%2F%2Fexample.com%2Fsomething%2Fsomething.html&target=%2Fvar%2Fwww%2Fshare%2Fprivate%2Fexample

{
	"result": true,
	"log": {
		"source": "https://example.com/something/something.html",
		"target": "/var/www/share/private/example",
		"requests": {
			"https://example.com/something/something.html": 200,
			"https://example.com/style.css": 200,
			// ...
		},
		"messages": {
			{
				"type": "info",
				"text": "[document] waiting for document"
			},
			{
				"type": "info",
				"text": "[document] creating page 1"
			},
			// ...
			{
				"type": "info",
				"text": "[document] finished document"
			},
			// ...
		},
		"duration": 37.4,
		"additional": {/* ... */},
	}
}

`POST https://[HOSTNAME]:8080/pdf`

Diese Schnittstelle verteilt ein HTML-Dokument auf mehrere Seite und speichert das Ergebnis als PDF-Dokument.

Das erzeugte PDF-Dokument erfüllt nicht die Anforderungen eines Druck-PDF-Dokuments.

Anfrageinhalt (`JSON`)

Bezeichnung			Typ	Beschreibung
`source`			`string`	Das zu verarbeitende HTML-Dokument. Die Angabe erfolgt als URL und kann entweder ein Dateipfad oder eine Webadresse darstellen. Dateipfad (bspw. in einem eingehangenen Volume): `file:///var/www/share/private/document.html` Webadresse: `https://[HOSTNAME]/something/something.html?optional=parameter`
`target`			`string`	Ein Ordnerpfad für die Ablage des verarbeiteten HTML-Dokuments. Es wird immer ein Gesamtdokument sowie die Einzelseiten abgelegt.
`configuration`			`object`
	`options`		`object`
		`abort`	`boolean`	Wird diese Option auf `true` gesetzt, bricht der Verarbeitungsprozess bei einem Platzierungsfehler direkt ab.
		`debug`	`boolean`	Wird diese Option auf `true` gesetzt, werden innerhalb des Images Logmitteilungen ausgegeben.
	`timeouts`		`object`
		`navigation`	`integer`	Die maximale Wartezeit in Millisekunden die zum Aufrufen der Dokumentenquelle verstreichen darf.
		`processing`	`integer`	Die maximale Wartezeit in Millisekunden die zwischen „Lebenszeichen“ des Verarbeitungsprozesses verstreichen darf.

Rückgabewerte (`JSON`)

Bezeichnung	Typ	Beschreibung
`success`	`boolean`	Wird auf den Wert `true` gesetzt, wenn der Verarbeitungsprozess und die PDF-Erstellung erfolgreich abgeschlossen wurde. Der Wert `false` wird im Fehlerfall gesetzt.
`runtime`	`integer`	Die Dauer in Millisekunden, welche für die Verarbeitung benötigt wurde.
`logs`	`object`	Die gesammelten Logmitteilungen aus der Verarbeitungsprozess.
`resources`	`object`	Die angeforderten Ressourcen aus dem Verarbeitungsprozess.

puppeteer

Enthaltene Software

Konfiguration für docker-compose.yml

Cluster-Konfiguration (Kubernetes)

Verwendung

GET https://[HOSTNAME]:8080/puppeteer?source=[SOURCE]&target=[TARGET]

Parameter (GET)

Rückgabewerte (JSON)

Beispiel

POST https://[HOSTNAME]:8080/pdf

Anfrageinhalt (JSON)

Rückgabewerte (JSON)

Konfiguration für `docker-compose.yml`

`GET https://[HOSTNAME]:8080/puppeteer?source=[SOURCE]&target=[TARGET]`

Parameter (`GET`)

Rückgabewerte (`JSON`)

`POST https://[HOSTNAME]:8080/pdf`

Anfrageinhalt (`JSON`)

Rückgabewerte (`JSON`)