99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 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 | `Merchant Operator 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 merchant-operator-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:
|
|
merchant-operator-app:
|
|
environment:
|
|
- CLIENT_BASE_PATH=/app
|
|
- CLIENT_API_URL=https://api.example.com
|
|
- CLIENT_APP_NAME=Merchant Operator 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 Merchant-operator-app`
|