Reverse Proxy

For self-hosted infrastructure or platforms not covered by other guides, configure a reverse proxy to route /blog requests to Waldium. This guide covers nginx configuration, but the principles apply to Apache, Caddy, and other proxy servers.

Custom reverse proxy configurations are recommended for teams with infrastructure experience. Misconfigurations can affect both your blog and main site.

Routing Configuration

Your proxy should route these paths to Waldium with the specified caching behavior:

Path	Destination	Caching
`/.well-known/acme-challenge/*`	`[SUBDOMAIN].waldium.app`	Disabled
`/.well-known/vercel/*`	`[SUBDOMAIN].waldium.app`	Disabled
`/waldium-assets/_next/static/*`	`[SUBDOMAIN].waldium.app`	Enabled
`/_waldium/*`	`[SUBDOMAIN].waldium.app`	Disabled
`/blog/*`	`[SUBDOMAIN].waldium.app`	Disabled
`/blog`	`[SUBDOMAIN].waldium.app`	Disabled

Required Headers

Configure your proxy to forward these headers:

Header	Purpose
`Origin`	Set to `[SUBDOMAIN].waldium.app`
`X-Forwarded-For`	Preserves client IP
`X-Forwarded-Proto`	Preserves original protocol (HTTP/HTTPS)
`X-Real-IP`	Forwards the real client IP
`User-Agent`	Forwards the user agent string

Do not forward the Host header. This must be set to the Waldium subdomain, not your domain.

Nginx Configuration

Here's a complete nginx configuration for subpath hosting. Replace [SUBDOMAIN] with your Waldium subdomain and update paths as needed.

server {
    listen 80;
    server_name yoursite.com;

    # SSL certificate verification
    location ~ ^/\.well-known/acme-challenge/ {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Domain verification paths
    location ~ ^/\.well-known/vercel/ {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Static assets with caching
    location ~ ^/waldium-assets/_next/static/ {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "public, max-age=86400";
    }

    # Waldium internal paths
    location ~ ^/_waldium/ {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Blog root path
    location = /blog {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # All blog subpaths
    location /blog/ {
        proxy_pass https://[SUBDOMAIN].waldium.app;
        proxy_set_header Origin [SUBDOMAIN].waldium.app;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;
        
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Your main site (adjust as needed)
    location / {
        # Your existing configuration for the main site
        root /var/www/html;
        index index.html;
    }
}

Apache Configuration

For Apache with mod_proxy enabled:

<VirtualHost *:80>
    ServerName yoursite.com

    # Enable proxy modules
    ProxyPreserveHost Off
    ProxyPass /.well-known/acme-challenge/ https://[SUBDOMAIN].waldium.app/.well-known/acme-challenge/
    ProxyPassReverse /.well-known/acme-challenge/ https://[SUBDOMAIN].waldium.app/.well-known/acme-challenge/

    ProxyPass /blog https://[SUBDOMAIN].waldium.app/blog
    ProxyPassReverse /blog https://[SUBDOMAIN].waldium.app/blog

    ProxyPass /waldium-assets/ https://[SUBDOMAIN].waldium.app/waldium-assets/
    ProxyPassReverse /waldium-assets/ https://[SUBDOMAIN].waldium.app/waldium-assets/

    ProxyPass /_waldium/ https://[SUBDOMAIN].waldium.app/_waldium/
    ProxyPassReverse /_waldium/ https://[SUBDOMAIN].waldium.app/_waldium/

    # Your main site configuration
    DocumentRoot /var/www/html
</VirtualHost>

Caddy Configuration

For Caddy server:

yoursite.com {
    # Blog paths
    handle /blog* {
        reverse_proxy [SUBDOMAIN].waldium.app {
            header_up Origin [SUBDOMAIN].waldium.app
            header_up X-Forwarded-Proto https
        }
    }

    # Waldium assets and internal paths
    handle /waldium-assets/* {
        reverse_proxy [SUBDOMAIN].waldium.app
    }

    handle /_waldium/* {
        reverse_proxy [SUBDOMAIN].waldium.app
    }

    # Verification paths
    handle /.well-known/* {
        reverse_proxy [SUBDOMAIN].waldium.app
    }

    # Main site
    handle {
        root * /var/www/html
        file_server
    }
}

Troubleshooting

404 Errors

Symptoms: Blog pages return 404 after configuration.

Solutions:

Verify the Waldium subdomain is correct
Check that proxy rules match the URL patterns exactly
Ensure the proxy is actually reaching Waldium (test with curl)

Features Not Working

Symptoms: Blog loads but interactive features fail, or content looks broken.

Causes:

Host header being forwarded incorrectly
Missing Origin header
/_waldium/ paths not proxied

Solutions:

Ensure Host is NOT forwarded from the client
Set Origin header to your Waldium subdomain
Add proxy rules for all required paths

Performance Issues

Symptoms: Pages load slowly or have layout shifts.

Causes: Incorrect caching configuration.

Solutions:

Enable caching only for /waldium-assets/_next/static/*
Keep other paths uncached to ensure fresh content
Monitor proxy logs for slow responses