From 67535f170734f4d22d5045a2fd6d0097a9d43034 Mon Sep 17 00:00:00 2001
From: Justin Mclean <justin@classsoftware.com>
Date: Thu, 3 Sep 2026 06:43:02 +0000
Subject: [PATCH] fix(site): serve the site's own 404 page on iggy.apache.org

next build emits out/404.html, but the ASF web server never uses it and
answers unknown paths with its own bare "Not Found" body. Add a root
.htaccess setting ErrorDocument, and copy it into out/ alongside
.asf.yaml in both workflows.
---
 .github/workflows/deploy.yml |  4 +++-
 .github/workflows/stage.yml  |  4 +++-
 .htaccess                    | 23 +++++++++++++++++++++++
 CLAUDE.md                    |  1 +
 4 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100644 .htaccess

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 53a3839628..51be31b049 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -30,7 +30,9 @@ jobs:
         run: npm run build
 
       - name: Copy ASF config
-        run: cp .asf.yaml ./out/.asf.yaml
+        run: |
+          cp .asf.yaml ./out/.asf.yaml
+          cp .htaccess ./out/.htaccess
 
       - name: Publish Iggy Website to asf-site
         if: github.ref == 'refs/heads/main'
diff --git a/.github/workflows/stage.yml b/.github/workflows/stage.yml
index a58ab69515..8ec5f79085 100644
--- a/.github/workflows/stage.yml
+++ b/.github/workflows/stage.yml
@@ -28,7 +28,9 @@ jobs:
         run: npm run build
 
       - name: Copy ASF config
-        run: cp .asf.yaml ./out/.asf.yaml
+        run: |
+          cp .asf.yaml ./out/.asf.yaml
+          cp .htaccess ./out/.htaccess
 
       - name: Publish Iggy Website to asf-staging
         if: github.event_name == 'push' && github.ref == 'refs/heads/staging'
diff --git a/.htaccess b/.htaccess
new file mode 100644
index 0000000000..c2733fadd4
--- /dev/null
+++ b/.htaccess
@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Served from the site root on iggy.apache.org (published to asf-site).
+#
+# Without this, the ASF web server answers unknown paths with its own bare
+# "Not Found" body and the 404.html produced by `next build` is never used.
+# The status code stays 404 either way; this only replaces the body.
+ErrorDocument 404 /404.html
diff --git a/CLAUDE.md b/CLAUDE.md
index e8dcc364da..9d6bdd4774 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,4 +59,5 @@ No test framework is configured. No linter is configured beyond TypeScript stric
 - Push to `main` triggers `.github/workflows/deploy.yml` (also daily cron and manual dispatch), which builds and force-orphan-pushes `out/` to the `asf-site` branch -> iggy.apache.org.
 - Push to `staging` triggers `stage.yml`, same flow to `asf-staging` -> iggy.staged.apache.org. Use it to preview large changes.
 - `asf-site` and `asf-staging` are generated artifacts. Never edit them by hand.
+- Both workflows copy `.asf.yaml` and `.htaccess` into `out/` before publishing. The `.htaccess` sets `ErrorDocument 404 /404.html`; without it the ASF web server answers unknown paths with its own bare "Not Found" body instead of the site's 404 page (the status code is 404 either way).
 - Branch-to-URL mapping is configured via `.asf.yaml` (Apache infrastructure).