Add LXC packaging: release builder, systemd installer, and Proxmox container script

This commit is contained in:
zyphlar
2026-10-19 15:20:34 -07:00
parent f598200e24
commit df48ae7f6f
7 changed files with 426 additions and 0 deletions
+90
View File
@@ -0,0 +1,90 @@
# 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)
```sh
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:
```sh
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:
```sh
./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:
```sh
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:
```sh
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:
```sh
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.