[DOC] Best approach to run a single page application with client-side routing?

[spwoodcock]

Description

Awesome project 🎉

• However, it's not very clear how to run a single page application via SERVE_FILES.
• Accessing the root of the page works fine, but any client-side routing returns a 404, redirecting to the default bunkerweb 404 page.
• The user may wish to access the SPA via a direct URL, e.g. https://some.domain.com/projects/1, instead of having to go to https://some.domain.com, then navigate via the app.

Example config:

# Used for both bunkerweb proxy + scheduler (config) service
x-proxy-env: &proxy-env
  # General
  BUNKERWEB_INSTANCES: proxy:5000
  LOG_LEVEL: notice
  DISABLE_DEFAULT_SERVER: yes
  API_WHITELIST_IP: 127.0.0.0/8 10.20.30.0/24
  SERVE_FILES: yes
  USE_BROTLI: yes
  SERVER_NAME: some.domain.com

services:
  proxy:
    image: "ghcr.io/bunkerity/bunkerweb:${BUNKERWEB_TAG:-1.6.0}"
    volumes:
      - nginx-configs:/etc/nginx
      - certs:/var/cache/bunkerweb/letsencrypt
      - spa_frontend:/var/www/html/some.domain.org:ro
    environment: *proxy-env
    ports:
      - 80:8080
      - 443:8443
    networks:
      - my-network
    restart: "unless-stopped"

  # This is needed by bunkerweb to generate the nginx configs
  proxy-setup:
    image: "ghcr.io/bunkerity/bunkerweb-scheduler:${BUNKERWEB_TAG:-1.6.0}"
    depends_on:
      proxy:
        condition: service_started
    volumes:
      - nginx-configs:/etc/nginx
      - certs:/var/cache/bunkerweb/letsencrypt
    environment: *proxy-env
    networks:
      - my-network
    restart: "no"
    # If success or timeout exits with 0 code, else use actual exit code
    entrypoint: sh -c 'timeout 120 ./entrypoint.sh || [ $? -eq 124 ] && exit 0'

Proposed solution (optional)

Option 1: Modify serve-files.conf

The serve-files.conf file is as such:

bunkerweb/src/common/core/misc/confs/server-http/serve-files.conf

Lines 1 to 6 in 00e7529

	{%- if SERVE_FILES == "yes" -%}
	root {% if ROOT_FOLDER == "" %}/var/www/html/{% if MULTISITE == "yes" %}{{ SERVER_NAME.split(" ")[0] }}{% endif %}{% else %}{{ ROOT_FOLDER }}{% endif %};
	try_files $uri $uri/ =404;
	{%- else -%}
	root /nowhere;
	{%- endif %}

• A simple solution would be to try the request on index.html, prior to returning a 404.
  try_files $uri $uri/ =404 --> try_files $uri $uri/ /index.html =404
• This is the preferred solution IMO, but would require a PR (happy to do this).

Option 2: Override the 404

• In the config above, it should be possible to add environment variable:

  some.domain.com_ERRORS: 404=/index.html

• This would override the 404 response and point it to index.html, so that the SPA can handle the client-side routing.

I'm interested to hear if others have encountered this, or if there is an approach I have not considered that would be preferred 🙏