{{ .Description }}
- name: JSON_TEMPLATE # language=json value: | { "error": true, "message": {{ .Message | toJson }} } ``` For adding your own error descriptions, you can still use `--add-code` (or `$ADD_CODE`), but now it's a single flag instead of multiple, and the value format has changed: ```bash --add-code "418=I'm a teapot/Short and stout" # v3 --add-code "499=Custom Error/Another description" # v3 --add-code "418=I'm a teapot|Short and stout" # v4 - single entry --add-code "418=I'm a teapot|Short and stout||499=Custom Error|Another description" # v4 - multiple entries in one value ``` ```yaml env: - name: ADD_CODE # v4 - env var, newline-separated value: | 418=I'm a teapot|Short and stout 499=Custom Error|Another description ``` > This became obvious to me after reading [this discussion](https://github.com/tarampampam/error-pages/discussions/297), > so thanks for leaving your thoughts in the repo - I genuinely appreciate it and I read all your ideas and suggestions, > even when I don't always reply. > [!WARNING] > If you keep the old `/` syntax for `--add-code`, the parser won't error - your description will be silently glued onto > the message. Grep your configs for `--add-code` or `$ADD_CODE` to find and fix them. ### Localization (l10n) got easier Before, you had to open a JS file and add your translations there, which wasn't great. I extracted all localizable strings into a separate JSON file, and the JS file is now generated from it at build time. Way simpler and more reliable. ### All templates are now parsed once at startup This used to happen on every request, which was inefficient - but it was a forced compromise to keep backward compatibility with previous versions. As a consequence, "functions" and "data" in templates had to be separated, and now you'll need to update all custom templates (if you used your own templates instead of the built-ins) to match the new data structure passed to the template. But it's not as hard as it sounds, really. On top of that, all the template functions have been completely reworked so they can be used in chained calls, the way it's normally done in Go templates (e.g., in Helm and other projects). This significantly expanded their capabilities - you can now do much more complex things without extra cognitive overhead. I'll cover how to migrate your templates in more detail below, but the short version: I implemented support for the old template format, so if you don't want to deal with updating them right now, you can do it later. The legacy support won't last forever, but I'm not planning to remove it anytime soon, so don't stress. ### HTML minification replaced by full-response gzip compression Previously HTML responses were minified, but the minification wasn't perfect and would occasionally break templates - plus it didn't work for other formats (JSON, XML, plaintext). Now, instead of that, all responses can be gzip-compressed (if the incoming request supports it), which is actually a more effective way to shrink the response and works for all formats without exception. ### Docker image now contains only the HTTP server The app is now shipped as 2 separate binaries - `error-pages` (HTTP server) and `builder` (a static generator that produces pre-rendered static error pages). Adding new templates was bloating the docker image size, and realistically you only need one of these two - either pre-rendered pages from `builder`, or the HTTP server for dynamic page generation, but not both at the same time. As for the docker image and its tags: - The image name stays the same - Tags in the `X.Y.Z` (and `X.Y`, `X`) format contain the HTTP server - Tags with the `X.Y.Z-builder` (and `X.Y-builder`, `X-builder`) suffix contain the builder and pre-rendered error pages The `serve` and `build` sub-commands no longer exist as such - they're separate binaries now. Both image variants are signed with [cosign](https://github.com/sigstore/cosign) via keyless signing (GitHub OIDC), so if you're running in an environment that verifies image signatures you can trust they came straight from the release pipeline without any extra setup on your end. ### Helm chart If you're running this in Kubernetes, there's now an official Helm chart. No need to write your own manifests from scratch - the chart covers all the config options, handles the `ingress-nginx` defaultBackend and Traefik `errors` middleware setups, and ships with every release. Install it directly from the OCI registry: ```bash helm install error-pages oci://ghcr.io/tarampampam/error-pages/charts/error-pages --version X.Y.Z ``` Or as a dependency in your own `Chart.yaml`: ```yaml dependencies: - name: error-pages version: "X.Y.Z" repository: oci://ghcr.io/tarampampam/error-pages/charts ``` There's also a `helm-chart.tgz` attachment on every GitHub release if you'd rather install from a local file. Every chart release is signed with [cosign](https://github.com/sigstore/cosign) using keyless signing via GitHub OIDC, so you can verify the signature before deploying if supply chain security matters to you. The chart is also registered on ArtifactHub, where you can browse versions, config options, and the changelog without leaving your browser. ### Release artifacts The list of files attached to each GitHub release has changed significantly. What used to be a handful of raw platform binaries is now properly archived, covers both `error-pages` and `builder` across all supported platforms, and includes a few extras. Here's what you'll find in each release now: ``` error-pages-{os}-{arch}(.tar.gz|.zip) - the HTTP server (linux + darwin + windows / amd64 + arm64) builder-{os}-{arch}(.tar.gz|.zip) - the static page builder (same platforms) error-pages-static(.tar.gz|.zip) - pre-rendered static pages (from the builder) helm-chart.tgz - Helm chart checksums.txt - SHA256 checksums for everything above ``` Previously the release only shipped raw unarchived binaries for the `error-pages` server, a single `error-pages-static.zip`, and no checksums. If you have any scripts or CI pipelines that download release assets by filename - make sure to update them. > One concrete thing to watch out for - the old binary had no archive wrapper at all - the asset was literally named > `error-pages-linux-amd64` (or `error-pages-linux-amd64.exe` on Windows). Now that same binary lives inside > `error-pages-linux-amd64.tar.gz` / `error-pages-linux-amd64.zip`, so you'll need to extract it after downloading. ## 🔥 Upgrade guide ### Template syntax (Go templates) Below are all the variables and functions available in templates, and their syntax. If you used your own templates, you'll need to update them to match the new data structure passed to the template: ``` {{ code }} → {{ .StatusCode }} {{ message }} → {{ .Message }} {{ description }} → {{ .Description }} {{ original_uri }} → {{ .OriginalURI }} {{ host }} → {{ .Host }} {{ request_id }} → {{ .RequestID }} {{ namespace }} → {{ .Namespace }} {{ ingress_name }} → {{ .IngressName }} {{ service_name }} → {{ .ServiceName }} {{ service_port }} → {{ .ServicePort }} {{ forwarded_for }} → {{ .ForwardedFor }} {{ show_details }} → {{ .Config.ShowRequestDetails }} {{ hide_details }} → {{ not .Config.ShowRequestDetails }} {{ l10n_enabled }} → {{ not .Config.L10nDisabled }} {{ l10n_disabled }} → {{ .Config.L10nDisabled }} ``` > v4 still ships a temporary shim (`convertV3toV4`) that auto-rewrites the old syntax at parse time, so existing > templates keep rendering - but the shim is **deprecated and will be removed someday**. ### CMD / args The `serve`, `build`, and `healthcheck` subcommands are gone. The binary now runs the HTTP server directly: ```bash error-pages serve --port 8080 # v3 error-pages --port 8080 # v4 ``` Update your Dockerfile `CMD`, Kubernetes manifest `args`, systemd unit, or whatever else launches the binary. If you relied on `CMD ["serve"]` in the official image, drop it. ### Renamed environment variables Please review the new env var names and update them in your configs (some also changed format - like `ADD_CODE` - so be extra careful when updating): ``` TEMPLATES_ROTATION_MODE → ROTATION_MODE RESPONSE_JSON_FORMAT → JSON_TEMPLATE RESPONSE_XML_FORMAT → XML_TEMPLATE RESPONSE_PLAINTEXT_FORMAT → TEXT_TEMPLATE ``` > The old names are **not** aliased - they will be silently ignored. For the full list of new env vars, please refer to the [CLI documentation](CLI.md). ### Renamed flags - `--json-format` → `--json-template` - `--xml-format` → `--xml-template` - `--plaintext-format` → `--plaintext-template` - `--listen` is still accepted, but `--addr` is now the canonical name - `--template-name` is still accepted, but `--template` and `--theme` were dropped > [!WARNING] > Some short flags like `-l`, `-p`, and `-t` are gone. Use the long forms. ### Template functions **Good news:** all v3 function names still work as deprecated aliases - `nowUnix`, `json`, `strContains`, `strCount`, `strTrimSpace`, `strTrimPrefix`, `strTrimSuffix`, `strReplace`, `strIndex`, `strFields`. Existing templates keep rendering, but you should update them to the new names: | v3 (deprecated) | v4 | |-----------------------------|----------------------------------------------| | `nowUnix` (returns `int64`) | `now` (returns `time.Time`) | | `json` | `toJson` / `toJSON` | | `strContains` | `contains` | | `strCount` | `count` | | `strTrimSpace` | `trim` | | `strTrimPrefix` | `trimPrefix` | | `strTrimSuffix` | `trimSuffix` / `trimPostfix` | | `strReplace` | `replace` | | `strFields` | `fields` | | `strIndex` | *(no direct replacement, alias still works)* | > [!IMPORTANT] > **Argument order changed for the new names**. v3 string functions used Go's `strings.*` order (`haystack, needle`); > the v4 names are pipeline-friendly (`needle, haystack`). > > ``` > {{ strContains "test" "es" }} ← v3 alias, still works > {{ contains "es" "test" }} ← v4, args flipped > {{ "test" | contains "es" }} ← v4, idiomatic pipeline form > ``` > > If you blind-replace `strContains` → `contains` (or any of the other `str*` functions) without flipping the > arguments, your conditions will silently evaluate the wrong way around. Same applies to `strCount`, `strReplace`, > `strTrimPrefix`, `strTrimSuffix`. **Behavior changes worth knowing about:** - `now` returns `time.Time`, not an int. To get the old Unix timestamp use `{{ now.Unix }}`. The old `nowUnix` alias still returns `int` for backward compatibility. - `env` now masks values whose key contains `PASSWORD`, `SECRET`, `KEY`, `TOKEN`, `PASS`, `PWD`, or `CRED` (case-insensitive, segment-matched on `_`). The function returns a string of `*` of the same length instead of the actual value. If you were intentionally rendering one of these into a template, it won't work anymore. **New functions** (non-exhaustive - see template docs for the full list): `lower`, `upper`, `default`, `coalesce`, `ternary`, `hasPrefix`, `hasSuffix`, `split`, `join`, `quote`, `squote`, `repeat`, `substr`, `truncate`, `trimAll`, `urlEncode`, `toString` / `str`, `isEmpty`, `isNotEmpty`. All designed for pipeline use (`{{ .Message | default "Unknown" | upper }}`). ## Upgrade checklist Run through this in order: 1. **Drop `serve`** from every place that launches the binary (Dockerfile `CMD`, K8s `args`/`command`, systemd `ExecStart`, Compose `command`, shell scripts, CI). 2. **Rename env vars** in your configs. 3. **Replace short flags**. 4. **Rename `--*-format` flags** to `--*-template` (`--json-format` → `--json-template`, etc.; if you used `--add-template` with one file → switch to `--html-template`) 5. **Rewrite `--add-code` values**: replace `/` with `|`. If you have many entries, consider collapsing them into one value with `||`. 6. **Custom templates** - if you used `--add-template` with one file → switch to `--html-template`. 7. **Update template syntax** in any custom templates you ship. The v3-shim currently makes them work, but it's deprecated. 8. **Update query path pattern** - remove `.html` from your error page URLs if you had it (e.g., `/{status}.html` → `/{status}`) if you don't want to force HTML responses. 9. **Delete `--disable-minification` / `DISABLE_MINIFICATION`** from your config; it's a no-op now. 10. **Delete `--read-buffer-size` / `READ_BUFFER_SIZE`** from your config. 11. **Boot it up and test.** Hit `/404`, `/404.json`, `/404.xml`, `/404.txt` and confirm the right format comes back. **Test everything before you deploy to production.** --- If I missed something, or you've got questions about the upgrade - don't hesitate to open an issue or drop a note in discussions, I'll happily help you out. And thanks for using this project, I really appreciate it, and I'm doing my best to make it as good as it can be for you.