Files
immich-magic-proxy/docs/installation.md
T
2026-10-06 09:23:57 +13:00

2.7 KiB

Installation

Note

IPP requires Immich 3.0.0 or newer. It checks the server version at startup and will exit with an error against an older Immich.

Install with Docker / Podman

  1. Download the docker-compose.yml file.

  2. Update the value for IMMICH_URL in your docker-compose file to point to your local URL for Immich. This should not be a public URL. Most likely this will be a local IP and port; whatever your Immich container runs on.

  3. Update or remove the value for PUBLIC_BASE_URL. This should be the public base URL for IPP, without a trailing slash (example https://your-proxy-url.com). If you remove this value, it will dynamically generate it based on the request hostname. This can be useful if you are serving from multiple domains.

  4. Start the docker container. You can test that it is working by visiting https://your-proxy-url.com/share/healthcheck. Check the container console output for any error messages.

docker-compose up -d
  1. Set the "External domain" in your Immich Server Settings to be whatever domain you use to publicly serve Immich Public Proxy:
Immich server settings - external domain

Now whenever you share an image or gallery through Immich, it will automatically create the correct public path for you.

Warning

If you're using Cloudflare, please make sure to set your /share/video/*, /share/*/download and /s/*/download paths to Bypass Cache, otherwise you may run into video playback issues and failed zip downloads. See Troubleshooting for more information.

Those two variables are all most people need. The port and the config file location are covered under Environment variables, and everything about how galleries look and behave under Configuration.

Docker images

Images are published to Docker Hub (alangrainger/immich-public-proxy) and GitHub Container Registry (ghcr.io/alangrainger/immich-public-proxy) for linux/amd64 and linux/arm64. Each release is tagged with its full version (for example 3.3.0), its minor version (3.3) and its major version (3), and latest always points at the newest release.

Running alongside Immich on a single domain

Because all IPP paths are under /share/... and /s/..., you can run Immich Public Proxy and Immich on the same domain. See Running on a single domain.

Install with Kubernetes

See the Kubernetes install docs.

Next: Sharing from Immich.