Immich Public Proxy

A focused look at the security layer that makes Immich photo sharing actually safe. No marketing fluff, just what you get when you deploy it.

TL;DR

• What it is: A stateless reverse proxy that sits in front of your private Immich instance and only passes through publicly-shared content — nothing else [README].
• Who it’s for: Immich users who want to share albums and photos with non-technical family or clients without exposing their entire Immich installation to the internet [README].
• Cost: Free (AGPL-3.0). Runs as a single Docker container alongside your existing Immich stack. No API key needed, no database, no state [README].
• Key strength: Zero-configuration sharing after initial setup. All share management happens inside Immich — you never touch IPP again [README].
• Key weakness: It’s a companion tool, not a standalone product. It solves exactly one problem: safe public sharing from Immich. If you don’t already run Immich, this isn’t your starting point.
• GitHub stars: 1,674 — small but focused.

---

What is Immich Public Proxy

Immich is a self-hosted Google Photos alternative — AI-powered facial recognition, semantic search, automatic mobile backup, map views, the full suite [1]. It’s also software that holds every private photo your family has ever taken, which means keeping it locked down behind a VPN or mTLS is the correct default security posture [README][1].

The problem surfaces when you want to share a vacation album with your parents or send a single photo to a client. Immich has a sharing feature, but to use it over the public internet, you need to expose the /api/ path — and exposing /api/ means that any current or future vulnerability in Immich becomes reachable by anyone on the internet [README].

Immich Public Proxy (IPP) solves this with a narrow security boundary. It’s a small Node.js application that runs as an additional Docker container. You point your public domain at IPP instead of directly at Immich. IPP inspects each incoming request and only passes through content that Immich has explicitly marked as publicly shared. Everything else — your private albums, your user accounts, your entire /api/ surface — is invisible to the outside world [README].

The author’s stated ideal setup: run Immich privately behind mTLS or WireGuard VPN, and put only IPP on the public internet. IPP has no login, no admin panel, no database to compromise. The README includes a worked example for securing Immich behind mTLS using Caddy or Traefik with this architecture [README].

What makes this more than a simple nginx path filter is the stateless design. IPP holds no knowledge of your Immich instance. It doesn’t cache credentials, doesn’t store share metadata, and critically does not require an API key — which removes an entire class of credential-leakage attacks from the equation [README]. When you ask IPP to display a shared album, it asks Immich “is this share token public?” in real time using the same unauthenticated endpoint that Immich itself exposes for valid shares, and then proxies the response.

---

Why People Choose It

The third-party coverage of IPP specifically is thin — most reviews of Immich don’t mention it. What does exist is a clear pattern of Immich users struggling with the share-safety problem, and IPP being the answer that keeps coming up.

The core tension: Immich users who followed security best practices locked their instance behind a VPN [1][5]. These setups work perfectly until someone who isn’t on the VPN — a grandparent, a client, a friend — needs to see a gallery. The options are: expose Immich publicly (bad), set up VPN access for every person you want to share with (impractical), or use a purpose-built proxy that handles exactly this case [README].

The networking rabbit hole: Several Immich articles describe elaborate WireGuard + Nginx configurations to expose Immich externally while maintaining security [5]. A setup documented by ditatompel [5] routes through a VPS with WireGuard tunneling back to a local LXC — functional, but involves Cloudflare DNS configuration, manual certificate management, and a multi-hop network topology. IPP offers a simpler mental model: keep Immich entirely private, expose one small proxy service, done.

The /api/ exposure problem: The README directly addresses a common misunderstanding — that you can just put Immich behind nginx and only expose the /share/ path. In practice, shared albums require /api/ access, which means truly public gallery viewing isn’t achievable with path filtering alone [README]. IPP is the architecturally correct solution to this constraint.

The WordPress plugin for Immich [3] illustrates the same problem from a different angle: it explicitly notes that Immich’s API key must never be exposed to browsers, and routes all Immich API calls server-side. IPP is the same philosophy applied to public gallery sharing.

---

Features

Based on the README and project documentation:

Core proxy behavior:

• Passes only publicly-shared content from Immich to the outside world [README]
• Stateless — no database, no persistent storage, no session management [README]
• No API key required on IPP’s side, reducing attack surface [README]
• Healthcheck endpoint at /share/healthcheck for monitoring [README]
• Password-protected share support [README]

Share types:

• Photo sharing — single images, served directly as image files by default (embeddable anywhere you’d use a normal image URL) [README]
• Video sharing with seeking support [3]
• Album/gallery sharing with lightGallery integration for the gallery UI [README]
• Configurable behavior for single-image links (direct file vs. gallery page) [README]

Integration:

• Share management stays entirely inside Immich — you use Immich’s native share feature, IPP just handles the public delivery [README]
• Set Immich’s “External domain” to the IPP public URL and share links auto-generate correctly [README]
• Works alongside Immich on a single domain since all IPP paths are under /share/... [README]
• Multi-domain support — IPP can dynamically generate base URLs from request hostname, useful if you serve from multiple public domains [README]

Deployment:

• Docker and Podman support [README]
• Kubernetes support (separate docs) [README]
• Three environment variables for basic configuration: IMMICH_URL, PUBLIC_BASE_URL, optional IPP_PORT [README]
• Custom error pages [README]

---

Pricing: What Immich + IPP Actually Costs

IPP itself is free. This section is really about the broader cost comparison: what does the Immich + IPP stack cost versus staying on a cloud photo service.

Cloud photo service pricing (for reference):

• Google Photos: free up to 15GB of Google Account storage, then $2.99/mo for 100GB, $9.99/mo for 2TB
• iCloud: $0.99/mo for 50GB, $2.99/mo for 200GB, $9.99/mo for 2TB
• Amazon Photos: included with Prime (but Prime is ~$140/yr)

Self-hosted Immich + IPP stack:

• Immich: free (AGPL-3.0) [1]
• Immich Public Proxy: free (AGPL-3.0) [README]
• Hardware: a NAS or home server you may already have, or a VPS
• VPS if you go cloud-hosted: ElfHosted offers managed Immich [4]; a self-managed Hetzner or Contabo VPS with enough storage runs $5–20/mo depending on storage needs

Concrete math for a family with 500GB of photos:

• Google One 2TB plan: $9.99/mo = ~$120/yr
• Self-hosted Immich on a $6/mo VPS with 1TB storage (or a home NAS with sunk hardware cost): roughly $72/yr for VPS-hosted, near-zero marginal cost if using existing hardware

The savings aren’t as dramatic as automation-tool comparisons because cloud photo storage is already relatively cheap. The real value proposition is data sovereignty and no storage limits — a 10TB drive attached to a home server costs less than two years of 2TB cloud storage [1].

IPP adds no cost to this equation. It’s a single lightweight Docker container that runs on the same VPS as Immich.

---

Deployment Reality Check

The README claims setup takes less than a minute, which is accurate if you already have Immich running and understand Docker Compose. The actual steps are:

1. Download the docker-compose.yml
2. Set IMMICH_URL to your private Immich URL (internal network address, not public)
3. Set PUBLIC_BASE_URL to your IPP public domain
4. Run docker-compose up -d
5. Point Immich’s “External domain” setting to your IPP public URL

That’s it. After this, every share link you create inside Immich automatically routes through IPP.

What you need before you start:

• A working Immich instance (the non-trivial part — Immich itself requires Docker, PostgreSQL, Redis, and a reverse proxy) [1][2]
• A public domain pointed at the machine or VPS running IPP
• A reverse proxy in front of IPP for HTTPS (Caddy, Traefik, or nginx)

What can go sideways:

The README has a notable Cloudflare warning: if you’re using Cloudflare, set the /share/video/* path to Bypass Cache or you’ll hit video playback issues [README]. This is the kind of gotcha that wastes an hour if you miss it.

IPP’s architecture means Immich must be network-reachable from the IPP container. In a typical Docker Compose setup on the same host this is trivial. If Immich is on a different machine, or behind a VPN, you need to ensure IPP can reach it on its internal URL — which is by design (you don’t want IPP reaching your Immich via the public internet).

The stateless design is a strength for security but means IPP has no built-in rate limiting or abuse protection. If someone discovers a public share URL and hammers it, the load hits Immich directly through the proxy. For most personal use this is irrelevant; for anyone sharing with large public audiences, put a rate limiter at the nginx/Caddy layer upstream of IPP.

One architectural note from the README worth understanding: IPP is not a CDN or caching layer. Every request for a shared photo goes through IPP to Immich in real time. If you’re sharing a high-traffic gallery, your Immich instance serves all of it.

Realistic setup time if Immich is already running: 5–15 minutes. If you’re starting from zero (no Immich), Immich itself is the work — IPP is the easy part.

---

Pros and Cons

Pros

• Solves one problem perfectly. This is a narrow tool with a clear scope: safe public sharing from a private Immich. It doesn’t try to be a CDN, a CMS, or a media server. That focus is a feature [README].
• Genuinely stateless. No database, no API keys stored, no session tokens. The attack surface is minimal by design [README].
• Zero ongoing maintenance. After the initial domain setup, everything is managed through Immich’s native UI. You never touch IPP again [README].
• No API key exposure. IPP accesses only what Immich publicly exposes for valid share tokens. There’s no privileged credential sitting in the proxy that could be compromised [README].
• Password-protected shares work. Password protection from Immich passes through correctly — useful for sharing with specific people without making content fully public [README].
• Kubernetes support. For anyone already running Immich on k8s, IPP has documented Kubernetes deployment [README].
• Enables locking Immich down harder. With IPP handling public shares, Immich can be moved behind mTLS or VPN with zero user-facing degradation for sharing workflows [README].

Cons

• Useless without Immich. This isn’t a criticism exactly — it’s just scope — but IPP has zero standalone value. If you’re not already committed to Immich, the onboarding path starts with Immich, not here.
• No caching. Every shared photo request hits Immich in real time. For high-traffic sharing scenarios, this creates load on your Immich instance [README].
• No built-in rate limiting or abuse protection. Anyone with a valid share URL can hammer it. You need to implement rate limiting at the upstream proxy layer yourself.
• Small project, single maintainer. 1,674 stars, 49 forks, one primary author. It works well and is actively maintained (373 commits, 64 releases as of the scrape date), but there’s no org backing it [README].
• AGPL-3.0 license. For commercial deployments where you’re embedding IPP in a product, the copyleft terms matter. For personal and small-team use, it’s irrelevant.
• Cloudflare video cache issue. The video playback problem with Cloudflare caching [README] is a real gotcha that isn’t obvious and requires manual cache rule configuration.
• No media transformation. IPP proxies original files. No resizing, compression, or format conversion for different devices. What Immich has is what gets served.

---

Who Should Use This / Who Shouldn’t

Use Immich Public Proxy if:

• You already run Immich and want to share photos with people who aren’t on your VPN.
• You’ve locked Immich down tightly (mTLS, VPN-only) and this has broken sharing links.
• You’re sharing photo albums with family, clients, or the public and don’t want to expose your entire Immich instance to do it.
• You care about the principle of minimal attack surface — IPP is the right architecture for this use case.

Skip it (not applicable) if:

• You don’t run Immich. Start with Immich, come back to IPP once you’re sharing.
• You’re running Immich behind Cloudflare Tunnel and using Cloudflare’s own access controls — you may have an alternative path to the same goal, though IPP is still cleaner.
• You want caching or CDN-style media delivery for high-traffic public galleries — IPP isn’t that.

Skip it (pick a different approach) if:

• You need to share Immich content and require your Immich instance to remain fully public anyway (e.g., a shared family server where everyone is a user). In that case, just secure Immich directly with proper authentication and skip the extra proxy.
• You want media embeds with transformations (resizing, watermarks, format conversion) — IPP passes originals through, nothing more.

---

Alternatives Worth Considering

For the specific use case of safe Immich sharing, there isn’t a direct competing tool — IPP occupies a narrow slot. The alternatives are architectural approaches:

• Nginx path filtering — expose only /share/ and /api/ with a reverse proxy. The README explains why this is insufficient: shared album views require full /api/ access, not just the share path [README]. IPP is the correct solution.
• Cloudflare Tunnel + Access — put Immich behind Cloudflare Tunnel and use Cloudflare Access policies to control what’s public. More infrastructure to manage, but gives you additional features like audit logs and geographic restrictions.
• WireGuard VPN for share recipients — technically sound but impractical for sharing with non-technical people [5].
• ElfHosted managed Immich [4] — if you’re not comfortable managing your own Immich stack, ElfHosted hosts it for you. They handle the infrastructure; you still configure IPP-style sharing separately.
• WordPress Media Picker for Immich [3] — if your sharing target is a WordPress site, this plugin proxies Immich media server-side without exposing the API key to browsers. Solves the same problem in a different context (WordPress site → Immich, rather than public gallery → Immich).

For anyone evaluating the broader Immich-vs-cloud-photos decision, the self-hosting guide from glukhov.org [1] and the Dutch review from sebastix.nl [2] cover the full Immich setup in detail, including the mobile backup workflow and the tech stack.

---

Bottom Line

Immich Public Proxy is a small, focused tool that does one thing correctly: it lets you share photos from a locked-down Immich instance without compromising the security of that instance. The stateless design, the absence of an API key requirement, and the zero-ongoing-maintenance model are all architectural choices that hold up under scrutiny. If you run Immich and have hit the share-vs-security tension — and most security-conscious Immich users do — IPP is the right answer. The setup is genuinely fast, the Cloudflare video cache gotcha is documented, and once it’s running you forget it exists. The only honest caveat is that this is a single-maintainer community project at 1,674 stars, not a product with a company behind it. For personal and small-team use, that’s fine. Bet your business-critical photo infrastructure on it with eyes open.

---

Sources

1. Rost Glukhov — “Self-Hosting Immich: Private Photo Cloud” (November 2025). https://www.glukhov.org/post/2025/11/selfhosting-immich/

2. Sebastian Hagens — “Immich review - backup jouw foto’s en video’s op je mobiele telefoon”. https://sebastix.nl/blog/immich-review-backup-jouw-fotos-en-videos-op-je-mobiele-telefoon/

3. WordPress.org Plugin Directory — “Media Picker for Immich”. https://wordpress.org/plugins/media-picker-for-immich/

4. ElfHosted Documentation — “Hosted Immich - Cloud Photo & Video Backup”. https://docs.elfhosted.com/app/immich/

5. ditatompel Insights — “Access Any Self-Hosted Applications at Home From Anywhere” (October 23, 2024). https://insights.ditatompel.com/en/tutorials/access-any-self-hosted-applications-at-home-from-anywhere/

Primary sources:

• GitHub repository and README: https://github.com/alangrainger/immich-public-proxy (1,674 stars, AGPL-3.0, 373 commits, 64 releases)
• Live demo gallery: https://immich-demo.note.sx/share/gJfs8l4LcJJrBUpjhMnDoKXFt1Tm5vKXPbXl8BgwPtLtEBCOOObqbQdV5i0oun5hZjQ