---
tags: [tech-patterns, auto-generated]
source: video-accessibility
created: 2026-04-30
---

# Apache SPA + API Proxy Configuration via Includes

## When to use
When deploying a Single Page Application (SPA) alongside a backend API on the same Apache server, but the SPA's API calls return 404 errors despite the backend being healthy. This pattern ensures Apache correctly routes SPA assets and proxies API requests.

## Prerequisites
- Apache 2.4+ with `mod_proxy` and `mod_proxy_http` enabled
- SPA files deployed to a directory (e.g., `/var/www/html/video-accessibility/`)
- Backend API running on localhost (e.g., port 8012)
- Virtual host configuration file in `/etc/apache2/sites-available/`

## Steps
1. Create the virtual host configuration in `/etc/apache2/sites-available/your-domain.conf` with ProxyPassMatch and Alias directives:
   ```apache
   <VirtualHost *:443>
       ServerName optical-dev.oliver.solutions
       
       # Proxy API requests to backend
       ProxyPassMatch ^/video-accessibility/api/(.*)$ http://localhost:8012/api/$1
       ProxyPassReverse /video-accessibility/api/ http://localhost:8012/api/
       
       # Serve SPA static files
       Alias /video-accessibility/ /var/www/html/video-accessibility/
       <Directory /var/www/html/video-accessibility/>
           Require all granted
           FallbackResource /video-accessibility/index.html
       </Directory>
   </VirtualHost>
   ```

2. Create an Include file (e.g., `/opt/video-accessibility/apache-includes/video-accessibility.conf`) with the same content for automated deployment

3. **Critical:** Link the configuration to `sites-enabled/`:
   ```bash
   sudo a2ensite your-domain.conf
   # or manually:
   sudo ln -s /etc/apache2/sites-available/your-domain.conf /etc/apache2/sites-enabled/your-domain.conf
   ```

4. Verify the Include is in the main vhost file:
   ```bash
   grep -A2 "video-accessibility" /etc/apache2/sites-available/optical-dev.oliver.solutions.conf
   ```

5. Test and reload Apache:
   ```bash
   sudo apache2ctl configtest
   sudo systemctl reload apache2
   ```

6. Verify backend health:
   ```bash
   curl -s http://localhost:8012/health
   ```

## Key Configuration
- **ProxyPassMatch regex must match SPA route prefix:** If SPA is at `/video-accessibility/`, API proxy must be `/video-accessibility/api/(...)`
- **FallbackResource is essential:** Routes all non-file requests to `index.html` so SPA client-side routing works
- **Include path must be in `sites-enabled/`**, not just `sites-available/` — Apache only reads enabled configs

## Gotchas
- Configuration files in `sites-available/` are NOT automatically loaded — they must be symlinked to `sites-enabled/` or included via `a2ensite`
- Deployment scripts should write Include directives to `sites-enabled/` path, not `sites-available/` (common bug in automation)
- If SPA loads but API calls 404, check `grep -n "video-accessibility" /etc/apache2/sites-enabled/` — if empty, the config was never enabled
- ProxyPassMatch order matters: more specific patterns should come before general ones
- Browser DevTools may cache SPA bundle — test with `curl` to backend API endpoint directly

## Source
Project: video-accessibility
