feat: add ability to run local Apache server to test htaccess redirec…

…ts (#1421)

* feat: add a dockerfile for testing htaccess rules locally

* feat: add a docker-compose file for running a local webserver to test htaccess rules

* docs: explain how to use docker compose to test htaccess rules locally

* docs: add more details based on feedback

Dockerfile

@@ -0,0 +1,19 @@
+# For local development purposes only
+
+FROM httpd:alpine
+
+RUN rm -r /usr/local/apache2/htdocs/*
+COPY /build /usr/local/apache2/htdocs/
+
+# Remove SSL requirement
+RUN sed -i \
+        '/SERVER_PORT/d;/SERVER_NAME/d' \
+        /usr/local/apache2/htdocs/.htaccess
+
+# Enable the rewrite module
+RUN sed -i \
+        -e 's/^#\(LoadModule .*mod_rewrite.so\)/\1/' \
+        /usr/local/apache2/conf/httpd.conf
+
+# Enable rewrites
+RUN sed -i '/<Directory "\/usr\/local\/apache2\/htdocs">/,/<\/Directory>/ s/AllowOverride None/AllowOverride All/' /usr/local/apache2/conf/httpd.conf

docker-compose.yml

@@ -0,0 +1,6 @@
+version: "3.9"
+services:
+  webserver:
+    build: .
+    ports:
+      - "3001:80"

howtos/documentation-guidelines.md

@@ -125,8 +125,7 @@ When linking internally from one document to another, follow these guidelines:
 3. If the doc is [in one of the shared sections](#synchronization-of-sidebars), update [the opposite instance's corresponding sidebars file(s)](#sidebar-navigation).
 4. Add necessary redirect/rewrite rules to the top of `.htaccess`.
 
-> **Note**
-> The redirects/rewrite rules added to `.htaccess` will not work when running the documentation locally. You can use online tooling to help with this (e.g. https://htaccess.madewithlove.com/).
+See [Redirect rules](#redirect-rules) for information on testing `.htaccess` rules.
 
 ## Remove an existing page
 
@@ -135,8 +134,29 @@ When linking internally from one document to another, follow these guidelines:
 3. If the doc is [in one of the shared sections](#synchronization-of-sidebars), update [the opposite instance's corresponding sidebars file(s)](#sidebar-navigation).
 4. Add necessary redirect/rewrite rules to the top of `.htaccess` to redirect users to appropriate relevant content on another page.
 
-> **Note**
-> The redirects/rewrite rules added to `.htaccess` will not work when running the documentation locally. You can use online tooling to help with this (e.g. https://htaccess.madewithlove.com/).
+See [Redirect rules](#redirect-rules) for information on testing `.htaccess` rules.
+
+## Redirect rules
+
+The `.htaccess` file contains redirect rules that are applied to the published site, but it has no effect when running docusaurus locally (via `npm start`).
+
+If you wish to test `.htaccess` rules, you have a couple options:
+
+1. Use online tooling to test rules.
+   Tools like https://htaccess.madewithlove.com/ apply a set of redirect rules to a specific URL. Note that there are edge cases where this tool doesn't give the same results as a published environment.
+
+2. Use `docker compose` to spin up a locally-running Apache webserver.
+   This repo includes Docker configuration ([Dockerfile](../Dockerfile) and [docker-compose.yml](../docker-compose.yml)) to spin up a local environment that better simulates a published environment. Redirect rules can then be tested directly in a browser.
+
+   The local server is based on the contents of your `./build` folder. To start this local server:
+
+   1. Build the docs with `npm run build`.
+   2. Start the server with `docker compose up`.
+   3. Browse http://localhost:3001 and test redirects.
+
+      It is probably best to do this in an incognito browser session, as browsers clutch tightly to 301 redirects.
+
+   4. Clean up the server with `docker compose down`.
 
 ## Review Process