Setting up Caddy as reverse proxy for BookStack with Reality on Ubuntu VPS

BookStack with Caddy as Reverse Proxy in Docker Container and Reality Stealself on Ubuntu

BookStack with Caddy as reverse proxy in Docker container and Reality Stealself on Ubuntu usually requires proper port configuration and transparent proxy setup. The main issue is often related to the Caddyfile configuration, where you need to specify the correct Docker container ports and use transparent mode for proper header forwarding.

Contents:

• Basic Setup Issues
• Caddyfile Configuration
• Reality Stealself Setup
• Docker Configuration for BookStack
• Troubleshooting

Basic Setup Issues

Common errors when setting up Caddy as reverse proxy for BookStack include:

• Incorrect ports: BookStack in Docker usually runs on port 8080, not 80
• Missing transparent mode: you need to add transparent to the Caddyfile
• Incorrect APP_URL configuration: BookStack should specify the full URL via HTTPS
• Reality port conflicts: Reality may conflict with ports used by Caddy

According to the BookStack installation documentation for Ubuntu, when installed via Docker container, BookStack is available by default on port 8080 of the host.

Caddyfile Configuration

For BookStack with Reality Stealself, the optimal Caddyfile configuration looks like this:

wiki.example.com {
    reverse_proxy localhost:8080 {
        transparent
        header_up Host {http.reverse_proxy.upstream.hostport}
        header_up X-Forwarded-For {http.request.remote_host}
        header_up X-Forwarded-Proto {http.request.scheme}
    }
    
    # For Reality if used
    tls internal
}

Key points:

• Use localhost:8080 as the target address if BookStack is running in Docker on the same host
• The transparent flag is critically important
• Headers should be forwarded for proper scheme and host determination

As explained in a Reddit discussion, “the BookStack container should be accessible on the host IP at port 8080, not 80”.

Reality Stealself Setup

Reality Stealself requires special configuration to work with Caddy:

# Reality configuration
{
    experimental_http3
}

reality.example.com {
    reverse_proxy localhost:8080 {
        transparent
        tls reality {
            local_port 8443
            destination_port 443
        }
    }
}

Important parameters:

• local_port - the port that Reality listens on
• destination_port - the port of the target service
• For SSL certificates, use tls internal or configure automatic issuance

The XTLS forwardproxy-reality project provides a plugin for Caddy with anti-probing and proxy hiding features.

Docker Configuration for BookStack

Your docker-compose.yml for BookStack should look like this:

version: '3.8'
services:
  bookstack:
    image: solidnerd/bookstack
    container_name: bookstack
    ports:
      - "8080:80"
    environment:
      - APP_URL=https://wiki.example.com
      - APP_KEY=base64:your_secret_key
      - DB_HOST=bookstack-db
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=your_password
    volumes:
      - bookstackuploads:/var/www/bookstack/public/uploads
      - bookstackstorage:/var/www/bookstack/storage

volumes:
  bookstackuploads:
  bookstackstorage:

Critical points:

• Port 8080 on the host corresponds to port 80 inside the container
• APP_URL should match the domain used in the Caddyfile
• Create a unique APP_KEY using php artisan key:generate

Troubleshooting

If the setup doesn’t work, check the following points:

Checking BookStack Availability

1. Direct access to BookStack:

curl http://localhost:8080

2. Check Docker logs:

docker logs bookstack

Port Conflicts

Make sure there are no port conflicts:

netstat -tulpn | grep :8080
netstat -tulpn | grep :443

Testing Caddy

Check the Caddy configuration:

caddy adapt --config /etc/caddy/Caddyfile

And restart Caddy:

systemctl restart caddy

Working Configuration Example

Based on examples from real projects, a complete configuration might look like this:

{
    auto_https off
}

# Main domain
wiki.example.com {
    reverse_proxy bookstack:80 {
        transparent
    }
    tls internal
}

# Reality configuration
reality.wiki.example.com {
    reverse_proxy localhost:8080 {
        transparent
        tls reality {
            local_port 443
            destination_port 443
        }
    }
}

Sources

1. BookStack GitHub Issue #4037 - Cannot access bookstack behind caddy reverse proxy
2. BookStack GitHub Issue #801 - Bookstack behind Caddy Reverse Proxy not working
3. Reddit r/selfhosted - Caddyfile for Bookstack to use SSL
4. Reddit r/selfhosted - Anyone have Bookstack working with Caddy Server?
5. Carlos Aguni Blog - Using Caddy as Reverse Proxy
6. XTLS forwardproxy-reality GitHub - Forward proxy plugin for Caddy
7. BookStack Official Documentation - Ubuntu Installation

Conclusion

For successful setup of Caddy as reverse proxy for BookStack with Reality Stealself on Ubuntu VPS:

1. Ensure BookStack is accessible on port 8080 of the host
2. Use the transparent flag in the Caddyfile for proper header forwarding
3. Configure the correct APP_URL in BookStack to match the domain in Caddy
4. For Reality, check the port and SSL configuration
5. If problems persist, check Docker logs and service availability directly

If the issue remains after all configurations, try temporarily disabling Reality to check basic reverse proxy functionality, then gradually add Reality back while tracking each configuration step.