Upgrading

Templates don’t pin a version of the rendering engine: after an upgrade, every template renders with the new one. So before rolling it out, check that the documents your tenants have published still come out as they did.

Compare before you roll out

When a template version is published, Paprika records its reference fingerprint: its sample values rendered at a fixed date, as the PDF’s content (without what names the engine or the time) and each page’s pixels. The compare command of the new image renders every stored version again and lists those that changed:

PAPRIKA_IMAGE=paprika:new docker compose run --rm api compare --out compare.json

It prints a line per version that changed, had no reference or failed, and exits with 1 when any did, so it can stop an automated rollout. --tenant <id> compares one tenant’s. The report says, for each one, what changed: the PDF, which pages, the errors.

A change may be an improvement: a fix in text layout moves a line. Telling the tenants concerned is yours, from the report. Once you accept the changes, make the new renders the references:

PAPRIKA_IMAGE=paprika:new docker compose run --rm api compare --accept

Roll out

1. Back up the database and the data volume (storage).

2. Set PAPRIKA_IMAGE in .env to the new image.

3. Bring the services up again: migrate brings the schema up to date before the new API starts.

   docker compose up --wait

Migrations only ever move forward: going back to an older image after one has run means restoring the backup.

What the output says

Every output names the engine that made it: in GET /v1/health, in each PDF’s producer and metadata, and in the reports of outputs, jobs and batches, with the version it was published with. The same template version, values and creation date give the same bytes, so an output can be made again exactly (reproducible output).