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), ROOT_PASSWORD, SSH_PUBLIC_KEYS (a file of keys for root), CONSOLE_AUTOLOGIN (0), and
SMTP_HOST/SMTP_PORT/SMTP_USER/SMTP_PASS/SMTP_SECURE instead of SMTP_URL.
ADMIN_PASSWORD is only for the web /admin page, not the container's root account. To log in at the Proxmox
console, set ROOT_PASSWORD, or set CONSOLE_AUTOLOGIN=1 to have the console log in as root with no password.
Anyone who can open the container's console in Proxmox then gets root in it; SSH still can't log in as root without a
key. Without either, get a shell with pct enter <ctid> on the host. The console's login screen
shows the container's address and the /admin 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.