Reverse Proxy Setup

Setting Up with a Reverse Proxy

Running Recommendarr behind a reverse proxy (like Nginx, Traefik, Caddy, Apache, etc.) is recommended for exposing it securely, especially over the internet with HTTPS.

Key Considerations

• Public URL: The PUBLIC_URL environment variable must be set to the exact URL users will use to access Recommendarr (e.g., https://recommendarr.yourdomain.com). This is critical for generating correct links and for OAuth callbacks.
• Base URL: If running Recommendarr under a sub-path (e.g., https://yourdomain.com/recommendarr), set the BASE_URL environment variable accordingly (e.g., /recommendarr). The default is /.
• Secure Cookies: If your reverse proxy handles HTTPS termination (i.e., users connect via HTTPS, but the proxy connects to Recommendarr via HTTP), you must set the FORCE_SECURE_COOKIES=true environment variable. This ensures authentication cookies are flagged as secure. See Troubleshooting for related errors.
• Headers: Ensure your reverse proxy forwards essential headers like Host, X-Real-IP, X-Forwarded-For, and especially X-Forwarded-Proto (set to https if terminating SSL).

Docker Setup

When using Docker behind a reverse proxy:

1. Build Custom Image (Optional but Recommended for Sub-paths): If using a BASE_URL other than /, build a custom image:

   # Build with your public URL and base path
   docker build -t recommendarr:custom \
     --build-arg PUBLIC_URL=https://recommendarr.yourdomain.com \
     --build-arg BASE_URL=/your-base-path \
     .

2. Run Container:

   # Run with reverse proxy configuration
   # Use recommendarr:custom if you built a custom image, otherwise use the standard image
   docker run -d \
     --name recommendarr \
     -p 127.0.0.1:3000:3000 `# Expose only to localhost if proxy is on the same host` \
     -e PUBLIC_URL=https://recommendarr.yourdomain.com `# Your full public URL` \
     -e BASE_URL=/ `# Or your custom base path` \
     -e FORCE_SECURE_COOKIES=true `# If using HTTPS` \
     -v recommendarr-data:/app/server/data \
     tannermiddleton/recommendarr:latest # Or recommendarr:custom

   Note: Binding the port to 127.0.0.1:3000 prevents direct access from outside the host machine, forcing traffic through the proxy.

3. Docker Compose:

   services:
     recommendarr:
       # Use 'image: tannermiddleton/recommendarr:latest' if not building custom
       build:
         context: .
         args:
           - PUBLIC_URL=https://recommendarr.yourdomain.com
           - BASE_URL=/ # Or your custom base path
       ports:
         # Expose only to localhost if proxy is on the same host
         - "127.0.0.1:3000:3000"
       environment:
         - NODE_ENV=production
         - PORT=3000
         - PUBLIC_URL=https://recommendarr.yourdomain.com
         - BASE_URL=/ # Or your custom base path
         # Enable secure cookies when behind HTTPS reverse proxy
         - FORCE_SECURE_COOKIES=true
       volumes:
         - recommendarr-data:/app/server/data
       restart: unless-stopped
   
   volumes:
     recommendarr-data:
   
   # Add network configuration if your proxy is in a different Docker network
   # networks:
   #   proxy-network:
   #     external: true