docs(docker): update deployment section for share-generics and multi-arch (whatsapp-rust#845)

changelog/2026-06-11-dockerfile-share-generics.mdx

@@ -0,0 +1,24 @@
+---
+title: "June 11, 2026 — Docker image: share-generics, build-std, multi-arch"
+description: "Reduces the release binary .text section by ~15% cumulatively through -Zshare-generics=y and -Zbuild-std, and enables native multi-arch docker buildx builds."
+---
+
+## Performance
+
+**Dockerfile: `-Zshare-generics`, `build-std`, and explicit target ([#845](https://github.com/oxidezap/whatsapp-rust/pull/845))**
+
+The Docker image build gains three related changes that reduce binary size and improve reproducibility.
+
+**`-Zshare-generics=y`** tells the nightly compiler to reuse upstream crate monomorphizations instead of re-codegening them per downstream crate. Cross-crate duplicate-symbol waste drops from 1414 KiB to 475 KiB; consumer-crate reinstantiation drops from 1484 KiB to 531 KiB. Measured impact on the release binary: `.text` shrinks by **666 KiB (−5.6%)**.
+
+**`-Zbuild-std`** (via `CARGO_UNSTABLE_BUILD_STD=std,panic_abort`) recompiles the standard library with the release profile so it participates in fat LTO and dead-code elimination instead of linking the prebuilt rustup `std`. This was measured separately in the same audit series as an additional −303 KiB.
+
+Combined with the library-level deduplication in #842–#844, the cumulative reduction since the audit began is **13.03 MiB → 11.00 MiB (−15.6%)** on `.text`.
+
+**Explicit target triple.** The Dockerfile now detects the host triple at build time via `rustc -vV` and passes it explicitly to both `cargo chef cook` and `cargo build`. This is required by `-Zbuild-std`, and as a side effect it makes `docker buildx build --platform linux/arm64` produce correct native binaries without Dockerfile changes.
+
+**Pinned `cargo-chef`.** `cargo-chef` is now installed at a fixed version (`0.1.77 --locked`) so image rebuilds are deterministic rather than tracking the latest crates.io release.
+
+Both `-Zshare-generics` and `-Zbuild-std` are nightly-only flags. They apply only inside the Docker image, which already pins the nightly toolchain via `rust-toolchain.toml`. Stable consumers and local `cargo build` invocations are unaffected. With `lto = "fat"` the historical downside of `share-generics` (lost cross-crate inlining of shared instantiations) does not apply — fat LTO sees all bitcode and re-inlines freely.
+
+Downstream images building on the same pinned nightly (e.g. Veloz) can apply the same `RUSTFLAGS` and `CARGO_UNSTABLE_BUILD_STD` variables for identical gains.

docs.json

@@ -138,6 +138,7 @@
                 "group": "Changelog",
                 "pages": [
                   "changelog/overview",
+                  "changelog/2026-06-11-dockerfile-share-generics",
                   "changelog/2026-06-11-pdo-once-per-message",
                   "changelog/2026-06-11-history-sync-secret-prescan",
                   "changelog/2026-06-10-jid-into-api-convention",

installation.mdx

@@ -208,10 +208,11 @@ docker build -t whatsapp-rust .
 
 The build process:
 
-1. Uses `rust:alpine` with [cargo-chef](https://github.com/LukeMathWalker/cargo-chef) for efficient dependency caching
-2. Compiles natively against musl on Alpine for a fully static binary
-3. Caches dependency compilation via `cargo chef cook` in a separate layer for fast rebuilds
-4. Produces a final image from `scratch` containing only the binary
+1. Uses `rust:alpine` with [cargo-chef](https://github.com/LukeMathWalker/cargo-chef) (pinned to a fixed release with `--locked`) for efficient, reproducible dependency caching
+2. Detects the host target triple at build time — `docker buildx build --platform linux/arm64` produces native binaries without Dockerfile changes
+3. Enables `-Zshare-generics=y` (−5.6% `.text`) and recompiles `std` with the release profile (`-Zbuild-std`, −~300 KiB more) so it participates in fat LTO — together these two flags account for roughly 8% of the cumulative 15% reduction achieved across the full optimization series
+4. Caches dependency compilation via `cargo chef cook --target` in a separate layer for fast rebuilds
+5. Produces a final image from `scratch` containing only the binary
 
 ### Run the container
 
@@ -232,7 +233,7 @@ The container supports graceful shutdown out of the box. When the `signal` featu
 Since the image is built from `scratch`, PID 1 is the binary itself. It handles signals directly — no init system like `tini` is needed.
 
 <Note>
-  The Dockerfile uses `rust:alpine` which builds for the host architecture's musl target. For cross-compilation to other architectures, you need to modify the base image and build configuration in the Dockerfile.
+  The Dockerfile detects the host target triple at build time via `rustc -vV`, so `docker buildx build --platform linux/arm64` (or any other supported platform) works natively without modifying the Dockerfile. The nightly-only build flags (`-Zshare-generics`, `-Zbuild-std`) apply only inside this image — stable consumers and local `cargo build` invocations are unaffected.
 </Note>
 
 ## Next steps

pt/installation.mdx

@@ -205,10 +205,11 @@ docker build -t whatsapp-rust .
 
 O processo de build:
 
-1. Usa `rust:alpine` com [cargo-chef](https://github.com/LukeMathWalker/cargo-chef) para cache eficiente de dependências
-2. Compila nativamente contra musl no Alpine para um binário totalmente estático
-3. Faz cache da compilação de dependências via `cargo chef cook` em uma camada separada para rebuilds rápidos
-4. Produz uma imagem final a partir de `scratch` contendo apenas o binário
+1. Usa `rust:alpine` com [cargo-chef](https://github.com/LukeMathWalker/cargo-chef) (fixado em uma versão específica com `--locked`) para cache eficiente e reproduzível de dependências
+2. Detecta a triple de alvo do host em tempo de build — `docker buildx build --platform linux/arm64` produz binários nativos sem alterações no Dockerfile
+3. Habilita `-Zshare-generics=y` (−5,6% no `.text`) e recompila `std` com o perfil de release (`-Zbuild-std`, −~300 KiB adicionais) para participar do LTO gordo — juntas, essas duas flags respondem por cerca de 8% da redução acumulada de 15% obtida ao longo de toda a série de otimizações
+4. Faz cache da compilação de dependências via `cargo chef cook --target` em uma camada separada para rebuilds rápidos
+5. Produz uma imagem final a partir de `scratch` contendo apenas o binário
 
 ### Execute o contêiner
 
@@ -229,7 +230,7 @@ O contêiner suporta desligamento gracioso sem configuração adicional. Quando
 Como a imagem é construída a partir de `scratch`, o PID 1 é o próprio binário. Ele lida com sinais diretamente — nenhum sistema init como `tini` é necessário.
 
 <Note>
-  O Dockerfile usa `rust:alpine`, que constrói para o alvo musl da arquitetura do host. Para compilação cruzada para outras arquiteturas, você precisa modificar a imagem base e a configuração de build no Dockerfile.
+  O Dockerfile detecta a triple de alvo do host em tempo de build via `rustc -vV`, então `docker buildx build --platform linux/arm64` (ou qualquer outra plataforma suportada) funciona nativamente sem modificar o Dockerfile. As flags de build exclusivas do nightly (`-Zshare-generics`, `-Zbuild-std`) se aplicam apenas dentro desta imagem — consumidores stable e invocações locais de `cargo build` não são afetados.
 </Note>
 
 ## Próximos passos