Nginx Setup

Nginx Setup for FileRise

This guide covers configuring Nginx to run FileRise either:

• as a standalone web server with PHP-FPM, or
• as a reverse proxy in front of another web server.

The examples below assume PHP-FPM and FileRise installed under a standard setup.

FileRise is reverse-proxy aware and supports running under a subpath (e.g. /files) when configured correctly.

---

Prerequisites

• Nginx installed
• PHP-FPM installed (PHP 8.3+ recommended)
• FileRise installed (e.g. /var/www/FileRise, with the public/ directory as the web root)

---

Basic Nginx Configuration (root install)

This example serves FileRise at the site root (https://example.com/).

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/FileRise/public;
    index index.php index.html;

    # 1) Internal auth endpoint for auth_request
    location = /api/auth/auth.php {
        internal;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/api/auth/auth.php;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    }

    # 2) Protect API docs
    location ~ ^/(api\.html|openapi\.json)$ {
        auth_request /api/auth/auth.php;
        error_page 401 = @login;
        try_files $uri =404;
    }

    # 3) Redirect to login on auth failure
    location @login {
        return 302 /login?redirect=$request_uri;
    }

    # 4) Main application routing
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # 5) PHP handling
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
    }

    # 6) Deny sensitive paths
    location ~* /(users|metadata|\.git) {
        deny all;
    }

    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }

    # 7) Optional: cache static assets
    location ~* \.(jpg|jpeg|png|gif|css|js|ico|svg)$ {
        expires 30d;
        access_log off;
    }
}

---

Running FileRise under a subpath (e.g. /files)

FileRise supports running under a subpath without stripping the prefix when Nginx + PHP-FPM is serving the app directly (Nginx handles the subpath routing).

Note: For Traefik/Kubernetes, use StripPrefix + X-Forwarded-Prefix (see the Kubernetes wiki). Don’t apply the same “no strip” rule to Traefik.

Key rules (Nginx + PHP-FPM)

• ✅ Route or serve /files without rewriting it away in a way that breaks routing
• ✅ Ensure index.php is reached as /files/index.php for subpath requests
• ❌ Do NOT use proxy_pass .../ with a trailing slash when reverse proxying
• ❌ Do NOT use prefix stripping when proxying to a backend that expects /files (unless that backend is explicitly root-only)

---

Example: subpath install at /files

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/FileRise/public;
    index index.php index.html;

    # Redirect bare /files -> /files/
    location = /files {
        return 301 /files/;
    }

    location /files/ {
        try_files $uri $uri/ /files/index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
    }

    location ~* /(users|metadata|\.git) {
        deny all;
    }
}

Recommended environment variable

When running under a subpath, explicitly define the public URL:

FR_PUBLISHED_URL=https://yourdomain.com/files

This ensures correct generation of:

• share links
• portal URLs
• redirects
• PWA / manifest paths

---

Reverse proxy notes (Nginx in front of Apache / Docker)

If Nginx proxies to another FileRise container or Apache backend:

location /files/ {
    proxy_pass http://127.0.0.1:8080;   # no trailing slash
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

⚠️ If you are proxying a root-only backend, you may need to strip the prefix at Nginx and provide X-Forwarded-Prefix (similar to the Traefik pattern).

---

Encryption at rest (Nginx considerations)

If folder-level encryption at rest is enabled:

• Encrypted files are decrypted on download
• HTTP range requests are intentionally disabled
• Static caching of encrypted file downloads is not recommended

This is expected behavior.

---

Common pitfalls

• ❌ Using alias instead of root
• ❌ Using proxy_pass .../ (trailing slash)
• ❌ Stripping/rewriting prefixes without also handling base-path generation
• ❌ Forgetting to set FR_PUBLISHED_URL when using a subpath

---

Notes

• FileRise assumes a single active instance.
• Nginx buffering and large uploads may require:

  client_max_body_size 0;

• PHP-FPM timeouts may need adjustment for large uploads or ZIP operations.