Path-Agnostic SPA Deployment Guide

This project is configured for path-agnostic deployment, allowing the application to be served from any base path without requiring a rebuild.

Configuration Files

docker-compose.yml: Main Docker Compose configuration with variables
docker-compose.override.yml.template: Template for environment-specific overrides
.env.template: Template for environment variables

Setup Instructions

Copy the template files to create your environment-specific configurations:

cp docker-compose.override.yml.template docker-compose.override.yml
cp .env.template .env

Edit the .env and/or docker-compose.override.yml files to set your environment-specific values:

Key Configuration Variables

Variable	Description	Default
CLIENT_BASE_PATH	Base path where the app will be served	`/`
CLIENT_API_URL	Base URL for backend API	`https://localhost:7205`
CLIENT_APP_NAME	Application name displayed in UI	`App`
CLIENT_DEBUG	Enable debug mode	`false`
ENABLE_TLS	Whether to enable TLS	`false`
TRAEFIK_ENTRYPOINT	Traefik entrypoint to use	`web`

Deployment

Local Development

For local development, you can use the default values or customize as needed:

docker-compose up -d

Production Deployment

For production, build the image and then deploy with environment variables:

# Build the image
docker build -t spa-app-app .

# Deploy with environment variables
docker-compose up -d

Environment variables are passed at runtime through docker-compose.yml or docker-compose.override.yml:

services:
  spa-app-app:
    environment:
      - CLIENT_BASE_PATH=/app
      - CLIENT_API_URL=https://api.example.com
      - CLIENT_APP_NAME=App
      - CLIENT_DEBUG=false
      - CLIENT_OIDC_AUTHORITY=https://auth.example.com
      - CLIENT_OIDC_CLIENT_ID=your-client-id

Variable names are converted from CLIENT_SNAKE_CASE to camelCase automatically.

Using Base Path in the Application

The application is configured to use the base path from the configuration. In your React components, use the utility functions from src/utils/config.js:

import { getAssetPath } from '../utils/config';

function MyComponent() {
  return <img src={getAssetPath('/images/logo.png')} alt="Logo" />;
}

How It Works

During development, Vite makes environment variables prefixed with CLIENT_ available via import.meta.env.
The application is built without any environment-specific configuration.
At container startup, the docker-entrypoint.sh script extracts all environment variables starting with CLIENT_ and writes them to a .env file in the app's directory.
The Vite application reads these variables at runtime.
The Nginx configuration is set up to handle SPA routing and asset caching.
The getBasePath() and getAssetPath() utility functions provide the correct paths in your application code.

Troubleshooting

If assets are not loading, check that you're using the getAssetPath() function for all asset URLs.
If routing is not working, ensure that your router is configured to use the base path.
Check Nginx logs for any errors: docker-compose logs spa-app-app

3.6 KiB Raw Blame History