From f0f7723a61cd38a8bf1fbe7032f2ffd32ba7f8ee Mon Sep 17 00:00:00 2001
From: Ahmed Saleh <ahmed.saleh@bird.com>
Date: Tue, 21 Apr 2026 16:39:03 +0200
Subject: [PATCH] Containerize docs for self-hosting on eks-general
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Builds the Eleventy static site into a Docker image and publishes it
to ECR, matching the pattern already in use by pusher/engineering-
manual. The image is a thin nginx-unprivileged:1.27-alpine wrapper
around the built _site/ directory; k8s manifests will follow in a
platform-gitops PR.

Changes in this repo:

- Dockerfile + docker/nginx.conf: serves /docs/ on :8080, runs as
  non-root. Ports the 35 permanent redirects from vercel.json into
  nginx config. Preserves trailingSlash: true behavior via an explicit
  rewrite. Adds /healthz for k8s probes. Short TTL on HTML, 30 day
  immutable cache on /docs/static/* and on fingerprinted assets.

- .github/workflows/release.yml: AWS OIDC/ECR login, yarn build,
  optional Algolia index push on main, docker build, push to
  008815156580.dkr.ecr.us-east-1.amazonaws.com/pusher/docs. Copied
  from pusher/engineering-manual; PR builds push too (unique tag
  per commit, matches repo convention).

- package.json: split `build` into `build:css` + `build:site`. Add
  `update:algolia` task (kept the old `updateAlgoliaIndex` alias
  so nothing that calls the old name breaks).

- postcss.config.js, _data/env.js, search/update-algolia-index.js:
  read BUILD_ENV instead of VERCEL_ENV, falling back to VERCEL_ENV
  for a transition window. update-algolia-index.js now fails loudly
  if BUILD_ENV=production but ALGOLIA_UPDATE_KEY is missing.

- Drop api/search.js + the api/ directory: the Vercel serverless
  function that rendered HTML search results for users without JS.
  Client-side Algolia remains the primary experience; a <noscript>
  block now explains that search requires JavaScript.

- Drop vercel.json: rewrites and redirects both live in the pod
  nginx.conf now; trailingSlash is an explicit nginx rewrite.

- README: update deployment description; replace the Vercel-era
  "search fallback" note with a short local-docker-build recipe.

Smoke-tested locally:

    yarn install && yarn build
    docker build -t docs:test .
    docker run --rm -p 8080:8080 docs:test

  /healthz                         200 ok
  /docs/                           200, HTML
  /docs/channels/                  200, HTML
  /docs/security/                  301 -> https://pusher.com/security
  /docs/clusters/                  301 -> /docs/channels/miscellaneous/clusters/
  /docs/channels (no slash)        301 -> /docs/channels/
  /docs/does-not-exist/            404
  /docs/static/style.min.css       200, Cache-Control: public, max-age=2592000, immutable

Required secrets on this repo (GitHub Actions):

  ALGOLIA_UPDATE_KEY               (rotate from Vercel's copy)
  PUSHERINOS_AWS_ACCESS_KEY_ID     (existing pattern)
  PUSHERINOS_AWS_SECRET_ACCESS_KEY (existing pattern)
  PUSHER_CI_GITHUB_PRIVATE_TOKEN   (existing pattern)

Depends on: pusher/platform-infrastructure#chore/add-docs-ecr for
the ECR repository (`pusher/docs`).

See: pusher/engineering-manual PR — Marketing Website Vercel to EKS
Migration Plan.

Made-with: Cursor
---
 .dockerignore                  |  11 ++
 .github/workflows/release.yml  |  81 +++++++++++++
 Dockerfile                     |  18 +++
 README.md                      |  20 +++-
 _data/env.js                   |  12 +-
 _includes/partials/top-nav.njk |   5 +-
 api/search.js                  |  65 -----------
 docker/nginx.conf              | 104 +++++++++++++++++
 package.json                   |   7 +-
 postcss.config.js              |   8 +-
 search/update-algolia-index.js |  40 +++++--
 vercel.json                    | 208 ---------------------------------
 12 files changed, 282 insertions(+), 297 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 .github/workflows/release.yml
 create mode 100644 Dockerfile
 delete mode 100644 api/search.js
 create mode 100644 docker/nginx.conf
 delete mode 100644 vercel.json

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..124d061
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,11 @@
+# Keep the Docker build context minimal. _site/ is the only thing the image
+# actually needs (it's built on the CI runner before `docker build`).
+.git
+.github
+node_modules
+_tmp
+.cache
+.DS_Store
+*.md
+!README.md
+.vscode
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..e9636e2
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,81 @@
+name: release
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Only one push-to-ECR at a time per branch; queueing avoids racy tag pushes
+# if two commits land back to back.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Checkout/Install pusher/actions
+        uses: actions/checkout@v4
+        with:
+          repository: pusher/actions
+          token: ${{ secrets.PUSHER_CI_GITHUB_PRIVATE_TOKEN }}
+          path: .github/actions
+
+      - name: Define Common Env
+        id: common
+        uses: ./.github/actions/setup-common
+
+      - name: Set Env Vars
+        run: |
+          echo "VERSION=${{ steps.common.outputs.version }}" >> $GITHUB_ENV
+          echo "SHORT_SHA=${{ steps.common.outputs.short_sha }}" >> $GITHUB_ENV
+          echo "DATE=${{ steps.common.outputs.date }}" >> $GITHUB_ENV
+          echo "LONG_DATE=${{ steps.common.outputs.long_date }}" >> $GITHUB_ENV
+          echo "NAME=docs" >> $GITHUB_ENV
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build static site
+        env:
+          BUILD_ENV: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && 'production' || 'preview' }}
+        run: yarn build
+
+      - name: Update Algolia index
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        env:
+          ALGOLIA_UPDATE_KEY: ${{ secrets.ALGOLIA_UPDATE_KEY }}
+          BUILD_ENV: production
+        run: yarn update:algolia
+
+      - name: Build Docker image
+        run: |
+          docker build -t ${NAME}:${VERSION} .
+          echo "[BUILT] ${NAME}:${VERSION}"
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.PUSHERINOS_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.PUSHERINOS_AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Push image to Amazon ECR
+        run: |
+          echo "${{ steps.login-ecr.outputs.registry }}"
+          docker tag ${NAME}:${VERSION} ${{ steps.login-ecr.outputs.registry }}/pusher/${NAME}:${VERSION}
+          docker push ${{ steps.login-ecr.outputs.registry }}/pusher/${NAME}:${VERSION}
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..3c9e56b
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,18 @@
+# Build-time assets (_site/) are produced by the GitHub Actions runner before
+# `docker build` runs. This image is a thin static server.
+#
+# Using nginxinc/nginx-unprivileged so the master process runs as the non-root
+# `nginx` user (uid 101) and listens on :8080 — matches the k8s security
+# context used for the rest of our web workloads.
+#
+# Build locally:
+#   yarn install && yarn build && docker build -t docs:dev .
+#   docker run --rm -p 8080:8080 docs:dev
+#   open http://localhost:8080/docs/
+
+FROM nginxinc/nginx-unprivileged:1.27-alpine
+
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY _site /usr/share/nginx/html
+
+EXPOSE 8080
diff --git a/README.md b/README.md
index 76e89da..0efd07e 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,9 @@ permalink: docs/README/
 
 An [Eleventy] powered static site using our custom [Tachyons] build with [Postcss] for styling.
 
-It’s deployed and hosted by [Vercel] when the `main` branch changes using their [Github integration] - https://pusher-docs.vercel.app
+It's built and served from our own EKS cluster (`eks-general`). On every push to `main`, GitHub Actions (`.github/workflows/release.yml`) builds the static site, pushes a Docker image to ECR (`008815156580.dkr.ecr.us-east-1.amazonaws.com/pusher/docs`), and Flux deploys it to the `docs` Service in the `internal` namespace. Public traffic reaches it via CloudFront → the `pusher-sites` nginx proxy → this pod.
+
+See the migration plan in `pusher/engineering-manual` for the full setup.
 
 ## Running locally
 
@@ -43,11 +45,19 @@ yarn run css
 
 ### Search
 
-Search is powered by Algolia, on every production build a refreshed index of all content is sent to them.
+Search is powered by Algolia; on every `main` production build, `yarn update:algolia` pushes a refreshed index. The primary search experience is client-side JS (see `js/modules/search.mjs`). Users with JavaScript disabled see a short fallback message — no server-side rendering is offered.
+
+Required secret for the Algolia push: `ALGOLIA_UPDATE_KEY`, set as a GitHub Actions secret on this repo.
 
-For users without JS there is a fallback page which is powered by Vercel’s serverless functions.
+### Building a production-like image locally
 
-If you need to debug this you can run the project with `vercel dev` and it will hot reload any changes.
+```bash
+yarn install
+yarn build
+docker build -t docs:dev .
+docker run --rm -p 8080:8080 docs:dev
+open http://localhost:8080/docs/
+```
 
 ## How to add / update new pages
 
@@ -226,8 +236,6 @@ Contributions welcome!
 [eleventy]: https://www.11ty.io
 [tachyons]: http://tachyons.io/
 [postcss]: https://postcss.org
-[vercel]: https://vercel.co/
-[github integration]: https://vercel.com/docs/git-integrations
 [markdown]: https://www.markdownguide.org/
 [yarn]: https://yarnpkg.com/
 [browsersync]: https://www.browsersync.io/
diff --git a/_data/env.js b/_data/env.js
index 0455ba3..81984c4 100644
--- a/_data/env.js
+++ b/_data/env.js
@@ -1,4 +1,14 @@
+// BUILD_ENV is set by the release workflow:
+//   "production" on main pushes
+//   "preview"    on pull requests
+//   unset        in local dev (treat as non-production)
+//
+// Kept named `VERCEL_ENV` historically; the new pipeline sets `BUILD_ENV`
+// but we read both so local tools that still export `VERCEL_ENV` keep
+// working during the transition.
+const env = process.env.BUILD_ENV || process.env.VERCEL_ENV;
+
 module.exports = {
-  includeAnalytics: process.env.VERCEL_ENV === "production",
+  includeAnalytics: env === "production",
   pusherJSVersion: "8.3.0",
 };
diff --git a/_includes/partials/top-nav.njk b/_includes/partials/top-nav.njk
index ef2cbee..5e30b33 100644
--- a/_includes/partials/top-nav.njk
+++ b/_includes/partials/top-nav.njk
@@ -63,11 +63,14 @@
     <nav class="dn db-l flex-grow-1" style="margin-left: 6px;">
       <ul class="list pa0 ma0 flex items-center justify-center">
         <li class="ml-auto relative w-40-l" id="search-wrap">
-          <form id="search-form" type="POST" action="/docs/api/search">
+          <form id="search-form" action="/docs/" method="get" onsubmit="return false;">
             <label for="search" class="clip">
               Search Pusher documentation
             </label>
             <input name="t" id="search" type="search" value="" placeholder="Search documentation" class="sans-serif black f7 input-reset br2 ba b--smoke hover-b--silver focus-b--starflower focus-bs-starflower pa3 lh-solid h3 w-100" maxlength="200">
+            <noscript>
+              <p class="f7 pt2 lh-copy steel ma0">Search requires JavaScript. <a href="/docs/" class="link eggplant hover-dragonfruit underline">Browse the docs</a>.</p>
+            </noscript>
           </form>
           <div class="br2 mt2 ba b--smoke absolute left-0 right-0 dn bg-snow-light" id="search-results-wrap">
             <ul class="bg-white list ma0 pa0 overflow-y-auto bb b--smoke br2 br--top" style="top: 100%; max-height: 60vh;" id="search-results"></ul>
diff --git a/api/search.js b/api/search.js
deleted file mode 100644
index 216c260..0000000
--- a/api/search.js
+++ /dev/null
@@ -1,65 +0,0 @@
-import algoliasearch from "algoliasearch";
-import { sanitize } from "isomorphic-dompurify";
-
-const { ALGOLIA_SEARCH_KEY } = process.env;
-
-const client = algoliasearch("BQ93464WAA", ALGOLIA_SEARCH_KEY);
-const searchIndex = client.initIndex("docs");
-
-// https://wesbos.com/sanitize-html-es6-template-strings
-function sanitizer(strings, ...values) {
-  const dirty = strings.reduce(
-    (prev, next, i) => `${prev}${next}${values[i] || ""}`,
-    ""
-  );
-  return sanitize(dirty);
-}
-
-module.exports = async (req, res) => {
-  const { t } = req.query;
-  const sanitizedSearchTerm = sanitizer`${t}`;
-
-  try {
-    const { hits: results } = await searchIndex.search(sanitizedSearchTerm, {
-      hitsPerPage: 10,
-      attributesToRetrieve: ["title", "url"],
-      attributesToSnippet: ["content"],
-      snippetEllipsisText: "…",
-    });
-
-    res.status(200).send(
-      `<!DOCTYPE html>
-      <html lang="en">
-        <head>
-          <meta charset="utf-8" />
-          <meta name="viewport" content="width=device-width, initial-scale=1" />
-          <title>Search results for "${sanitizedSearchTerm}"</title>
-          <link href="/docs/static/style.min.css" rel="stylesheet" />
-        </head>
-        <body class="pa5 mw7 center">
-          <a class="flex items-center link eggplant hover-dragonfruit" href="/">
-            <svg width="145" height="38" class="ma0 mr3" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 145 38"><path fill="#300D4F" d="M12.31 37.946V28.42c0-.02.011-.04.03-.05l12.252-7.068a.055.055 0 00.029-.05v-2.708a.056.056 0 00-.085-.05l-12.14 7.004a.056.056 0 01-.085-.05v-2.71c0-.02.01-.039.028-.049l12.253-7.068a.059.059 0 00.029-.05v-2.708a.058.058 0 00-.085-.05l-12.14 7.003a.056.056 0 01-.086-.049v-2.709c0-.02.011-.039.03-.049l12.252-7.065a.056.056 0 00.029-.05V7.15a.12.12 0 00-.056-.098L12.367.015a.112.112 0 00-.113 0l-2.32 1.339a.056.056 0 000 .098l12.14 7.003a.058.058 0 010 .098l-2.32 1.338a.12.12 0 01-.114 0L7.443 2.856a.12.12 0 00-.12 0L5.01 4.193a.056.056 0 000 .098l12.138 7.004a.056.056 0 010 .099l-2.32 1.338a.12.12 0 01-.12 0L2.519 5.695a.12.12 0 00-.12 0L0 7.083V30.91c0 .02.01.04.029.049l2.348 1.355a.056.056 0 00.085-.05V8.603a.056.056 0 01.085-.049l2.35 1.355c.016.01.027.029.027.05V33.75c0 .02.01.04.028.05L7.3 35.156a.058.058 0 00.087-.05V11.442a.056.056 0 01.085-.05l2.348 1.354c.018.01.029.03.029.05v23.795c0 .02.01.039.027.05l2.355 1.353a.056.056 0 00.08-.049z"/><path fill="#300D4F" fill-rule="evenodd" d="M36.934 7.512v22.933c.01.242.195.44.436.466h2.478a.427.427 0 00.437-.43v-9.546a.23.23 0 01.23-.223h3.642c4.003 0 7.053-2.683 7.053-6.898s-2.688-6.731-7.014-6.731h-6.823a.427.427 0 00-.44.429zm10.845 6.302c0 2.162-1.296 4.064-3.583 4.064l-3.675-.003a.229.229 0 01-.23-.224v-7.548a.23.23 0 01.224-.224h3.68c2.403 0 3.584 1.697 3.584 3.935z" clip-rule="evenodd"/><path fill="#300D4F" d="M65.33 7.046h2.478a.427.427 0 01.44.429V24.8c0 3.935-3.222 6.34-6.996 6.34-3.698 0-6.919-2.424-6.919-6.34V7.475a.427.427 0 01.438-.43h2.44a.427.427 0 01.44.43v17.264c0 2.144 1.637 3.505 3.582 3.505 1.945 0 3.622-1.361 3.622-3.505V7.487a.503.503 0 01.476-.441zM76.767 18.83c-2.363-1.586-3.945-3.356-3.945-6.024 0-3.822 3.221-6.021 6.88-6.021 3.45 0 6.476 1.917 6.653 6.768a.46.46 0 01-.44.466h-2.267a.436.436 0 01-.439-.41c-.152-2.636-1.734-3.897-3.717-3.897-1.907 0-3.336 1.119-3.336 2.909 0 1.546.934 2.386 3.374 4.1l3.412 2.462c2.363 1.715 3.697 3.263 3.697 5.705 0 3.954-3.26 6.302-7.09 6.302-3.622 0-6.476-1.976-6.786-6.823a.436.436 0 01.44-.468h2.305a.45.45 0 01.438.411c.21 2.703 1.83 3.954 3.736 3.954 1.83 0 3.545-.988 3.545-3.3 0-1.438-.647-2.144-2.518-3.394l-3.942-2.74zM102.593 30.445v-10.03a.228.228 0 00-.229-.225h-7.299c-.124 0-.226.1-.229.224v10.03a.427.427 0 01-.439.428H91.92a.427.427 0 01-.44-.427V7.512a.427.427 0 01.44-.43h2.477a.427.427 0 01.44.43v9.585a.229.229 0 00.228.222h7.299a.228.228 0 00.229-.222V7.512a.429.429 0 01.439-.43h2.478a.427.427 0 01.439.43v22.95a.429.429 0 01-.439.43h-2.478a.442.442 0 01-.439-.447zM112.219 30.445V7.512a.426.426 0 01.438-.429h12.122a.424.424 0 01.439.429v1.995a.429.429 0 01-.439.428h-8.977a.23.23 0 00-.229.224v7.029a.229.229 0 00.229.224h6.176a.425.425 0 01.437.429v1.994a.423.423 0 01-.437.43h-6.176a.23.23 0 00-.229.223v7.309a.23.23 0 00.229.224h8.977c.239 0 .434.19.439.429v1.995a.44.44 0 01-.439.427h-12.122a.413.413 0 01-.438-.427z"/><path fill="#300D4F" fill-rule="evenodd" d="M137.035 20.47l3.659 9.975a.805.805 0 00.591.486h2.574a.437.437 0 00.419-.599l-4.136-10.57a.096.096 0 010-.079.093.093 0 01.057-.052c2.516-1.268 3.889-3.43 3.889-6.022 0-3.898-2.859-6.526-7.014-6.526h-6.786a.428.428 0 00-.438.429v22.933a.426.426 0 00.438.427h2.477a.425.425 0 00.439-.427v-9.901a.229.229 0 01.229-.223h3.393c.094 0 .178.06.209.148zm3.564-6.73c0 2.46-1.791 3.859-3.793 3.859l-3.354-.02a.23.23 0 01-.229-.224v-7.271a.209.209 0 01.21-.205h3.373c2.364 0 3.793 1.66 3.793 3.86z" clip-rule="evenodd"/></svg> <strong>DOCS</strong>
-          </a>
-          <h1 class="f1">Search results for “${sanitizedSearchTerm}”</h1>
-          <ul class="list ma0 pa0">
-            ${results
-              .map(
-                (result) =>
-                  `<li class="bb b--smoke f5"><a href="${result.url}" class="pa4 db link eggplant hover-dragonfruit hover-bg-snow-light">
-                    <strong class="db">${result.title}</strong>
-                    <p class="ma0 search-snippet">${result._snippetResult.content.value}</p>
-                  </a></li>`
-              )
-              .join("")}
-          </ul>
-          <footer class="f6 pv3 ph4 steel">
-            <p class="ma0">Search powered by <a href="https://www.algolia.com/" rel="noreferrer" class="link eggplant hover-dragonfruit underline">Algolia</a></p>
-            <p class="mt6 measure-wide">This page is the fallback search for when JavaScript search is unavailable. The docs are statically generated with <a href="https://www.11ty.dev/" rel="noreferrer" class="link eggplant hover-dragonfruit underline">11ty</a> but this page runs on <a href="https://vercel.com" rel="noreferrer" class="link eggplant hover-dragonfruit underline">Vercel</a> as a <a href="https://vercel.com/docs/serverless-functions/introduction" rel="noreferrer" class="link eggplant hover-dragonfruit underline">serverless function</a>. You can see <a href="https://github.com/pusher/docs/blob/main/api/search.js" rel="noreferrer" class="link eggplant hover-dragonfruit underline">the source code on&nbsp;Github</a>.</p>
-          </footer>
-        </body>
-      </html>`
-    );
-  } catch (error) {
-    res.status(500).send(`There was an error processing his request: ${error}`);
-  }
-};
diff --git a/docker/nginx.conf b/docker/nginx.conf
new file mode 100644
index 0000000..43345f3
--- /dev/null
+++ b/docker/nginx.conf
@@ -0,0 +1,104 @@
+# Served inside a pod in eks-general. The public URL is https://pusher.com/docs/,
+# reached via the `pusher-sites` reverse proxy which forwards the full path.
+#
+# All files live under /usr/share/nginx/html/docs/... (baked into the image
+# at build time from Eleventy's _site/ output). `/docs/...` paths therefore
+# map 1:1 to filesystem paths.
+
+server {
+    listen       8080 default_server;
+    server_name  _;
+
+    root   /usr/share/nginx/html;
+    index  index.html;
+
+    # k8s liveness/readiness probe
+    location = /healthz {
+        access_log off;
+        default_type text/plain;
+        return 200 "ok\n";
+    }
+
+    # Permanent redirects migrated from the old vercel.json. Keep alphabetically
+    # grouped; add new ones here rather than in app code or upstream nginx.
+    location = /docs/beams/concepts/interests/                   { return 301 /docs/beams/concepts/device-interests/; }
+    location = /docs/beams/guides/handle-notifications/          { return 301 /docs/beams/guides/handle-incoming-notifications/ios/; }
+    location = /docs/beams/guides/handle-incoming-notifications/ { return 301 /docs/beams/guides/handle-incoming-notifications/io/; }
+    location = /docs/beams/guides/publishing-to-users/           { return 301 /docs/beams/guides/publish-to-specific-user/ios/; }
+    location = /docs/beams/guides/publish-to-specific-user/      { return 301 /docs/beams/guides/publish-to-specific-user/ios/; }
+    location = /docs/push_notifications/overview/                { return 301 /docs/beams/; }
+
+    location = /docs/client_api_guide/                            { return 301 /docs/channels/using_channels/client-api-overview/; }
+    location = /docs/client_api_guide/client_connect/             { return 301 /docs/channels/using_channels/connection/; }
+    location = /docs/client_api_guide/client_authorized_connections/ { return 301 /docs/channels/using_channels/authorized-connections/; }
+    location = /docs/client_api_guide/client_channels/            { return 301 /docs/channels/using_channels/channels/; }
+    location = /docs/client_api_guide/client_public_channels/     { return 301 /docs/channels/using_channels/public-channels/; }
+    location = /docs/client_api_guide/client_private_channels/    { return 301 /docs/channels/using_channels/private-channels/; }
+    location = /docs/client_api_guide/client_encrypted_channels/  { return 301 /docs/channels/using_channels/encrypted-channels/; }
+    location = /docs/client_api_guide/client_presence_channels/   { return 301 /docs/channels/using_channels/presence-channels/; }
+    location = /docs/client_api_guide/client_events/              { return 301 /docs/channels/using_channels/events/; }
+    location = /docs/client_api_guide/client_global_configuration/ { return 301 /docs/channels/using_channels/global-config/; }
+
+    location = /docs/server_api_guide/                              { return 301 /docs/channels/server_api/overview/; }
+    location = /docs/server_api_guide/interact_rest_api/            { return 301 /docs/channels/server_api/http-api/; }
+    location = /docs/server_api_guide/server_excluding_recipients/  { return 301 /docs/channels/server_api/excluding-event-recipients/; }
+
+    location = /docs/pusher_cli/overview/       { return 301 /docs/channels/pusher_cli/overview/; }
+    location = /docs/pusher_cli/installation/   { return 301 /docs/channels/pusher_cli/installation/; }
+    location = /docs/pusher_cli/documentation/  { return 301 /docs/channels/pusher_cli/documentation/; }
+
+    location = /docs/android_quick_start/       { return 301 /docs/channels/getting_started/android/; }
+    location = /docs/ios_quick_start/           { return 301 /docs/channels/getting_started/ios/; }
+    location = /docs/ios-quick-start/           { return 301 /docs/channels/getting_started/ios/; }
+    location = /docs/javascript_quick_start/    { return 301 /docs/channels/getting_started/javascript/; }
+    location = /docs/javascript-quick-start/    { return 301 /docs/channels/getting_started/javascript/; }
+
+    location = /docs/auth_signatures/           { return 301 /docs/channels/library_auth_reference/auth-signatures/; }
+    location = /docs/authenticating_users/      { return 301 /docs/channels/server_api/authenticating-users/; }
+    location = /docs/clusters/                  { return 301 /docs/channels/miscellaneous/clusters/; }
+    location = /docs/debugging/                 { return 301 /docs/channels/getting_started/debugging/; }
+    location = /docs/device_compatibility/      { return 301 /docs/channels/using_channels/device-compatibility/; }
+    location = /docs/fallbacks/                 { return 301 /docs/channels/using_channels/websocket-fallbacks/; }
+    location = /docs/integrations/              { return 301 /docs/channels/miscellaneous/integrations/; }
+    location = /docs/libraries/                 { return 301 /docs/channels/channels_libraries/libraries/; }
+    location = /docs/pusher_protocol/           { return 301 /docs/channels/library_auth_reference/pusher-websockets-protocol/; }
+    location = /docs/rest_api/                  { return 301 /docs/channels/library_auth_reference/rest_api/; }
+    location = /docs/webhooks/                  { return 301 /docs/channels/server_api/webhooks/; }
+
+    location = /docs/security/                                { return 301 https://pusher.com/security; }
+    location = /docs/channels/miscellaneous/security/         { return 301 https://pusher.com/security; }
+
+    # Everything else: serve static files under /docs. Eleventy emits
+    # directory-style pages (each page is `/docs/foo/index.html`), so a
+    # trailing-slash URL maps directly to `$uri/index.html`.
+    location / {
+        # Canonicalize: requests for non-file, non-slashed paths (e.g. /docs/beams)
+        # get a 301 to the slashed form to match the old `trailingSlash: true`
+        # behavior on Vercel. Any path with a dot is considered a file and is
+        # served as-is.
+        rewrite ^/([^.]+[^/])$ /$1/ permanent;
+
+        try_files $uri $uri/ $uri.html $uri/index.html =404;
+
+        # Short TTL on HTML; CloudFront will still cache, but content publishes
+        # can propagate in ~a minute rather than waiting for a full invalidation.
+        add_header Cache-Control "public, max-age=60, s-maxage=60" always;
+    }
+
+    # Long cache on fingerprinted static assets. Eleventy + postcss produce
+    # /docs/static/style.min.css plus any hashed build artefacts under /docs/static/.
+    location ~* ^/docs/static/ {
+        expires off;
+        add_header Cache-Control "public, max-age=2592000, immutable" always;
+        try_files $uri =404;
+    }
+
+    # Common immutable file extensions anywhere in the tree.
+    location ~* \.(?:css|js|woff2?|ttf|eot|otf|png|jpg|jpeg|gif|svg|ico|webp|mp4|webm)$ {
+        expires off;
+        add_header Cache-Control "public, max-age=2592000, immutable" always;
+        try_files $uri =404;
+    }
+
+    error_page 404 /docs/404.html;
+}
diff --git a/package.json b/package.json
index c44b723..6d2aa5e 100644
--- a/package.json
+++ b/package.json
@@ -7,9 +7,12 @@
   "license": "MIT",
   "scripts": {
     "dev": "eleventy --serve",
-    "build": "postcss css/style.pcss -o _site/docs/static/style.min.css && ELEVENTY_PRODUCTION=true eleventy && yarn updateAlgoliaIndex",
+    "build": "yarn build:css && yarn build:site",
+    "build:css": "postcss css/style.pcss -o _site/docs/static/style.min.css",
+    "build:site": "ELEVENTY_PRODUCTION=true eleventy",
     "css": "postcss css/style.pcss -o _tmp/style.min.css -w --verbose",
-    "updateAlgoliaIndex": "node ./search/update-algolia-index.js"
+    "update:algolia": "node ./search/update-algolia-index.js",
+    "updateAlgoliaIndex": "yarn update:algolia"
   },
   "devDependencies": {
     "@11ty/eleventy": "1.0.2",
diff --git a/postcss.config.js b/postcss.config.js
index 9598af8..132c966 100644
--- a/postcss.config.js
+++ b/postcss.config.js
@@ -1,6 +1,10 @@
 const purgecss = require("@fullhuman/postcss-purgecss");
-const { VERCEL_ENV } = process.env;
-const is_prod_like = VERCEL_ENV === "production" || VERCEL_ENV === "preview";
+
+// BUILD_ENV is set by the release workflow (see .github/workflows/release.yml).
+// `VERCEL_ENV` is accepted as a fallback so the pipeline keeps working during
+// the transition off Vercel and for anyone still exporting it locally.
+const env = process.env.BUILD_ENV || process.env.VERCEL_ENV;
+const is_prod_like = env === "production" || env === "preview";
 
 module.exports = {
   plugins: [
diff --git a/search/update-algolia-index.js b/search/update-algolia-index.js
index 913dd8d..71841ff 100644
--- a/search/update-algolia-index.js
+++ b/search/update-algolia-index.js
@@ -1,15 +1,31 @@
 const algoliasearch = require("algoliasearch");
 const records = require("../_site/search/all.json");
-const { ALGOLIA_UPDATE_KEY, VERCEL_ENV } = process.env;
-
-if (VERCEL_ENV === "production") {
-  const client = algoliasearch("BQ93464WAA", ALGOLIA_UPDATE_KEY);
-  const index = client.initIndex("docs");
-
-  index
-    .replaceAllObjects(records, { autoGenerateObjectIDIfNotExist: true })
-    .then(() => console.log("Algolia index updated"))
-    .catch((error) => console.error("Failed to Algolia update index", error));
-} else {
-  console.log("Skipped Algolia update because this is not production");
+
+// BUILD_ENV is set by the release workflow (see .github/workflows/release.yml).
+// `VERCEL_ENV` is accepted as a fallback so the existing pipeline keeps
+// working during the transition off Vercel.
+const { ALGOLIA_UPDATE_KEY } = process.env;
+const env = process.env.BUILD_ENV || process.env.VERCEL_ENV;
+
+if (env !== "production") {
+  console.log(`Skipping Algolia update because env=${env || "unset"} (expected "production").`);
+  process.exit(0);
+}
+
+if (!ALGOLIA_UPDATE_KEY) {
+  console.error(
+    "ALGOLIA_UPDATE_KEY is not set but env=production. Refusing to run a production build without the Algolia key."
+  );
+  process.exit(1);
 }
+
+const client = algoliasearch("BQ93464WAA", ALGOLIA_UPDATE_KEY);
+const index = client.initIndex("docs");
+
+index
+  .replaceAllObjects(records, { autoGenerateObjectIDIfNotExist: true })
+  .then(() => console.log("Algolia index updated"))
+  .catch((error) => {
+    console.error("Failed to update Algolia index", error);
+    process.exit(1);
+  });
diff --git a/vercel.json b/vercel.json
deleted file mode 100644
index 880cff1..0000000
--- a/vercel.json
+++ /dev/null
@@ -1,208 +0,0 @@
-{
-  "rewrites": [
-    { "source": "/docs/api/:match*", "destination": "/api/:match*" }
-  ],
-  "redirects": [
-    {
-      "source": "/docs/beams/concepts/interests/",
-      "destination": "/docs/beams/concepts/device-interests/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/beams/guides/handle-notifications/",
-      "destination": "/docs/beams/guides/handle-incoming-notifications/ios/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/beams/guides/handle-incoming-notifications/",
-      "destination": "/docs/beams/guides/handle-incoming-notifications/io/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/beams/guides/publishing-to-users/",
-      "destination": "/docs/beams/guides/publish-to-specific-user/ios/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/beams/guides/publish-to-specific-user/",
-      "destination": "/docs/beams/guides/publish-to-specific-user/ios/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/push_notifications/overview/",
-      "destination": "/docs/beams/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_connect/",
-      "destination": "/docs/channels/using_channels/connection/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_authorized_connections/",
-      "destination": "/docs/channels/using_channels/authorized-connections/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_channels/",
-      "destination": "/docs/channels/using_channels/channels/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_public_channels/",
-      "destination": "/docs/channels/using_channels/public-channels/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_private_channels/",
-      "destination": "/docs/channels/using_channels/private-channels/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_encrypted_channels/",
-      "destination": "/docs/channels/using_channels/encrypted-channels/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_presence_channels/",
-      "destination": "/docs/channels/using_channels/presence-channels/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_events/",
-      "destination": "/docs/channels/using_channels/events/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/client_global_configuration/",
-      "destination": "/docs/channels/using_channels/global-config/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/server_api_guide/interact_rest_api/",
-      "destination": "/docs/channels/server_api/http-api/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/server_api_guide/server_excluding_recipients/",
-      "destination": "/docs/channels/server_api/excluding-event-recipients/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/pusher_cli/overview/",
-      "destination": "/docs/channels/pusher_cli/overview/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/pusher_cli/installation/",
-      "destination": "/docs/channels/pusher_cli/installation/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/pusher_cli/documentation/",
-      "destination": "/docs/channels/pusher_cli/documentation/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/android_quick_start/",
-      "destination": "/docs/channels/getting_started/android/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/auth_signatures/",
-      "destination": "/docs/channels/library_auth_reference/auth-signatures/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/authenticating_users/",
-      "destination": "/docs/channels/server_api/authenticating-users/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/client_api_guide/",
-      "destination": "/docs/channels/using_channels/client-api-overview/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/clusters/",
-      "destination": "/docs/channels/miscellaneous/clusters/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/debugging/",
-      "destination": "/docs/channels/getting_started/debugging/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/device_compatibility/",
-      "destination": "/docs/channels/using_channels/device-compatibility/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/fallbacks/",
-      "destination": "/docs/channels/using_channels/websocket-fallbacks/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/integrations/",
-      "destination": "/docs/channels/miscellaneous/integrations/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/ios_quick_start/",
-      "destination": "/docs/channels/getting_started/ios/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/javascript_quick_start/",
-      "destination": "/docs/channels/getting_started/javascript/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/ios-quick-start/",
-      "destination": "/docs/channels/getting_started/ios/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/javascript-quick-start/",
-      "destination": "/docs/channels/getting_started/javascript/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/libraries/",
-      "destination": "/docs/channels/channels_libraries/libraries/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/pusher_protocol/",
-      "destination": "/docs/channels/library_auth_reference/pusher-websockets-protocol/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/server_api_guide/",
-      "destination": "/docs/channels/server_api/overview/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/security/",
-      "destination": "https://pusher.com/security",
-      "permanent": true
-    },
-    {
-      "source": "/docs/channels/miscellaneous/security/",
-      "destination": "https://pusher.com/security",
-      "permanent": true
-    },
-    {
-      "source": "/docs/rest_api/",
-      "destination": "/docs/channels/library_auth_reference/rest_api/",
-      "permanent": true
-    },
-    {
-      "source": "/docs/webhooks/",
-      "destination": "/docs/channels/server_api/webhooks/",
-      "permanent": true
-    }
-  ],
-   "trailingSlash": true
-}