Files
immich-magic-proxy/docs/configuration.md
T
Alan Grainger f20e831375 Update docs
2026-06-04 10:41:10 +12:00

16 KiB

Configuration

Immich Public Proxy runs with sane defaults; most installs never need to touch config.json. Override only what you need.

Contents

How to provide a config override

Note: You only need to include the keys you're changing. Anything you omit keeps its default.

There are two ways to supply custom config:

Mount a file:

Recommended for anything non-trivial. Make a copy of config.json next to your docker-compose.yml, edit, then add a volume:

    volumes:
      - ./config.json:/app/config.json

Restart the container and your custom configuration becomes active.

Inline via env var:

For one-off or single-key overrides. See inline configuration.

How options are organised

All options live under ipp.*. Several groups follow a master-toggle plus per-field-overrides pattern (ipp.showMetadata.exif, ipp.showMetadata.location): set the group's enabled: true to expose the group, then turn individual fields off if you want fewer.

You only need to include the keys you're changing. Anything you omit keeps its default.

IPP options

Top-level options under ipp.*.

Option Type Description
responseHeaders object Change the headers sent with your web responses. By default there is cache-control and CORS added.
downloadOriginalPhoto bool Set to false if you only want people to be able to download the 'preview' quality photo, rather than your original photo.
downloadedFilename int The filename of the downloaded image.
0 for the original filename if available, falling back to the Immich asset ID
1 for the Immich asset ID number
2 for a shortened version of the asset ID: img_ plus the first 8 characters of the asset ID
allowDownloadAll int Allow visitors to download all files as a zip, including the selective-download flow in multi-select mode.
0 disable downloads
1 follow Immich setting per share (example)
2 always allowed
downloadFromImmichConcurrencyLimit int Maximum number of assets IPP will fetch from your Immich server in parallel when building a "download all" zip. Defaults to 8. Lower this if your Immich server is slow or you see download timeouts on large albums; raise it for faster downloads if your server can handle the load.
allowSlugLinks bool Enable/disable the custom URL links.
showHomePage bool Set to false to remove the IPP shield page at / and at /share.
gallery object Gallery-page options. See Gallery.
lightbox object Lightbox options. See Lightbox.
showMetadata object Description / EXIF / location reveal controls. See Metadata.
customInvalidResponse various Send a custom response instead of the default 404. See Custom responses.

For example, to disable the home page at / and at /share:

{
  "ipp": {
    "showHomePage": false
  }
}

Options that control how the gallery page is rendered. Configured under ipp.gallery.

Option Type Description
singleImage bool By default a link to a single image will directly open the image file. Set to true if you want to show a gallery page instead for a single item.
singleItemAutoOpen bool When a share contains a single item and is opened on its gallery page, automatically open the lightbox on the asset. Default true.
showTitle bool Show a title on the gallery page. This is taken from the album title if it is an album being shared, otherwise the "Description" from the shared link will be used.
showDescription bool Show the album description below the title. This only applies if it is an album which is being shared.
groupByDate bool Group the gallery's thumbnails by month, with headers like "December 2024" above each group. Sorts photos newest-first. Items missing a creation date end up under an "Undated" bucket at the end. Default false.

Example: show the gallery title and group photos by month.

{
  "ipp": {
    "gallery": {
      "showTitle": true,
      "groupByDate": true
    }
  }
}

Lightbox

The gallery's lightbox is powered by PhotoSwipe. Configured under ipp.lightbox.

Option Type Description
showArrows bool Show the prev/next arrows on desktop. They appear when the user hovers the lightbox. Default true.
showDownload bool Show a download button in the lightbox toolbar. Only takes effect when downloads are also allowed by allowDownloadAll. Default true.
mobileArrows bool Show prev/next arrows on mobile (under 640px viewport). Off by default since swipe is the natural mobile navigation.
options object Custom PhotoSwipe options to override defaults (e.g. {"wheelToZoom": true}).

Example: hide the download button inside the lightbox even though zip downloads are otherwise allowed.

{
  "ipp": {
    "lightbox": {
      "showDownload": false
    }
  }
}

Metadata

Configured under ipp.showMetadata. The lightbox includes a slide-in info sidebar (toggle with the i key or the info button in the toolbar) that surfaces whatever metadata you opt into here.

Option Type Description
description object Where to show the description. { "caption": bool, "sidebar": bool }. Both default false. See Description.
exif object Camera / file EXIF group. Set enabled: true to expose any of the per-field flags below. See EXIF group.
location object Location group (city / state / country / GPS). Set enabled: true to expose any of the per-field flags below. See Location group.

Within each group, the master enabled toggle controls whether the group's fields are sent at all. Per-field flags default to true once the group is enabled, so you can turn off individual fields without renaming or removing them.

IPP only sends a field if both the group's enabled is true AND the field's flag is true. If Immich itself isn't exposing metadata for the share (the per-share toggle on the Immich side), no metadata is available regardless of these settings.

The info sidebar (and its toolbar toggle button) only appear when there is at least one section the operator has opted into - i.e. description.sidebar, exif.enabled, or location.enabled is true. With all three off, the sidebar UI is suppressed.

Description

Under ipp.showMetadata.description.

Option Type Description
caption bool Show the description below the photo as a lightbox caption.
sidebar bool Show the description at the top of the info sidebar.

Set both to show in both places; set neither and the description is not included at all.

EXIF group

Under ipp.showMetadata.exif.

Option Type Description
enabled bool Master switch for the EXIF group. Default false.
dateTimeOriginal bool Show the date the photo was taken (per EXIF).
fileName bool Show the original filename.
dimensions bool Show width x height and megapixel count.
fileSize bool Show the file size.
make bool Camera manufacturer (e.g. "Canon").
model bool Camera model (e.g. "EOS R5").
lensModel bool Lens model.
exposureTime bool Shutter speed (e.g. "1/200").
iso bool ISO sensitivity.
fNumber bool Aperture f-number.
focalLength bool Focal length in millimetres.

Location group

Under ipp.showMetadata.location.

Option Type Description
enabled bool Master switch for the location group. Default false.
city bool Show city.
state bool Show state / region.
country bool Show country.
gps bool Show GPS coordinates.
webLink bool Show an "Open in OpenStreetMap" link below the coordinates. The link is rendered with rel="noreferrer" so the share URL is not leaked to the map provider when a viewer clicks it. Has no effect unless gps is also true. Default true.

A full example showing the description in the sidebar only (not as a lightbox caption), exposing full EXIF, and revealing place names but not the GPS coordinates:

{
  "ipp": {
    "showMetadata": {
      "description": { "caption": false, "sidebar": true },
      "exif": { "enabled": true },
      "location": { "enabled": true, "gps": false }
    }
  }
}

Customising your error response pages

You can customise the responses that IPP sends for invalid requests. For example you could:

  • Drop the connection entirely (no response).
  • Redirect to a new website.
  • Send a different status code.
  • Send a custom 404 page.

See Custom responses for the full reference.

Migration notes for upgraders

A few config keys have been renamed across versions. Existing configs continue to work via backward-compatibility shims and a startup deprecation notice. The shims will be removed in v3.0.

Gallery keys moved under ipp.gallery.* (v2.0). The old top-level keys are mapped automatically:

Legacy key New key
ipp.singleImageGallery ipp.gallery.singleImage
ipp.singleItemAutoOpen ipp.gallery.singleItemAutoOpen
ipp.showGalleryTitle ipp.gallery.showTitle
ipp.showGalleryDescription ipp.gallery.showDescription
ipp.groupGalleryByDate ipp.gallery.groupByDate

showMetadata.description is now an object. It used to be a single boolean. A legacy description: true migrates to { caption: true, sidebar: true } (and false to both false). Move to the explicit form to silence the deprecation notice and so you can target the caption vs. the sidebar independently.