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

Create the virtual host configuration in /etc/apache2/sites-available/your-domain.conf with ProxyPassMatch and Alias directives:

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

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

Critical: Link the configuration to sites-enabled/:

sudo a2ensite your-domain.conf
# or manually:
sudo ln -s /etc/apache2/sites-available/your-domain.conf /etc/apache2/sites-enabled/your-domain.conf

Verify the Include is in the main vhost file:

grep -A2 "video-accessibility" /etc/apache2/sites-available/optical-dev.oliver.solutions.conf

Test and reload Apache:

sudo apache2ctl configtest
sudo systemctl reload apache2

Verify backend health:
```
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

3.2 KiB Raw Permalink Blame History