Reverse Proxy Configuration

When deploying Palmr. behind a reverse proxy (like Traefik, Nginx, or Cloudflare), you need to configure secure cookie settings to ensure proper authentication. This guide covers the SECURE_SITE environment variable and related proxy configurations.

Overview

Reverse proxies terminate SSL/TLS connections and forward requests to Palmr., which can cause authentication issues if cookies aren't configured properly for HTTPS environments. The SECURE_SITE environment variable controls cookie security settings to handle these scenarios.

The SECURE_SITE Environment Variable

The SECURE_SITE variable configures how Palmr. handles authentication cookies based on your deployment environment:

Configuration Options

When to Use SECURE_SITE=true

Set SECURE_SITE=true in the following scenarios:

• ✅ Reverse Proxy with HTTPS: Traefik, Nginx, HAProxy with SSL termination
• ✅ Cloud Providers: Cloudflare, AWS ALB, Azure Application Gateway
• ✅ CDN with HTTPS: Any CDN that terminates SSL
• ✅ Production Deployments: When users access via HTTPS

When to Use SECURE_SITE=false

Keep SECURE_SITE=false (default) for:

• ✅ Local Development: Running on http://localhost
• ✅ Direct HTTP Access: No reverse proxy involved
• ✅ Testing Environments: When using HTTP
• ✅ HTTP Reverse Proxy: Nginx, Apache, etc. without SSL termination

HTTP Reverse Proxy Setup

Docker Compose for HTTP Nginx:

environment:
  - SECURE_SITE=false # HTTP = false

⚠️ HTTP Security: Remember that HTTP transmits data in plain text. Consider using HTTPS in production environments.

Troubleshooting Authentication Issues

Common Symptoms

If you experience authentication issues behind a reverse proxy:

• ❌ Login appears successful but redirects to login page
• ❌ "No Authorization was found in request.cookies" errors
• ❌ API requests return 401 Unauthorized
• ❌ User registration fails silently

Diagnostic Steps

1. Check Browser Developer Tools:

   • Look for cookies in Application/Storage tab
   • Verify cookie has Secure flag when using HTTPS
   • Check if SameSite attribute is appropriate

2. Verify Environment Variables:

   docker exec -it palmr env | grep SECURE_SITE

3. Test Cookie Settings:

   • With SECURE_SITE=false: Should work on HTTP
   • With SECURE_SITE=true: Should work on HTTPS

Common Fixes

Problem: Authentication fails with reverse proxy

Solution: Set SECURE_SITE=true and ensure proper headers:

environment:
  - SECURE_SITE=true

Problem: Mixed content errors

Solution: Ensure proxy passes correct headers:

# Traefik
- "traefik.http.middlewares.palmr-headers.headers.customrequestheaders.X-Forwarded-Proto=https"
 
# Nginx
proxy_set_header X-Forwarded-Proto $scheme;

Problem: Authentication fails with HTTP reverse proxy

Solution: Use SECURE_SITE=false and ensure proper cookie headers:

environment:
  - SECURE_SITE=false # For HTTP proxy

# Nginx - Add these headers for cookie handling
proxy_set_header Cookie $http_cookie;
proxy_pass_header Set-Cookie;

Problem: SQLite "readonly database" error with bind mounts

Solution: Configure proper UID/GID permissions:

environment:
  - PALMR_UID=1000 # Your host UID (check with: id)
  - PALMR_GID=1000 # Your host GID
  - DISABLE_FILESYSTEM_ENCRYPTION=true # Set to false to enable file encryption
  # - ENCRYPTION_KEY=your-key-here # Required only if encryption is enabled

💡 Note: Check your host UID/GID with id command and use those values. See UID/GID Configuration for detailed setup.

Security Considerations

⚠️ Important: Always use HTTPS in production environments. The SECURE_SITE=true setting ensures cookies are only sent over encrypted connections.

Advanced Configuration

Multiple Domains

If serving Palmr. on multiple domains, ensure consistent cookie settings:

environment:
  - SECURE_SITE=true # Use for all HTTPS domains

Development vs Production

Use environment-specific configurations:

Development (HTTP):

environment:
  - SECURE_SITE=false

Production (HTTPS):

environment:
  - SECURE_SITE=true

Health Checks

Add health checks to ensure proper proxy configuration:

services:
  palmr:
    # ... other config
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5487/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Need Help?

If you're still experiencing issues after following this guide:

1. Check the Logs: docker logs palmr
2. Verify Headers: Use browser dev tools or curl -I
3. Test Direct Access: Try accessing Palmr. directly (bypassing proxy)
4. Open an Issue: Report bugs on GitHub

💡 Pro Tip: When reporting issues, include your reverse proxy configuration and any relevant error messages from both Palmr. and your proxy logs.