# Reverse proxy

Source: https://frameleaf.app/docs/admin/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](https://frameleaf.app/docs/cloud/remote-access/) gives you HTTPS and a stable address without opening ports. See [Remote access](https://frameleaf.app/docs/admin/remote-access/) for all the options.

## What every proxy needs

- **Forward all headers**, and set `Host`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-For` to 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 `.env` and run `docker compose up -d`.

Setting it replaces the default, so include every proxy you use. See [Environment variables](https://frameleaf.app/docs/admin/environment-variables/#general).

If your proxy also asks for extra headers or a client certificate, see [Give the apps access through your proxy](#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](https://frameleaf.app/docs/admin/sign-in-and-oauth/#redirect-uris).

:::note[Let's Encrypt http-01]
If your proxy gets certificates with the Let's Encrypt http-01 challenge, it answers requests under `/.well-known/` itself. Make sure `/.well-known/frameleaf` and `/.well-known/immich` still reach Frameleaf. The apps read them to find the server; the second path is kept for older apps.
:::

## 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](https://frameleaf.app/docs/apps/iphone/#servers-behind-a-proxy) and [Android](https://frameleaf.app/docs/apps/android/#servers-behind-a-proxy).

**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:

```bash
openssl pkcs12 -export -inkey alex.key -in alex.crt -certfile ca.crt -out alex.p12
```

Send 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.

## nginx

Replace `<public_url>` with your domain and `<backend_url>` with the address of the Frameleaf server.

```nginx
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

Caddy sets up HTTPS for you automatically:

```text
photos.example.com {
    reverse_proxy http://<backend_url>:2283
}
```

## Apache

```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

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`:

```yaml
entryPoints:
  websecure:
    address: :443
    # add this section
    transport:
      respondingTimeouts:
        readTimeout: 600s
        idleTimeout: 600s
```

Then add labels to the server in Frameleaf's `docker-compose.yml`:

```yaml
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: 2283
```

Finally, 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

- **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 (port `2282`) 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](https://frameleaf.app/docs/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-For` by a proxy Frameleaf trusts.
