Files
immich-magic-proxy/README.md
T
2026-11-08 03:01:09 -08:00

174 lines
10 KiB
Markdown

# Immich Magic Proxy
![](docs/screenshots/album-view.png)
A fork of [Immich Public Proxy](https://github.com/alangrainger/immich-public-proxy) (4.1.1) that adds invitations,
comments and new-photo emails. Each share is either **public** (anyone with its Immich link can view it, as upstream)
or **sign-in only** (only people you invite).
- **Public or sign-in only.** Any Immich shared link opened through the proxy is added to `/admin` automatically, as
public. Untick "Public link works" there to make it sign-in only. Shares you add in `/admin` yourself are public
unless you untick the box when adding them. Shares added before this setting existed stay sign-in only. A key
Immich doesn't know is refused, and Immich is asked about it at most once every 10 minutes.
- **Magic links.** You add the people allowed to see a share. Each person gets a personal link. For a sign-in only
share, without a valid link every page, photo, video, download and API route answers with a "private photos"
page or a 404, and never touches Immich.
- **Bookmarkable.** Opening the link signs that browser in with an `HttpOnly` cookie that lasts 400 days (the
browser maximum) and renews itself daily while in use. Sessions live in the database, so restarts don't sign
anyone out. Recipients can bookmark an album, or `/me` for all their albums.
- **New-photo emails.** Each recipient chooses daily, weekly, monthly or never (you set their starting choice). The
proxy checks every album for new photos and sends one summary email per period, with a sign-in link per album.
Photos that were already there when someone got access are never reported as new.
- **Comments.** Recipients can comment on any photo from the lightbox (comment button, or the info sidebar). They can
delete their own; you can moderate all of them from the admin page. Comments are only ever shown to recipients
given that share, never via a public share.
- **Hearts.** Recipients can heart a photo from the lightbox, with totals. Like comments, hearts are for authenticated
recipients only.
- **Activity.** `/admin` shows how often each album's gallery was opened (and how many of those opens were by
visitors who weren't signed in), its hearts, and how often each recipient opened their albums. A recipient's page
lists each signed-in browser with when it was last used and its views, and can sign out any one of them. Counting
started with this release; earlier visits aren't included.
- **Lost links.** A visitor with no session can ask for a new link by email. The reply is the same whether or not the
address was invited, and requests are rate-limited.
- **Password-protected shares.** Store the share password when adding the album, and recipients are never asked
for it.
### Comments and hearts:
![](docs/screenshots/comments-and-likes.png)
### Inviting a user:
![](docs/screenshots/invite-user.png)
### The invite email:
![](docs/screenshots/invite-email.png)
### The user's account view:
![](docs/screenshots/user-view.png)
## Setup
To run it in an LXC container (Proxmox, Incus, LXD) instead of Docker, see [`lxc/README.md`](lxc/README.md).
1. Set the environment (see `docker-compose.yml`) and start it with `docker compose up -d --build`. Mount a volume at
`/data`: it holds the SQLite database of recipients, sessions and comments. Back it up.
2. Open `/admin` and sign in with `ADMIN_PASSWORD`.
3. Under **Albums**, paste an Immich shared link (`https://immich.example.com/share/...` or `/s/<slug>`), or just
open it through the proxy. Choose whether its public link works.
4. Under **Recipients**, add each person, tick their albums, and either email the invitation or copy the link.
From a recipient's page you can send a new link, revoke every link and session they have, disable them, or delete
them.
| Variable | |
| --- | --- |
| `IMMICH_URL` | Immich's internal URL, as upstream |
| `PUBLIC_BASE_URL` | This proxy's public URL. Needed for links in emails, and `https://` makes cookies `Secure` |
| `ADMIN_PASSWORD` | Turns on `/admin`. Without it there is no admin console |
| `SMTP_URL` or `SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` / `SMTP_SECURE` | Outgoing mail. Without it, no emails are sent; you copy links by hand |
| `MAIL_FROM` | Sender address, e.g. `Our photos <photos@example.com>` |
| `SITE_NAME` | Name used in email subjects. Default `Shared photos` |
| `DIGEST_HOUR` | Hour (0-23) that notification emails go out. Default `8` |
| `TZ` | Timezone for `DIGEST_HOUR`. Default UTC |
| `NOTIFY_INTERVAL_MINUTES` | How often albums are checked for new photos. Default `60` |
| `DATA_DIR` | Database directory. `/data` in the image, `./data` otherwise |
| `TRUST_PROXY` | Express `trust proxy` setting. Default trusts private-network proxies |
## Differences from upstream
- Responses are cached `private` only, with no CORS header, so a CDN can't hand a photo to someone without a session.
If you set `ipp.responseHeaders` yourself, keep `Cache-Control` private.
- The gallery page is `private, no-cache`; `ipp.gallery.cacheTime` and `ipp.showHomePage` are no longer used. `/`
goes to the recipient's albums.
- `ipp.gallery.singleImage` defaults to `true`, so a one-photo share opens in the gallery where it can be commented on.
- `ipp.uploadUrl` defaults to off. The separate upload service (`upload-app/`) does not check magic-link sessions,
so don't route it unless you accept that anyone with a share key can upload.
- An Immich share link still works directly on Immich itself; this proxy only controls access through the proxy.
Keep Immich private, as upstream recommends.
- Removing a share in `/admin` doesn't block its link: if Immich still accepts it, opening it adds the share back as
public. To block a share, make it sign-in only, or delete the link in Immich.
The rest of this README is upstream's.
---
# Immich Public Proxy
<p align="center" width="100%">
<img src="docs/public/ipp.svg" width="180" height="180">
</p>
<p align="center" width="100%">
<a href="https://hub.docker.com/r/alangrainger/immich-public-proxy/tags">
<img alt="Docker pulls" src="https://badgen.net/docker/pulls/alangrainger/immich-public-proxy?icon=docker&label=docker%20pulls&color=green&scale=1.1"></a>
<a href="https://github.com/alangrainger/immich-public-proxy/releases/latest">
<img alt="Latest release" src="https://badgen.net/github/tag/alangrainger/immich-public-proxy?scale=1.1&label=release"></a>
<a href="https://demo.ipp.nz/s/demo-gallery"><img alt="Open demo gallery" src="https://badgen.net/static/↗🖼️/live%20demo/green?scale=1.1"></a>
</p>
Share your Immich photos and albums in a safe way without exposing your Immich instance to the public.
**This does not need an API key, or any privileged access to Immich.** Setup takes less than a minute, and you never need to touch it again as all of your sharing stays managed within Immich.
See a [Live demo gallery](https://demo.ipp.nz/s/demo-gallery) serving straight out of my own Immich instance.
<p align="center" width="100%">
<img src="docs/public/screenshot.webp" width="602" height="414" border="1px solid white">
</p>
## About this project
[Immich](https://github.com/immich-app/immich) is a wonderful bit of software, but since it holds all your private photos it's
best to keep it fully locked down. This presents a problem when you want to share a photo or a gallery with someone.
**Immich Public Proxy** provides a barrier of security between the public and Immich, and _only_ allows through requests
which you have publicly shared. It is stateless, needs no API key, and knows nothing about your Immich instance beyond
what you have shared.
Read more in the [Introduction](https://docs.ipp.nz/introduction), including
[why not just expose Immich's `/share/` path](https://docs.ipp.nz/introduction#why-not-expose-immich-directly).
Visitors can optionally add their own photos and videos to a share, for example guests at a wedding. See
**[Let visitors send photos back](https://docs.ipp.nz/visitor-uploads)**.
## Quick start
1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml) file.
2. Set `IMMICH_URL` to the local (not public) URL of your Immich server, and `PUBLIC_BASE_URL` to the public URL of IPP.
3. Run `docker-compose up -d` and check that `https://photos.example.com/share/healthcheck` responds.
4. In Immich's **Server Settings**, set the "External domain" to your IPP URL. Every link Immich generates from now on
points at the proxy.
If you use Cloudflare, set your `/share/video/*` path to Bypass Cache or videos may not play.
Full instructions, including Kubernetes: **[Installation](https://docs.ipp.nz/installation)**.
## Documentation
Everything is at **[docs.ipp.nz](https://docs.ipp.nz)**:
- [Installation](https://docs.ipp.nz/installation) and [Sharing from Immich](https://docs.ipp.nz/how-to-use)
- [Configuration](https://docs.ipp.nz/config/): downloads, gallery layout, lightbox, metadata privacy, error responses
- Guides: [let visitors send photos back](https://docs.ipp.nz/visitor-uploads),
[single domain with Immich](https://docs.ipp.nz/running-on-single-domain),
[redirect your root domain to a share](https://docs.ipp.nz/redirect-root-to-share),
[securing Immich with mTLS](https://docs.ipp.nz/securing-immich-with-mtls)
- [Troubleshooting](https://docs.ipp.nz/troubleshooting)
## Feature requests
You can [add feature requests here](https://github.com/alangrainger/immich-public-proxy/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop).
IPP has **read-only** access to Immich and stores nothing: anything that needs an API key, modifies Immich, or would
require storing a share key won't be considered. Visitor uploads are the one write path, and they live in their own
optional container. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full list.
## Thanks
The gallery lightbox, with its zoom, swipe and keyboard navigation, is **[PhotoSwipe](https://photoswipe.com/)** by
[Dmytro Semenov](https://github.com/dimsemenov). It is a superb piece of work, MIT licensed, and IPP would be a much
poorer viewer without it. If you find it useful, consider [sponsoring the project](https://github.com/sponsors/dimsemenov).