[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 🙏

[spwoodcock]

Hi @TheophileDiot, was the 'Help Wanted' label added because you would accept a PR for this, or you need more input from others?

This issue is a big dealbreaker for using an SPA behind bunkerweb IMO. I'm having an absolute nightmare trying to register service workers when not accessing from the root domain, meaning my PWA is broken currently 😢

Note

The change would mean that the server attempts to load index.html as a fallback, prior to returning a 404.
It guess this could cause issues on entirely static sites? As loading domain.com/does/not/exist would return to domain.com.

It might be best to have multisite env vars as a flag:

• {DOMAIN}_SERVE_FILES_PWA: true
  • try_files $uri $uri/ /index.html =404
• {DOMAIN}_SERVE_FILES_PWA: false
  • try_files $uri $uri/ =404