Reverse proxy
A reverse proxy sits in front of Frameleaf and passes requests on to it. It’s the usual way to serve Frameleaf over HTTPS on your own domain, such as https://photos.example.com, and it can handle certificates, load balancing and access control for you.
If you’d rather not run one, Frameleaf Cloud remote access gives you HTTPS and a stable address without opening ports. See Remote access for all the options.
What every proxy needs
Section titled “What every proxy needs”- Forward all headers, and set
Host,X-Real-IP,X-Forwarded-ProtoandX-Forwarded-Forto the right values. - Allow large uploads. Videos can be many gigabytes.
- Long timeouts. Large uploads fail if the proxy gives up after a minute.
- WebSockets. The web app uses them for live updates.
- Serve Frameleaf at the root of a domain or subdomain. Frameleaf can’t be served on a sub-path such as
https://example.com/photos.
Frameleaf needs to see each visitor’s real address, because sign-in limits and “at home or away” decisions depend on it. A proxy on the same machine or on your home network is trusted already: Frameleaf accepts the forwarded address from any private or link-local address.
If your proxy connects from another kind of address, such as a Tailscale 100.64.0.0/10 address or a public one, tell Frameleaf to trust it. Set FRAMELEAF_TRUSTED_PROXIES to the proxy’s address or range, comma-separated if there are several:
- Manager: open Containers, choose Add a setting… on the Frameleaf server tab and search for proxy. It’s listed as Reverse proxies to trust.
- Docker Compose: add it to
.envand rundocker compose up -d.
Setting it replaces the default, so include every proxy you use. See Environment variables.
If your proxy also asks for extra headers or a client certificate, see Give the apps access through your proxy. Most setups don’t need this.
Finally, set Public server URL to your new address in Settings, then Frameleaf Cloud, then Remote access, so shared links and emails use it. It doesn’t need a Frameleaf Cloud link. If you use your own sign-in provider, add the new address to its redirect URIs.
Give the apps access through your proxy
Section titled “Give the apps access through your proxy”Skip this unless your proxy checks every visitor itself, for example with Cloudflare Access or with client certificates (mutual TLS). A plain HTTPS proxy needs nothing more. The apps can’t make these credentials, so you create them and give one to each person, who adds it in the app’s connection options: see iPhone and iPad and Android.
Headers, such as Cloudflare Access. In Cloudflare Zero Trust, create a service token under Access, then Service credentials, and add a policy with the Service Auth action to your Frameleaf application that allows it. Give the person the two values to enter as headers: CF-Access-Client-Id and CF-Access-Client-Secret. A browser sign-in policy alone doesn’t work for the apps, because background backup has no browser to sign in with. For another proxy, give them the header name and shared value it checks.
Client certificates. Issue each person a certificate from the authority your proxy trusts, and export it together with its private key as a .p12 file:
openssl pkcs12 -export -inkey alex.key -in alex.crt -certfile ca.crt -out alex.p12Send the file and its password separately, for example the file by email and the password by message. On iPhone and iPad it’s added in Frameleaf. On Android it’s installed in Android’s settings first, then chosen in Frameleaf.
Give each person, or each phone, its own token or certificate. Then you can revoke one, when a phone is lost or someone leaves, without cutting off everyone else. The apps show a plain message when a certificate is refused or a proxy turns them away.
Replace <public_url> with your domain and <backend_url> with the address of the Frameleaf server.
server { server_name <public_url>;
# allow large file uploads client_max_body_size 50000M;
# don't buffer uploads, to save memory on the proxy and keep uploads fast proxy_request_buffering off;
# a larger body buffer avoids limiting upload speed client_body_buffer_size 1024k;
# headers proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;
# websockets proxy_http_version 1.1; proxy_redirect off;
# timeouts proxy_read_timeout 600s; proxy_send_timeout 600s; send_timeout 600s;
location / { proxy_pass http://<backend_url>:2283; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }
# useful with the Let's Encrypt http-01 challenge # location ~ ^/\.well-known/(frameleaf|immich)$ { # proxy_pass http://<backend_url>:2283; # }}Caddy sets up HTTPS for you automatically:
photos.example.com { reverse_proxy http://<backend_url>:2283}Apache
Section titled “Apache”<VirtualHost *:80> ServerName <public_url> ProxyRequests Off # timeout in seconds ProxyPass / http://127.0.0.1:2283/ timeout=600 upgrade=websocket ProxyPassReverse / http://127.0.0.1:2283/ ProxyPreserveHost On</VirtualHost>Traefik
Section titled “Traefik”This example is for Traefik version 3. The most important part is raising the entry point’s timeouts. The default of 60 seconds stops video uploads after a minute with error 499; this raises it to 10 minutes, which is usually enough.
In traefik.yaml:
entryPoints: websecure: address: :443 # add this section transport: respondingTimeouts: readTimeout: 600s idleTimeout: 600sThen add labels to the server in Frameleaf’s docker-compose.yml:
services: frameleaf-server: labels: traefik.enable: true traefik.http.routers.frameleaf.entrypoints: websecure traefik.http.routers.frameleaf.rule: Host(`photos.example.com`) traefik.http.services.frameleaf.loadbalancer.server.port: 2283Finally, give Traefik access to the network Frameleaf runs on, usually by adding Traefik’s network to the frameleaf-server service. Put the labels in a docker-compose.override.yml so they survive when you replace the release’s Compose file on an upgrade.
Good to know
Section titled “Good to know”- Manager installations. Point your proxy at the server’s address and Frameleaf port, normally
2283. Manager shows the address on its Overview. Don’t put Manager itself (port2282) behind a public proxy: it controls Docker on your server, so keep it on your home network. - Port 2443 is something else. It’s the direct connection for Frameleaf Cloud remote access, which brings its own certificate. Your proxy doesn’t need it.
- Passkeys and iCloud sign-in need HTTPS. Browsers only make and use passkeys at an address that starts with
https, so a proxy with a certificate is what turns them on for your own domain. - Setting up a new server. Setup only works from your home network. Through a proxy, that means a visitor with a private address, passed on in
X-Forwarded-Forby a proxy Frameleaf trusts.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.