174 lines
10 KiB
Markdown
174 lines
10 KiB
Markdown
# Immich Magic Proxy
|
|
|
|

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

|
|
|
|
### Inviting a user:
|
|
|
|

|
|
|
|
### The invite email:
|
|
|
|

|
|
|
|
### The user's account view:
|
|
|
|

|
|
|
|
## 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).
|