build: make UPX packing opt-in via COMPRESS env var (#2429)

dunglas · web-flow · commit 1a03bc23ef50 · 2026-05-16T18:03:24.000+02:00
## Summary

UPX is now disabled by default for the static build. To pack the binary
with UPX (Linux only), set `COMPRESS=1` at build time. The previous
`NO_COMPRESS` flag is removed; CI invocations and the
`static-builder-{musl,gnu}` Dockerfiles were updated accordingly. Docs
(all locales) were refreshed.

## Why drop UPX from the default?

- **AV false positives.** UPX-packed binaries get flagged routinely on
Windows and macOS, generating recurring support friction for end users.
- **Permanent memory cost.** UPX decompresses the whole binary into
anonymous memory at launch, so the OS can no longer share read-only text
pages across processes or demand-page from disk. For a long-running
server with workers, the savings on disk are paid back continuously in
RAM.
- **Startup latency.** ~100–300 ms added per launch — noticeable for
container cold starts and test runs.
- **Tooling friction.** Complicates debugging, core dumps,
SBOM/attestation, and trips up some security scanners.
- **Modest upside.** ~60% size reduction is nice, but FrankenPHP is
mostly distributed via Docker layers (cached) or downloaded once per
host. If artifact size is the concern, `xz`-compressing the release
asset gives similar savings without any of the runtime downsides.

Users who still want a packed binary can opt in explicitly with
`COMPRESS=1`.
diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml
@@ -143,7 +143,6 @@ jobs:
             runner-${{ matrix.variant }}
           # Remove tags to prevent "can't push tagged ref [...] by digest" error
           set: |
-            ${{ (github.event_name == 'pull_request') && '*.args.NO_COMPRESS=1' || '' }}
             *.tags=
             *.platform=${{ matrix.platform }}
             ${{ fromJson(needs.prepare.outputs.push) && '' || format('builder-{0}.cache-from=type=gha,scope=builder-{0}-{1}-{2}', matrix.variant, needs.prepare.outputs.ref || github.ref, matrix.platform) }}
diff --git a/.github/workflows/static.yaml b/.github/workflows/static.yaml
@@ -148,7 +148,6 @@ jobs:
           set: |
             ${{ matrix.debug && 'static-builder-musl.args.DEBUG_SYMBOLS=1' || '' }}
             ${{ matrix.mimalloc && 'static-builder-musl.args.MIMALLOC=1' || '' }}
-            ${{ (github.event_name == 'pull_request' || matrix.platform == 'linux/arm64') && 'static-builder-musl.args.NO_COMPRESS=1' || '' }}
             *.tags=
             *.platform=${{ matrix.platform }}
             ${{ fromJson(needs.prepare.outputs.push) && '' || format('*.cache-from=type=gha,scope={0}-static-builder-musl{1}{2}', needs.prepare.outputs.ref || github.ref, matrix.debug && '-debug' || '', matrix.mimalloc && '-mimalloc' || '') }}
@@ -302,7 +301,6 @@ jobs:
           source: .
           targets: static-builder-gnu
           set: |
-            ${{ (github.event_name == 'pull_request' || matrix.platform == 'linux/arm64') && 'static-builder-gnu.args.NO_COMPRESS=1' || '' }}
             *.tags=
             *.platform=${{ matrix.platform }}
             ${{ fromJson(needs.prepare.outputs.push) && '' || format('*.cache-from=type=gha,scope={0}-static-builder-gnu', needs.prepare.outputs.ref || github.ref) }}
@@ -466,7 +464,6 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           FRANKENPHP_VERSION: ${{ steps.version.outputs.version }}
           RELEASE: ${{ (needs.prepare.outputs.ref || github.ref_type == 'tag') && '1' || '' }}
-          NO_COMPRESS: ${{ github.event_name == 'pull_request' && '1' || '' }}
       - name: Upload logs
         if: ${{ failure() }}
         uses: actions/upload-artifact@v7
diff --git a/alpine.Dockerfile b/alpine.Dockerfile
@@ -54,7 +54,7 @@ LABEL org.opencontainers.image.vendor="Kévin Dunglas"
 FROM common AS builder
 
 ARG FRANKENPHP_VERSION='dev'
-ARG NO_COMPRESS=''
+ARG COMPRESS=''
 SHELL ["/bin/ash", "-eo", "pipefail", "-c"]
 
 COPY --link --from=golang-base /usr/local/go /usr/local/go
@@ -128,7 +128,7 @@ WORKDIR /go/src/app/caddy/frankenphp
 RUN GOBIN=/usr/local/bin \
 		../../go.sh install -ldflags "-w -s -extldflags '-Wl,-z,stack-size=0x80000' -X 'github.com/caddyserver/caddy/v2.CustomVersion=FrankenPHP $FRANKENPHP_VERSION PHP $PHP_VERSION Caddy' -X 'github.com/caddyserver/caddy/v2.CustomBinaryName=frankenphp' -X 'github.com/caddyserver/caddy/v2/modules/caddyhttp.ServerHeader=FrankenPHP Caddy'" -buildvcs=true && \
 	setcap cap_net_bind_service=+ep /usr/local/bin/frankenphp && \
-	([ -z "${NO_COMPRESS}" ] && upx --best /usr/local/bin/frankenphp || true) && \
+	([ -n "${COMPRESS}" ] && upx --best /usr/local/bin/frankenphp || true) && \
 	frankenphp version && \
 	frankenphp build-info
 
diff --git a/build-static.sh b/build-static.sh
@@ -21,6 +21,7 @@ os="$(uname -s | tr '[:upper:]' '[:lower:]')"
 # - FRANKENPHP_VERSION: FrankenPHP version (default: current Git commit)
 # - EMBED: Path to the PHP app to embed (default: none)
 # - DEBUG_SYMBOLS: Enable debug symbols if set to 1 (default: none)
+# - COMPRESS: Pack the resulting Linux binary with UPX if set to 1; ignored when DEBUG_SYMBOLS is set (default: none)
 # - MIMALLOC: Use mimalloc as the allocator if set to 1 (default: none)
 # - XCADDY_ARGS: Additional arguments to pass to xcaddy
 # - RELEASE: [maintainer only] Create a GitHub release if set to 1 (default: none)
@@ -189,7 +190,7 @@ if [ -n "${EMBED}" ] && [ -d "${EMBED}" ]; then
 fi
 
 SPC_OPT_INSTALL_ARGS="go-xcaddy"
-if [ -z "${DEBUG_SYMBOLS}" ] && [ -z "${NO_COMPRESS}" ] && [ "${os}" = "linux" ]; then
+if [ -n "${COMPRESS}" ] && [ -z "${DEBUG_SYMBOLS}" ] && [ "${os}" = "linux" ]; then
 	SPC_OPT_BUILD_ARGS="${SPC_OPT_BUILD_ARGS} --with-upx-pack"
 	SPC_OPT_INSTALL_ARGS="${SPC_OPT_INSTALL_ARGS} upx"
 fi
diff --git a/docs/cn/embed.md b/docs/cn/embed.md
@@ -138,7 +138,7 @@ EMBED=/path/to/your/app ./build-static.sh
 
 ## 分发二进制文件
 
-在Linux上，创建的二进制文件使用[UPX](https://upx.github.io)进行压缩。
+在 Linux 上，可以通过在构建时设置环境变量 `COMPRESS=1` 来使用 [UPX](https://upx.github.io) 压缩生成的二进制文件。
 
 在Mac上，您可以在发送文件之前压缩它以减小文件大小。
 我们推荐使用 `xz`。
diff --git a/docs/cn/static.md b/docs/cn/static.md
@@ -124,7 +124,7 @@ cd frankenphp
 - `XCADDY_ARGS`：传递给 [xcaddy](https://github.com/caddyserver/xcaddy) 的参数，例如用于添加额外的 Caddy 模块
 - `EMBED`: 要嵌入二进制文件的 PHP 应用程序的路径
 - `CLEAN`: 设置后，libphp 及其所有依赖项都是重新构建的（不使用缓存）
-- `NO_COMPRESS`: 不要使用UPX压缩生成的二进制文件
+- `COMPRESS`: 设置为 `1` 时使用 UPX 压缩生成的二进制文件（仅限 Linux；设置了 `DEBUG_SYMBOLS` 时忽略此选项）
 - `DEBUG_SYMBOLS`: 设置后，调试符号将被保留在二进制文件内
 - `MIMALLOC`: (实验性，仅限Linux) 用[mimalloc](https://github.com/microsoft/mimalloc)替换musl的mallocng，以提高性能。我们仅建议在musl目标构建中使用此选项，对于glibc，建议禁用此选项，并在运行二进制文件时使用[`LD_PRELOAD`](https://microsoft.github.io/mimalloc/overrides.html)。
 - `RELEASE`: （仅限维护者）设置后，生成的二进制文件将上传到 GitHub 上
diff --git a/docs/embed.md b/docs/embed.md
@@ -144,7 +144,7 @@ To customize the extensions, use the `PHP_EXTENSIONS` environment variable.
 
 ## Distributing the binary
 
-On Linux, the created binary is compressed using [UPX](https://upx.github.io).
+On Linux, the created binary can be compressed using [UPX](https://upx.github.io) by setting the `COMPRESS=1` environment variable at build time.
 
 On macOS, to reduce the size of the file before sending it, you can compress it.
 We recommend `xz`.
diff --git a/docs/es/embed.md b/docs/es/embed.md
@@ -138,7 +138,7 @@ Para personalizar las extensiones, use la variable de entorno `PHP_EXTENSIONS`.
 
 ## Distribuir el binario
 
-En Linux, el binario creado se comprime usando [UPX](https://upx.github.io).
+En Linux, el binario creado puede comprimirse usando [UPX](https://upx.github.io) estableciendo la variable de entorno `COMPRESS=1` en el momento de la compilación.
 
 En Mac, para reducir el tamaño del archivo antes de enviarlo, puede comprimirlo.
 Recomendamos `xz`.
diff --git a/docs/es/static.md b/docs/es/static.md
@@ -123,7 +123,7 @@ Las siguientes variables de entorno pueden pasarse a `docker build` y al script
 - `XCADDY_ARGS`: argumentos a pasar a [xcaddy](https://github.com/caddyserver/xcaddy), por ejemplo para agregar módulos adicionales de Caddy
 - `EMBED`: ruta de la aplicación PHP a incrustar en el binario
 - `CLEAN`: cuando está establecido, libphp y todas sus dependencias se compilan desde cero (sin caché)
-- `NO_COMPRESS`: no comprimir el binario resultante usando UPX
+- `COMPRESS`: cuando se establece en `1`, comprime el binario resultante usando UPX (solo Linux; se ignora cuando `DEBUG_SYMBOLS` está establecido)
 - `DEBUG_SYMBOLS`: cuando está establecido, los símbolos de depuración no se eliminarán y se añadirán al binario
 - `MIMALLOC`: (experimental, solo Linux) reemplaza mallocng de musl por [mimalloc](https://github.com/microsoft/mimalloc) para mejorar el rendimiento. Solo recomendamos usar esto para compilaciones orientadas a musl; para glibc, preferimos deshabilitar esta opción y usar [`LD_PRELOAD`](https://microsoft.github.io/mimalloc/overrides.html) cuando ejecutes tu binario.
 - `RELEASE`: (solo para mantenedores) cuando está establecido, el binario resultante se subirá a GitHub
diff --git a/docs/fr/embed.md b/docs/fr/embed.md
@@ -145,7 +145,7 @@ PHP_EXTENSIONS=ctype,iconv,pdo_sqlite \
 
 ## Distribuer le binaire
 
-Sous Linux, le binaire est compressé par défaut à l'aide de [UPX](https://upx.github.io).
+Sous Linux, le binaire peut être compressé à l'aide de [UPX](https://upx.github.io) en définissant la variable d'environnement `COMPRESS=1` au moment de la compilation.
 
 Sous Mac, pour réduire la taille du fichier avant de l'envoyer, vous pouvez le compresser.
 Nous recommandons `xz`.
diff --git a/docs/fr/static.md b/docs/fr/static.md
@@ -124,7 +124,7 @@ Les variables d'environnement suivantes peuvent être transmises à `docker buil
 - `EMBED` : chemin de l'application PHP à intégrer dans le binaire
 - `CLEAN` : lorsque défini, `libphp` et toutes ses dépendances sont construites à partir de zéro (pas de cache)
 - `DEBUG_SYMBOLS` : lorsque défini, les symboles de débogage ne seront pas supprimés et seront ajoutés dans le binaire
-- `NO_COMPRESS` : ne pas compresser le binaire avec UPX
+- `COMPRESS` : lorsque défini à `1`, compresse le binaire résultant avec UPX (Linux uniquement ; ignoré lorsque `DEBUG_SYMBOLS` est défini)
 - `MIMALLOC` : (expérimental, Linux seulement) remplace l'allocateur mallocng de musl par [mimalloc](https://github.com/microsoft/mimalloc) pour des performances améliorées
 - `RELEASE` : (uniquement pour les mainteneurs) lorsque défini, le binaire résultant sera uploadé sur GitHub
 
diff --git a/docs/ja/embed.md b/docs/ja/embed.md
@@ -138,7 +138,7 @@ HTTPS（Let's Encrypt証明書は自動作成）、HTTP/2、HTTP/3を有効に
 
 ## バイナリの配布
 
-Linuxでは、作成されたバイナリは[UPX](https://upx.github.io)を使用して圧縮されます。
+Linux では、ビルド時に環境変数 `COMPRESS=1` を設定することで、作成されたバイナリを [UPX](https://upx.github.io) で圧縮できます。
 
 Macでは、送信前にファイルサイズを減らすために圧縮できます。
 `xz`の使用をお勧めします。
diff --git a/docs/ja/static.md b/docs/ja/static.md
@@ -124,7 +124,7 @@ cd frankenphp
 - `XCADDY_ARGS`: 追加のCaddyモジュールを導入するなど[xcaddy](https://github.com/caddyserver/xcaddy)に渡す引数
 - `EMBED`: バイナリに埋め込むPHPアプリケーションのパス
 - `CLEAN`: 指定するとlibphpおよびそのすべての依存関係がスクラッチからビルドされます（キャッシュなし）
-- `NO_COMPRESS`: UPXを使用して結果のバイナリを圧縮しない
+- `COMPRESS`: `1` に設定すると UPX を使用して結果のバイナリを圧縮します（Linux のみ。`DEBUG_SYMBOLS` が設定されている場合は無視されます）
 - `DEBUG_SYMBOLS`: 指定すると、デバッグシンボルが除去されず、バイナリに含まれます
 - `MIMALLOC`: （実験的、Linuxのみ）パフォーマンス向上のためにmuslのmallocngを[mimalloc](https://github.com/microsoft/mimalloc)に置き換えます。muslをターゲットとするビルドにのみこれを使用することをお勧めします。glibcの場合は、このオプションを無効にして、代わりにバイナリを実行する際に[`LD_PRELOAD`](https://microsoft.github.io/mimalloc/overrides.html)を使用することをお勧めします。
 - `RELEASE`: （メンテナー用）指定すると、生成されたバイナリがGitHubにアップロードされます
diff --git a/docs/pt-br/embed.md b/docs/pt-br/embed.md
@@ -160,7 +160,7 @@ personalizar o binário (extensões, versão do PHP...).
 
 ## Distribuindo o binário
 
-No Linux, o binário criado é compactado usando [UPX](https://upx.github.io).
+No Linux, o binário criado pode ser compactado usando [UPX](https://upx.github.io) definindo a variável de ambiente `COMPRESS=1` no momento da compilação.
 
 No Mac, para reduzir o tamanho do arquivo antes de enviá-lo, você pode
 compactá-lo.
diff --git a/docs/pt-br/static.md b/docs/pt-br/static.md
@@ -157,7 +157,7 @@ o script `build-static.sh` para personalizar a compilação estática:
 - `EMBED`: caminho da aplicação PHP a ser incorporada no binário;
 - `CLEAN`: quando definida, a `libphp` e todas as suas dependências são
   compiladas do zero (sem cache);
-- `NO_COMPRESS`: não compacta o binário resultante usando UPX;
+- `COMPRESS`: quando definida como `1`, compacta o binário resultante usando UPX (apenas Linux; ignorada quando `DEBUG_SYMBOLS` está definida);
 - `DEBUG_SYMBOLS`: quando definida, os símbolos de depuração não serão removidos
   e serão adicionados ao binário;
 - `MIMALLOC`: (experimental, somente Linux) substitui `mallocng` da `musl` por
diff --git a/docs/ru/embed.md b/docs/ru/embed.md
@@ -136,6 +136,6 @@ EMBED=/path/to/your/app ./build-static.sh
 
 ## Распространение бинарного файла
 
-На Linux созданный бинарный файл сжимается с помощью [UPX](https://upx.github.io).
+На Linux созданный бинарный файл можно сжать с помощью [UPX](https://upx.github.io), задав переменную окружения `COMPRESS=1` во время сборки.
 
 На Mac для уменьшения размера файла перед отправкой его можно сжать. Рекомендуется использовать `xz`.
diff --git a/docs/ru/static.md b/docs/ru/static.md
@@ -94,7 +94,7 @@ cd frankenphp
 - `XCADDY_ARGS`: аргументы для [xcaddy](https://github.com/caddyserver/xcaddy), например, для добавления модулей Caddy
 - `EMBED`: путь к PHP-приложению для встраивания в бинарник
 - `CLEAN`: если задано, libphp и все его зависимости будут пересобраны с нуля (без кэша)
-- `NO_COMPRESS`: отключает сжатие результирующего бинарника с помощью UPX
+- `COMPRESS`: если установлено в `1`, сжимает результирующий бинарник с помощью UPX (только для Linux; игнорируется, если задан `DEBUG_SYMBOLS`)
 - `DEBUG_SYMBOLS`: если задано, отладочные символы не будут удалены и будут добавлены в бинарник
 - `MIMALLOC`: (экспериментально, только для Linux) заменяет musl's mallocng на [mimalloc](https://github.com/microsoft/mimalloc) для повышения производительности
 - `RELEASE`: (только для мейнтейнеров) если задано, бинарник будет загружен на GitHub
diff --git a/docs/static.md b/docs/static.md
@@ -129,7 +129,7 @@ script to customize the static build:
 - `XCADDY_ARGS`: arguments to pass to [xcaddy](https://github.com/caddyserver/xcaddy), for instance to add extra Caddy modules
 - `EMBED`: path of the PHP application to embed in the binary
 - `CLEAN`: when set, libphp and all its dependencies are built from scratch (no cache)
-- `NO_COMPRESS`: don't compress the resulting binary using UPX
+- `COMPRESS`: when set to `1`, pack the resulting binary with UPX (Linux only; ignored when `DEBUG_SYMBOLS` is set)
 - `DEBUG_SYMBOLS`: when set, debug-symbols will not be stripped and will be added to the binary
 - `MIMALLOC`: (experimental, Linux-only) replace musl's mallocng by [mimalloc](https://github.com/microsoft/mimalloc) for improved performance. We only recommend using this for musl targeting builds, for glibc prefer disabling this option and using [`LD_PRELOAD`](https://microsoft.github.io/mimalloc/overrides.html) when you run your binary instead.
 - `RELEASE`: (maintainers only) when set, the resulting binary will be uploaded on GitHub
diff --git a/docs/tr/embed.md b/docs/tr/embed.md
@@ -125,7 +125,7 @@ Binary dosyasının nasıl özelleştirileceğini (uzantılar, PHP sürümü...)
 
 ## Binary Dosyasının Dağıtılması
 
-Linux'ta, oluşturulan ikili dosya [UPX](https://upx.github.io) kullanılarak sıkıştırılır.
+Linux'ta, oluşturulan ikili dosya derleme sırasında `COMPRESS=1` ortam değişkeni ayarlanarak [UPX](https://upx.github.io) ile sıkıştırılabilir.
 
 Mac'te, göndermeden önce dosyanın boyutunu küçültmek için sıkıştırabilirsiniz.
 Biz `xz` öneririz.
diff --git a/static-builder-gnu.Dockerfile b/static-builder-gnu.Dockerfile
@@ -21,7 +21,7 @@ ARG CLEAN=''
 ARG EMBED=''
 ARG DEBUG_SYMBOLS=''
 ARG MIMALLOC=''
-ARG NO_COMPRESS=''
+ARG COMPRESS=''
 
 # Go
 ARG GO_VERSION
diff --git a/static-builder-musl.Dockerfile b/static-builder-musl.Dockerfile
@@ -24,7 +24,7 @@ ARG CLEAN=''
 ARG EMBED=''
 ARG DEBUG_SYMBOLS=''
 ARG MIMALLOC=''
-ARG NO_COMPRESS=''
+ARG COMPRESS=''
 
 ENV GOTOOLCHAIN=local
 
