Files
immich-magic-proxy/lxc

Running in an LXC container

Immich Magic Proxy runs as a systemd service in an unprivileged Debian 13 (trixie) container. The Docker image is not needed.

1. Build a release (on your workstation)

lxc/build-release.sh

This needs Docker or Podman, and writes dist-release/immich-magic-proxy-<version>-<commit>.tar.gz (about 4 MB) with a .sha256 beside it. The tarball is self-contained: all dependencies are pure JavaScript, so it runs on amd64 or arm64. Nothing is compiled in the container.

2a. Proxmox VE: create the container and install

Copy the tarball, install.sh and proxmox-create.sh into one directory on the Proxmox host, then as root:

IMMICH_URL=http://192.168.1.20:2283 \
PUBLIC_BASE_URL=https://photos.example.com \
ADMIN_PASSWORD='a long random password' \
SMTP_URL=smtp://user:password@smtp.example.com:587 \
MAIL_FROM='Our photos <photos@example.com>' \
./proxmox-create.sh immich-magic-proxy-<version>.tar.gz

It downloads the Debian 13 template if needed and creates an unprivileged container with nesting on and start-on-boot. It then installs everything and prints the container's address. Optional settings: CTID, CT_HOSTNAME, STORAGE (local-lvm), TEMPLATE_STORAGE (local), BRIDGE (vmbr0), IP (dhcp or 192.168.1.50/24), GATEWAY, VLAN, CORES (1), MEMORY (512 MB), DISK (4 GB), PORT (3000), SITE_NAME, DIGEST_HOUR, TZ (defaults to the host's), and SMTP_HOST/SMTP_PORT/SMTP_USER/SMTP_PASS/SMTP_SECURE instead of SMTP_URL.

Then point your reverse proxy (HTTPS) at the container's port 3000, open /admin, and sign in.

2b. Any other Debian 13 LXC container (Incus, LXD, plain LXC)

Copy the tarball and install.sh into the container, then as root:

./install.sh immich-magic-proxy-<version>.tar.gz
nano /etc/immich-magic-proxy/env     # set IMMICH_URL, PUBLIC_BASE_URL, ADMIN_PASSWORD, SMTP...
systemctl restart immich-magic-proxy

The service waits until ADMIN_PASSWORD is set. The container needs nesting enabled (Incus/LXD: security.nesting=true) for the service's systemd sandboxing.

Where things are

/etc/immich-magic-proxy/env Settings (root-only, it holds passwords). In the file, put any value with spaces or symbols in double quotes, with \ before \ " $ or a backtick inside it
/etc/immich-magic-proxy/config.json Upstream's ipp config (see docs/config)
/var/lib/immich-magic-proxy/ The database: recipients, sessions, comments. Back this up
/opt/immich-magic-proxy/current The running release; the last 3 are kept in releases/

Logs: journalctl -u immich-magic-proxy -f. The service runs as the immich-magic-proxy user. It can write only to its data directory and can't modify its own code.

Node.js 24 comes from NodeSource's signed apt repository, so apt upgrade keeps it patched.

Upgrading and rolling back

Build a new release, copy it in, and run install.sh with it again. Settings and data are kept, and the service restarts on the new release. On Proxmox:

pct push <ctid> immich-magic-proxy-<new>.tar.gz /root/release.tar.gz
pct push <ctid> install.sh /root/install.sh --perms 0755
pct exec <ctid> -- /root/install.sh /root/release.tar.gz

To roll back, point current at an earlier release and restart:

ln -sfn /opt/immich-magic-proxy/releases/<older> /opt/immich-magic-proxy/current
systemctl restart immich-magic-proxy

Backups

The database is SQLite in WAL mode. For a consistent, root-only copy while it runs:

umask 077; node -e "new (require('node:sqlite').DatabaseSync)('/var/lib/immich-magic-proxy/magic.db').exec(\"VACUUM INTO '/root/magic-backup.db'\")"

A Proxmox backup (vzdump) of the container also covers it.