# 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

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

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

2. 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:

```bash
docker-compose up -d
```

### Production Deployment

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

```bash
# 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:

```yaml
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
```

<!-- Removed client-side env vars section; see docs/client-env-vars.md for details -->

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`:

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

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

## How It Works

1. During development, Vite makes environment variables prefixed with `CLIENT_` available via `import.meta.env`.
2. The application is built without any environment-specific configuration.
3. 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.
4. The Vite application reads these variables at runtime.
5. The Nginx configuration is set up to handle SPA routing and asset caching.
6. 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`