Skip to content
You are reading the documentation of the unreleased development version.Go to the latest release

Deployment

Fagus needs its fagus binary next to PHP on every server that renders PDFs. The Composer plugin installs it with composer install; this page covers builds, servers and processes where that needs a thought.

Install the binary in CI and Docker builds#

The plugin runs after composer install and composer update and installs the binary for the platform Composer runs on, checked against the SHA-256 that the package lists for its release. Builds run Composer without asking, so two things must be in place:

  1. The plugin is allowed in composer.json. Composer asks interactively the first time; in a build it fails instead:

    text
    nforst/fagus contains a Composer plugin which is blocked by your allow-plugins config. You may add it to the list if you consider it safe.

    Commit the entry that answering y writes, or add it yourself:

    sh
    composer config allow-plugins.nforst/fagus true
  2. The build can reach GitHub, where the binaries are attached to the release. Installing from a private fork also needs a token that can read it: Composer's (github-oauth.github.com in auth.json or COMPOSER_AUTH), else FAGUS_GITHUB_TOKEN or GITHUB_TOKEN.

--no-scripts does not stop the plugin; --no-plugins does. After --no-plugins, run vendor/bin/fagus-install.

The plugin keeps downloaded binaries in Composer's cache directory (<cache-dir>/fagus/<version>/), so a build with a cached Composer directory downloads each binary once.

Docker#

Run Composer in the image that runs the application, or install the binary there afterwards. A binary installed in another image is for that image's platform, which may differ in architecture or C library from the image that runs PHP.

dockerfile
FROM php:8.4-fpm

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /app
COPY . .
RUN composer install --no-dev --no-interaction --optimize-autoloader

With a multi-stage build, where Composer runs in a stage of its own, install the binary in the final stage:

dockerfile
FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --no-plugins --optimize-autoloader

FROM php:8.4-fpm-alpine
WORKDIR /app
COPY --from=vendor /app/vendor ./vendor
COPY . .
RUN vendor/bin/fagus-install

vendor/bin/fagus-install keeps a binary that is already there with the right SHA-256 and replaces one of another platform.

Alpine and other musl systems#

Linux with musl has binaries of its own (x86_64-unknown-linux-musl, aarch64-unknown-linux-musl), linked statically. The installer picks them when it finds /lib/ld-musl-*.so.1 or /etc/alpine-release; nothing needs to be configured. The glibc binaries are linked against glibc 2.17, so they run on every maintained glibc distribution.

The binary needs no system libraries and no installed fonts. With systemFonts: true, it reads the font directories that fontconfig's configuration lists, else /usr/share/fonts, /usr/local/share/fonts and ~/.local/share/fonts; install the font packages you want there (see fonts.md).

Servers without access to GitHub#

Put the files of the release somewhere the server can reach and point FAGUS_DOWNLOAD_URL at it: a directory or a URL that holds the files under their names in the release, fagus-<target>:

text
fagus-x86_64-unknown-linux-gnu
fagus-aarch64-unknown-linux-gnu
fagus-x86_64-unknown-linux-musl
fagus-aarch64-unknown-linux-musl
fagus-x86_64-apple-darwin
fagus-aarch64-apple-darwin
fagus-x86_64-pc-windows-msvc.exe
sh
FAGUS_DOWNLOAD_URL=https://artifacts.example.com/fagus/0.1.0 composer install
FAGUS_DOWNLOAD_URL=/mnt/artifacts/fagus/0.1.0 vendor/bin/fagus-install

The binary is installed only if its SHA-256 is the one the package lists for its release, whatever its source. FAGUS_DOWNLOAD_URL applies to the plugin, vendor/bin/fagus-install and php artisan fagus:install.

vendor/bin/fagus-install takes a directory as its argument to install somewhere else than into the package; name that path in FAGUS_BINARY then:

sh
vendor/bin/fagus-install /opt/fagus
# The fagus binary is installed at /opt/fagus/fagus.

Use a binary of your own#

FAGUS_BINARY names a binary that the engine uses instead of the installed one, for example one built from source:

sh
cargo build --release -p fagus-cli
export FAGUS_BINARY=/path/to/fagus/target/release/fagus

The engine looks for the binary in this order:

  1. The binary argument of Engine (in Laravel, the binary key of config/fagus.php).
  2. FAGUS_BINARY.
  3. The binary the installer put into the package (vendor/nforst/fagus/php/fagus/bin/fagus, fagus.exe on Windows).
  4. fagus (fagus.exe) on the PATH.

A binary named in the first two must exist and be executable, otherwise the engine does not fall back but throws:

text
The fagus binary `/usr/local/bin/fagus` could not be started. It does not exist or is not executable.

The binary must speak the package's protocol; use the one of the same release.

Under PHP-FPM the pool's environment is cleared by default (clear_env = yes), so a FAGUS_BINARY from the shell does not reach PHP. Set it in the pool (env[FAGUS_BINARY] = /usr/local/bin/fagus) or pass the path to the engine. In Laravel, FAGUS_BINARY in .env works, also with a cached configuration, as it is read into config('fagus.binary').

Windows#

  • The binary is fagus.exe for x64; Windows on ARM is not supported.
  • There is no timeout: PHP cannot wait for a pipe with a time limit on Windows, so the engine waits for each answer as long as it takes.
  • A running binary is locked. Stop the processes that run it (queue workers, Octane) before composer update replaces it; otherwise the installer reports that it could not write the binary.

Worker processes#

The PHP package starts the binary as a worker process with the first document and talks to it through pipes (protocol.md). The worker keeps fonts and caches warm and renders one document after another until its engine is closed or destroyed. HTML, fonts and PDFs travel through the pipes as they are, of any size.

Runtime The worker serves
PHP-FPM, mod_php, FrankenPHP's classic mode the documents of one request; the first document of each request starts it
Queue workers (queue:work, Horizon) every document of the queue worker process
Octane (Swoole, RoadRunner, FrankenPHP) every document of the Octane worker: the Laravel integration warms the engine (laravel.md)
FrankenPHP's worker mode without Laravel, long-running scripts every document, as long as the engine (for example Fagus::engine()) is kept
CLI scripts the documents of the script

Each PHP process that renders has its own worker process. One worker renders one document at a time, as PHP sends them one after another.

Engine::close() stops the worker; the next document starts a new one, which gets the fonts of addFont() again. When a worker times out or exits, the engine stops it and throws an EngineException; the next document starts a new worker.

Speed and memory#

Rendering times of invoices on an Apple M3, once the worker runs, unless noted:

Document Time
One-page invoice, tagged about 1.5 ms
Ten-page invoice, tagged about 12 ms
First document of a process, including the start of the worker about 8 ms

On an Apple M2 Pro, fagus render of the repository's corpus invoices peaks at about 22 MB of resident memory for the one-page invoice and 34 MB for the ten-page invoice. The macOS binary itself is about 25 MB on disk. Large images, many fonts and long documents need more.

Under PHP-FPM, every request that renders pays the start of the worker once. Where many requests render PDFs, a queue worker or Octane keeps the worker running.

Threads#

The binary compresses the PDF on two threads of its own while it draws the pages, which makes large documents a few percent faster. RAYON_NUM_THREADS sets how many there are:

sh
RAYON_NUM_THREADS=1 php artisan queue:work

More than two gain nothing. With many workers side by side on few cores, one thread each saves processor time. The worker inherits the environment of the PHP process that starts it; under PHP-FPM, set the variable in the pool (env[RAYON_NUM_THREADS] = 1).

Timeouts#

The engine waits up to timeout seconds (60 by default) for each answer of the worker. A worker that does not answer in time is stopped, and the engine throws:

text
The fagus worker did not answer within 60 seconds and was stopped.
php
new Engine(timeout: 120.0);   // in Laravel: 'timeout' => 120 in config/fagus.php

The limit applies to each answer, not to the whole document: time spent in your resolver callback does not count. There is no timeout on Windows. For requests, keep the timeout below the limits of PHP-FPM (request_terminate_timeout) and of your web server, or render long documents in a queue.

Reproducible PDFs#

The same document gives the same bytes when:

  • the creation date is fixed with created() (the current time otherwise),
  • the fonts are the same, which they are with fonts from @font-face, font directories and the built-in fonts, and not necessarily with systemFonts: true,
  • the binary is the same release.
php
$pdf = Fagus::html($html)
    ->created(new DateTimeImmutable('2026-11-02 12:00:00', new DateTimeZone('UTC')))
    ->render();

Every platform prints the same PDF from the same input, so a PDF made on a Mac matches the one made on a Linux server.