samuelstreets/immich-share repository overview

⁠🖼️ Immich Share

A self-hosted web app that sits alongside your Immich⁠ instance and lets you share albums or photos with anyone via a password-protected URL — no Immich account required.

⁠Features

• 🔒 Password-protected shares — each share has its own password
• 🔑 Passwordless access — generate a token-in-URL link (no password prompt)
• 📁 Album or tag shares — share a whole Immich album or assets by tag
• ⏱ Expiry dates — shares can auto-expire
• 👁 Max view limits — auto-disable a share after N views
• ⬇ Optional downloads — control whether viewers can download originals or a ZIP
• ⬆ Optional uploads — let viewers contribute photos back to the album (chunked, no file-size limit)
• 🏷 Auto-tag uploads — automatically apply Immich tags to every uploaded asset
• 👀 Album watcher — periodically tags new assets added to watched albums
• 🔗 Custom slugs — friendly URLs like /s/summer-2024
• 🌐 External URL config — set the public URL used in share links
• 🖼 Lightbox viewer — full-screen photo/video viewer with pinch-to-zoom, drag-to-pan, and keyboard navigation
• ✅ Drag-to-select — select multiple photos in the gallery and bulk-download as ZIP
• 📊 Admin dashboard — stats, per-share activity charts, access logs with export (CSV/JSON)
• 🔔 Notifications — email (SMTP) and webhook alerts on upload, per-share or global
• 🔐 Two-factor authentication — TOTP (Google Authenticator, Authy, etc.) for the admin login
• 🧹 Scheduled cleanup — auto-purge expired shares and orphaned upload chunks
• 📱 Mobile-friendly admin — responsive sidebar + bottom nav for phones
• 🐳 Single Docker container — easy to self-host

⁠Quick Start (Docker Compose)

# 1. Clone the repo
git clone https://github.com/YOUR_USERNAME/immich-share.git
cd immich-share

# 2. Create your .env file
cp .env.example .env
# Edit .env — set JWT_SECRET at minimum

# 3. Start
docker compose up -d

# 4. Open http://localhost:3000
# Login: admin / admin  (change immediately in Settings!)

⁠Configuration

Settings can be configured via environment variables (seed on first boot) or the admin UI → Settings page at any time.

*These can be set via the Settings UI after first boot.

⁠Getting an Immich API Key

1. Open your Immich web UI
2. Click your profile icon → Account Settings
3. Go to API Keys → New API Key
4. Copy the key and paste it into the Settings page (or .env)

⁠Required API Key Permissions

⁠Share Features

⁠Passwordless Access

Generate a static token-in-URL link for a share — visitors open the link and go straight to the gallery without a password prompt. Tokens can be generated or revoked at any time from the Shares admin page.

⁠Custom Slugs

Instead of /s/<uuid>, give a share a memorable URL like /s/wedding-photos. Slugs must be 3–60 lowercase alphanumeric characters or hyphens and must be unique.

⁠Max Views

Set a view limit on a share — it is automatically disabled once the limit is reached (checked every 30 minutes by the cleanup job).

⁠Upload Tags

When uploads are enabled, select one or more Immich tags to be automatically applied to every photo uploaded through that share.

⁠Album Watcher

For album shares, configure "watch tags" — the watcher runs every 5 minutes and applies those tags to any assets that have been newly added to the album since the last check.

⁠Notifications

Configure SMTP settings globally and set a per-share notify email to receive an alert whenever someone uploads a file. Webhooks (global or per-share) fire a signed JSON payload on each upload and can be used to trigger automations.

⁠Reverse Proxy (nginx example)

server {
    listen 443 ssl;
    server_name share.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        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;
        # Required for large uploads and downloads
        proxy_buffering off;
        proxy_read_timeout 300s;
        client_max_body_size 0;
    }
}

⁠Local Development

⁠Prerequisites

• Node.js 20+
• An Immich instance

⁠Run locally

# Quickstart script (copies .env.example if no .env exists)
./dev.sh

# Or manually:

# Backend
cd backend
cp ../.env.example .env  # edit it — set JWT_SECRET at minimum
npm install
node src/index.js

# Frontend (separate terminal)
cd frontend
npm install
npm run dev
# → http://localhost:5173 (proxies /api to :3000)

⁠Build Docker image locally

docker build -t immich-share .
docker run -p 3000:3000 \
  -e JWT_SECRET=change-me-to-something-long \
  -e IMMICH_URL=http://your-immich:2283 \
  -e IMMICH_API_KEY=your-key \
  -e EXTERNAL_URL=http://localhost:3000 \
  -v immich-share-data:/app/data \
  immich-share

⁠Data & Privacy

• All share metadata is stored in a local SQLite database at /app/data/app.db
• No photo data is stored — all media is proxied directly from your Immich instance
• Share passwords are bcrypt-hashed (cost factor 10)
• Admin passwords are bcrypt-hashed (cost factor 12)
• Share session tokens are HMAC-SHA256 signed, valid for 8 hours
• Webhook payloads are optionally HMAC-SHA256 signed (X-ImmichShare-Signature: sha256=…)
• Rate limiting is applied to auth, share-verify, and token-access endpoints

⁠License

MIT