Skip to content

docs: explain daily binary rebuilds, verification and pinning #2784

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dunglas wants to merge 1 commit into
base: main
Choose a base branch
from
+27 −0
Open

docs: explain daily binary rebuilds, verification and pinning #2784

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ Windows archives contain the official PHP binary for Windows.

[Download FrankenPHP](https://github.com/php/frankenphp/releases)

The binaries of the latest release are rebuilt daily to include PHP security fixes. See [how to verify and pin them](https://frankenphp.dev/docs/production/#standalone-binary-updates).

### rpm packages

Our maintainers offer rpm packages for all systems using `dnf`. To install, run:
Expand Down
3 changes: 3 additions & 0 deletions docs/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,9 @@ The Docker images are built:
- when a new release is tagged
- daily at 4 am UTC, if new versions of the official PHP images are available

Tags such as `latest` or `1-php8.5` are moved to the new images, while digests never change.
To pin an exact image, reference it by digest. The standalone binaries follow [a similar update policy](production.md#standalone-binary-updates).

## Hardening images

To further reduce the attack surface and size of your FrankenPHP Docker images, it's also possible to build them on top of a
Expand Down
22 changes: 22 additions & 0 deletions docs/production.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,3 +234,25 @@ Windows services cannot be reloaded. To apply configuration changes gracefully,
```powershell
.\frankenphp.exe reload --config Caddyfile
```

## Standalone binary updates

To ship PHP and library security fixes without waiting for a new FrankenPHP release, the binaries attached to the latest release are rebuilt every day
(at midnight UTC for Linux and macOS, at 8 am UTC for Windows) and replace the previous ones under the same name.

@henderkes henderkes Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we just rebuild them at the same time?

@dunglas dunglas Oct 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure, in the past we hit various rate limits with too much paralell builds. IMHO it's safer like this, but to be tested.

Anyway, we can change that later.

@henderkes henderkes Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single Windows build isn't going to change rate limits considering the amount of linux + macos builds.

@henderkes henderkes Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would propose we switch the windows build to 0 and make this less confusing. There's nothing I can imagine going wrong.

@dunglas dunglas Oct 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We sometimes hit the rate limit of php.net CDN, docker.io and other hidden dependencies. TBH I would prefer to keep it as is for now as it's working.

@henderkes henderkes Oct 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, a bit confusing from user perspective I would guess, but we can play it safe for now.

Their checksums therefore change from one day to the next. Binaries attached to older releases are not rebuilt.

To find out which PHP version a binary contains, run:

```console
frankenphp version
```

Every binary is signed with a [GitHub artifact attestation](https://docs.github.com/actions/security-for-github-actions/using-artifact-attestations).
To check that a binary was built by the FrankenPHP CI, whatever the day it was downloaded, use the [GitHub CLI](https://cli.github.com):

```console
gh attestation verify frankenphp-linux-x86_64 --repo php/frankenphp
```

If your deployments need a byte-for-byte reproducible binary (for instance, to pin its checksum), don't download it from the releases page at deploy time.
Instead, store a verified copy in your own artifact repository, or use [the Docker images](docker.md) pinned by digest (`dunglas/frankenphp@sha256:...`).
Loading