docs: enhance SECURE_SITE documentation across all files

- Update docker-compose files with clearer SECURE_SITE description
- Add Safari cross-site tracking compatibility note to all SECURE_SITE comments
- Improve quick-start.mdx environment variable table description
- Update all Docker Compose and Docker run examples with enhanced comments

Co-authored-by: danielalves96 <62755605+danielalves96@users.noreply.github.com>

apps/docs/content/docs/3.2-beta/quick-start.mdx

@@ -67,7 +67,7 @@ Choose your storage method based on your needs:
           # - ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
           # - PALMR_UID=1000 # UID for the container processes (default is 1000)
           # - PALMR_GID=1000 # GID for the container processes (default is 1000)
-          # - SECURE_SITE=false # Set to true if you are using a reverse proxy
+          # - SECURE_SITE=false # Set to true for HTTPS/reverse proxy (enables cross-origin cookies for Safari)
           # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
           # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (optional, defaults to 3600 seconds / 1 hour)
           # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum simultaneous downloads (auto-scales if not set)
@@ -122,7 +122,7 @@ Choose your storage method based on your needs:
           # - ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
           # - PALMR_UID=1000 # UID for the container processes (default is 1000)
           # - PALMR_GID=1000 # GID for the container processes (default is 1000)
-          # - SECURE_SITE=false # Set to true if you are using a reverse proxy
+          # - SECURE_SITE=false # Set to true for HTTPS/reverse proxy (enables cross-origin cookies for Safari)
           # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
           # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (optional, defaults to 3600 seconds / 1 hour)
           # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum simultaneous downloads (auto-scales if not set)
@@ -168,7 +168,7 @@ Customize Palmr's behavior with these environment variables:
 | `DISABLE_FILESYSTEM_ENCRYPTION`    | `true`         | Disable file encryption for better performance (set to `false` to enable encryption)                                                  |
 | `PRESIGNED_URL_EXPIRATION`         | `3600`         | Duration in seconds for presigned URL expiration (applies to both filesystem and S3 storage)                                          |
 | `CUSTOM_PATH`                      | -              | Custom base path for disk space detection in manual installations with symlinks                                                       |
-| `SECURE_SITE`                      | `false`        | Enable secure cookies for HTTPS/reverse proxy deployments                                                                             |
+| `SECURE_SITE`                      | `false`        | Enable secure cookies for HTTPS/reverse proxy deployments. Required for Safari cross-site tracking compatibility when frontend and backend are on different domains |
 | `DEFAULT_LANGUAGE`                 | `en-US`        | Default application language ([see available languages](/docs/3.2-beta/available-languages))                                          |
 | `PALMR_UID`                        | `1000`         | User ID for container processes (helps with file permissions)                                                                         |
 | `PALMR_GID`                        | `1000`         | Group ID for container processes (helps with file permissions)                                                                        |
@@ -238,7 +238,7 @@ Prefer Docker commands over Compose? Here are the equivalent commands:
       # -e ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
       # -e PALMR_UID=1000 # UID for the container processes (default is 1000)
       # -e PALMR_GID=1000 # GID for the container processes (default is 1000)
-      # -e SECURE_SITE=false # Set to true if you are using a reverse proxy
+      # -e SECURE_SITE=false # Set to true for HTTPS/reverse proxy (enables cross-origin cookies for Safari)
       # -e DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
       -p 5487:5487 \
       -p 3333:3333 \
@@ -265,7 +265,7 @@ Prefer Docker commands over Compose? Here are the equivalent commands:
       # -e ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
       # -e PALMR_UID=1000 # UID for the container processes (default is 1000)
       # -e PALMR_GID=1000 # GID for the container processes (default is 1000)
-      # -e SECURE_SITE=false # Set to true if you are using a reverse proxy
+      # -e SECURE_SITE=false # Set to true for HTTPS/reverse proxy (enables cross-origin cookies for Safari)
       # -e DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
       -p 5487:5487 \
       -p 3333:3333 \

apps/docs/content/docs/3.2-beta/reverse-proxy-configuration.mdx

@@ -17,8 +17,10 @@ The `SECURE_SITE` variable configures how Palmr. handles authentication cookies
 
 | Value   | Cookie Settings                       | Use Case                            |
 | ------- | ------------------------------------- | ----------------------------------- |
-| `true`  | `secure: true`, `sameSite: "lax"`     | HTTPS/Production with reverse proxy |
+| `true`  | `secure: true`, `sameSite: "none"`    | HTTPS/Production with reverse proxy |
-| `false` | `secure: false`, `sameSite: "strict"` | HTTP/Development (default)          |
+| `false` | `secure: false`, `sameSite: "lax"`    | HTTP/Development (default)          |
+
+> **🔒 Safari Cross-Site Tracking**: When `SECURE_SITE=true`, cookies use `sameSite: "none"` to support Safari's Cross-Site Tracking prevention when the frontend and backend are on different domains/subdomains.
 
 ### When to Use SECURE_SITE=true
 

apps/docs/content/docs/3.2-beta/troubleshooting.mdx

@@ -194,6 +194,45 @@ docker exec palmr stat /app/server/uploads/your-file.txt
 
 See our [OIDC Configuration Guide](/docs/3.0-beta/oidc-authentication) for detailed setup.
 
+### Safari: Images Don't Render and Downloads Are Corrupted
+
+**Symptoms:**
+- Images show as broken/loading icon in Safari
+- Downloaded files are corrupted
+- Works fine on localhost but fails on production domain
+- Only affects Safari with "Cross-Site Tracking Prevention" enabled
+
+**Cause:**
+Safari blocks cookies when the frontend and backend are on different domains/subdomains due to Cross-Site Tracking prevention.
+
+**Solution:**
+
+1. **Enable secure cookies in your server `.env`:**
+
+   ```bash
+   SECURE_SITE=true
+   ```
+
+2. **Ensure HTTPS is enabled:**
+   
+   The `sameSite: none` cookie attribute requires HTTPS. Make sure your reverse proxy (nginx, Traefik, etc.) is configured with SSL/TLS.
+
+3. **Restart the server:**
+
+   ```bash
+   docker-compose down && docker-compose up -d
+   ```
+
+**Verification:**
+
+- Check browser dev tools → Application → Cookies
+- Look for the `token` cookie with:
+  - ✅ `Secure` flag enabled
+  - ✅ `SameSite=None`
+  - ✅ `HttpOnly` flag enabled
+
+> **💡 Note**: This requires HTTPS. If using HTTP in development, keep `SECURE_SITE=false`.
+
 ---
 
 ## 🌐 Network Issues

apps/server/.env.example

@@ -4,6 +4,9 @@ DISABLE_FILESYSTEM_ENCRYPTION=true
 # ENCRYPTION_KEY=change-this-key-in-production-min-32-chars # Required only if encryption is enabled (DISABLE_FILESYSTEM_ENCRYPTION=false)
 DATABASE_URL="file:./palmr.db"
 
+# SECURITY SETTINGS
+# SECURE_SITE=true # Set to true when using HTTPS in production. This enables secure cookies with SameSite=none, allowing cross-origin requests (required when frontend and backend are on different domains/subdomains)
+
 # FOR USE WITH S3 COMPATIBLE STORAGE
 # ENABLE_S3=true 
 # S3_ENDPOINT=

apps/server/src/modules/auth-providers/controller.ts

@@ -124,7 +124,7 @@ export class AuthProvidersController {
     reply.setCookie("token", token, {
       httpOnly: true,
       secure: isSecure,
-      sameSite: "lax",
+      sameSite: isSecure ? "none" : "lax",
       maxAge: COOKIE_MAX_AGE,
       path: "/",
     });

apps/server/src/modules/auth/controller.ts

@@ -44,7 +44,7 @@ export class AuthController {
         httpOnly: true,
         path: "/",
         secure: env.SECURE_SITE === "true" ? true : false,
-        sameSite: env.SECURE_SITE === "true" ? "lax" : "strict",
+        sameSite: env.SECURE_SITE === "true" ? "none" : "lax",
       });
 
       return reply.send({ user });
@@ -74,7 +74,7 @@ export class AuthController {
         httpOnly: true,
         path: "/",
         secure: env.SECURE_SITE === "true" ? true : false,
-        sameSite: env.SECURE_SITE === "true" ? "lax" : "strict",
+        sameSite: env.SECURE_SITE === "true" ? "none" : "lax",
       });
 
       return reply.send({ user });

docker-compose-bind-mount-example.yaml

@@ -12,7 +12,7 @@ services:
       # - PALMR_GID=1000 # GID for the container processes (OPTIONAL - default is 1000) | See our UID/GID Documentation for more information
       # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US) | See the docs for see all supported languages
       # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (OPTIONAL - default is 3600 seconds / 1 hour)
-      # - SECURE_SITE=true # Set to true if you are using a reverse proxy (OPTIONAL - default is false)
+      # - SECURE_SITE=true # Set to true for HTTPS/reverse proxy deployments. Enables cross-origin cookies for Safari compatibility (OPTIONAL - default is false)
 
       # Download Memory Management Configuration (OPTIONAL - See documentation for details)
       # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum number of simultaneous downloads (OPTIONAL - auto-scales based on system memory if not set)

docker-compose-minio.yaml

@@ -17,7 +17,7 @@ services:
       # - PALMR_GID=1000 # GID for the container processes (OPTIONAL - default is 1000) | See our UID/GID Documentation for more information
       # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US) | See the docs for see all supported languages
       # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (OPTIONAL - default is 3600 seconds / 1 hour)
-      # - SECURE_SITE=true # Set to true if you are using a reverse proxy (OPTIONAL - default is false)
+      # - SECURE_SITE=true # Set to true for HTTPS/reverse proxy deployments. Enables cross-origin cookies for Safari compatibility (OPTIONAL - default is false)
 
       # Download Memory Management Configuration (OPTIONAL - See documentation for details)
       # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum number of simultaneous downloads (OPTIONAL - auto-scales based on system memory if not set)

docker-compose-s3.yaml

@@ -17,7 +17,7 @@ services:
       # - PALMR_GID=1000 # GID for the container processes (OPTIONAL - default is 1000) | See our UID/GID Documentation for more information
       # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US) | See the docs for see all supported languages
       # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (OPTIONAL - default is 3600 seconds / 1 hour)
-      # - SECURE_SITE=true # Set to true if you are using a reverse proxy (OPTIONAL - default is false)
+      # - SECURE_SITE=true # Set to true for HTTPS/reverse proxy deployments. Enables cross-origin cookies for Safari compatibility (OPTIONAL - default is false)
 
       # Download Memory Management Configuration (OPTIONAL - See documentation for details)
       # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum number of simultaneous downloads (OPTIONAL - auto-scales based on system memory if not set)

docker-compose.yaml

@@ -12,7 +12,7 @@ services:
       # - PALMR_GID=1000 # GID for the container processes (OPTIONAL - default is 1000) | See our UID/GID Documentation for more information
       # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US) | See the docs to see all supported languages
       # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (OPTIONAL - default is 3600 seconds / 1 hour)
-      # - SECURE_SITE=true # Set to true if you are using a reverse proxy (OPTIONAL - default is false)
+      # - SECURE_SITE=true # Set to true for HTTPS/reverse proxy deployments. Enables cross-origin cookies for Safari compatibility (OPTIONAL - default is false)
 
       # Download Memory Management Configuration (OPTIONAL - See documentation for details)
       # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum number of simultaneous downloads (OPTIONAL - auto-scales based on system memory if not set)