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.
+38
View File
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
# Build a self-contained release tarball for lxc/install.sh, using the
# Dockerfile's builder stage (needs Docker or Podman on this machine, not in
# the container). Every production dependency is pure JavaScript, so the
# tarball runs on any architecture with Node 24.
#
# lxc/build-release.sh -> dist-release/immich-magic-proxy-<version>.tar.gz
set -euo pipefail
cd "$(dirname "$0")/.."
engine=$(command -v docker || command -v podman || true)
[ -n "$engine" ] || { echo "Docker or Podman is needed to build the release" >&2; exit 1; }
version=$(sed -n 's/^ "version": "\(.*\)",$/\1/p' app/package.json)
commit=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
name="immich-magic-proxy-$version-$commit"
out="dist-release"
image="immich-magic-proxy-builder:$commit"
echo "Building $name"
"$engine" build --target builder -t "$image" .
stage=$(mktemp -d)
trap 'rm -rf -- "$stage"; "$engine" rm -f "${container:-}" >/dev/null 2>&1 || true' EXIT
container=$("$engine" create "$image")
mkdir -p "$stage/$name"
"$engine" cp "$container:/ipp/app/dist" "$stage/$name/dist"
"$engine" cp "$container:/ipp/app/public" "$stage/$name/public"
"$engine" cp "$container:/ipp/app/config.json" "$stage/$name/config.json"
"$engine" cp "$container:/ipp/app/package.json" "$stage/$name/package.json"
"$engine" cp "$container:/ipp/prod_modules" "$stage/$name/node_modules"
rm -f "$stage/$name/dist/tsconfig.tsbuildinfo"
echo "$version-$commit" > "$stage/$name/VERSION"
mkdir -p "$out"
tar -C "$stage" -czf "$out/$name.tar.gz" "$name"
(cd "$out" && sha256sum "$name.tar.gz" > "$name.tar.gz.sha256")
echo "Wrote $out/$name.tar.gz"
Executable
+161
View File
@@ -0,0 +1,161 @@
#!/usr/bin/env bash
# Install or upgrade Immich Magic Proxy inside a Debian 13 (trixie) LXC
# container, as a systemd service. Run as root inside the container:
#
# ./install.sh immich-magic-proxy-<version>.tar.gz
#
# Re-running with a newer tarball upgrades in place. Settings in
# /etc/immich-magic-proxy and data in /var/lib/immich-magic-proxy are kept.
set -euo pipefail
APP=immich-magic-proxy
PREFIX=/opt/$APP
CONF_DIR=/etc/$APP
DATA_DIR=/var/lib/$APP
NODE_MAJOR=24
KEEP_RELEASES=3
die () { echo "error: $*" >&2; exit 1; }
log () { echo "==> $*"; }
[ "$(id -u)" -eq 0 ] || die "run as root"
[ $# -eq 1 ] && [ -f "$1" ] || die "usage: $0 <release tarball>"
tarball=$(readlink -f "$1")
[ -r /etc/debian_version ] || die "this installer is for Debian"
# ----- Node.js ---------------------------------------------------------------
# Debian's own nodejs is too old (node:sqlite needs 22.13+), so use NodeSource's
# signed apt repository, which also delivers Node security updates via apt.
node_major () { node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0; }
if [ "$(node_major)" -lt "$NODE_MAJOR" ]; then
log "Installing Node.js $NODE_MAJOR"
export DEBIAN_FRONTEND=noninteractive
apt-get update -q
apt-get install -y -q --no-install-recommends ca-certificates curl gpg
install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor --yes -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" \
> /etc/apt/sources.list.d/nodesource.list
apt-get update -q
apt-get install -y -q --no-install-recommends nodejs
fi
[ "$(node_major)" -ge "$NODE_MAJOR" ] || die "Node.js $NODE_MAJOR could not be installed"
# ----- user and directories --------------------------------------------------
if ! id "$APP" >/dev/null 2>&1; then
log "Creating system user $APP"
useradd --system --home-dir "$DATA_DIR" --no-create-home --shell /usr/sbin/nologin "$APP"
fi
install -d -m 0755 -o root -g root "$PREFIX" "$PREFIX/releases"
install -d -m 0750 -o root -g "$APP" "$CONF_DIR"
install -d -m 0750 -o "$APP" -g "$APP" "$DATA_DIR"
# ----- unpack the release ----------------------------------------------------
staging=$(mktemp -d)
trap 'rm -rf -- "$staging"' EXIT
tar -xzf "$tarball" -C "$staging"
release_dir=$(find "$staging" -mindepth 1 -maxdepth 1 -type d | head -n1)
[ -n "$release_dir" ] && [ -f "$release_dir/dist/index.js" ] || die "$1 is not a release tarball"
version=$(cat "$release_dir/VERSION")
target="$PREFIX/releases/$version"
log "Installing release $version"
if [ ! -d "$target" ]; then
# Code is root-owned, so the service account cannot modify it
chown -R root:root "$release_dir"
chmod -R u=rwX,go=rX "$release_dir"
mv "$release_dir" "$target"
fi
# Stamp with the install time (tar restores the build's), which pruning sorts by
touch "$target"
# ----- settings (kept across upgrades) --------------------------------------
if [ ! -f "$CONF_DIR/config.json" ]; then
install -m 0640 -o root -g "$APP" "$target/config.json" "$CONF_DIR/config.json"
fi
if [ ! -f "$CONF_DIR/env" ]; then
log "Writing $CONF_DIR/env - edit it before first use"
install -m 0600 -o root -g root /dev/null "$CONF_DIR/env"
cat > "$CONF_DIR/env" <<'EOF'
# Immich Magic Proxy settings. Restart after editing:
# systemctl restart immich-magic-proxy
# Put a value with spaces or symbols in double quotes, with a backslash
# before any \ " $ or ` inside it, e.g. ADMIN_PASSWORD="pa\$\$ word"
# Immich's internal URL, and this proxy's public URL (used in email links)
IMMICH_URL=http://immich.lan:2283
PUBLIC_BASE_URL=https://photos.example.com
# Turns on /admin, where you add albums and recipients
ADMIN_PASSWORD=
# Outgoing email for invitations and new-photo notifications
#SMTP_URL=smtp://user:password@smtp.example.com:587
#MAIL_FROM="Our photos <photos@example.com>"
#SITE_NAME="Our photos"
# Hour (0-23, in TZ) that notification emails go out
#DIGEST_HOUR=8
#TZ=Etc/UTC
#IPP_PORT=3000
EOF
fi
# Holds the admin and SMTP passwords. Only root reads it: systemd loads it
# before the service drops to its own user.
chown root:root "$CONF_DIR/env"
chmod 0600 "$CONF_DIR/env"
# ----- systemd service -------------------------------------------------------
cat > /etc/systemd/system/$APP.service <<EOF
[Unit]
Description=Immich Magic Proxy
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
User=$APP
Group=$APP
WorkingDirectory=$PREFIX/current
Environment=NODE_ENV=production
Environment=DATA_DIR=$DATA_DIR
Environment=IPP_CONFIG=$CONF_DIR/config.json
EnvironmentFile=$CONF_DIR/env
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=5
# Hardening. These need namespaces, which an LXC container has with nesting
# on (Proxmox's default for unprivileged containers).
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=$DATA_DIR
CapabilityBoundingSet=
RestrictSUIDSGID=yes
LockPersonality=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
UMask=0077
[Install]
WantedBy=multi-user.target
EOF
ln -sfn "$target" "$PREFIX/current"
systemctl daemon-reload
systemctl enable "$APP" >/dev/null 2>&1
if grep -q '^ADMIN_PASSWORD=.\+' "$CONF_DIR/env"; then
systemctl restart "$APP"
log "Started $APP $version"
else
log "Installed $APP $version, not started: set ADMIN_PASSWORD (and the rest) in $CONF_DIR/env, then run"
log " systemctl restart $APP"
fi
# ----- keep the newest few releases -----------------------------------------
current=$(readlink -f "$PREFIX/current")
find "$PREFIX/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' | sort -rn | tail -n +$((KEEP_RELEASES + 1)) |
while read -r _ old; do
[ "$old" = "$current" ] || rm -rf -- "$old"
done
+133
View File
@@ -0,0 +1,133 @@
#!/usr/bin/env bash
# Create an unprivileged Debian 13 LXC container on a Proxmox VE host and
# install Immich Magic Proxy in it. Run as root on the Proxmox host, with the
# release tarball and lxc/install.sh beside this script:
#
# IMMICH_URL=http://192.168.1.20:2283 PUBLIC_BASE_URL=https://photos.example.com \
# ADMIN_PASSWORD='long random string' ./proxmox-create.sh immich-magic-proxy-<version>.tar.gz
#
# Optional settings (environment variables, defaults in brackets):
# CTID [next free] CT_HOSTNAME [immich-magic-proxy] STORAGE [local-lvm]
# TEMPLATE_STORAGE [local] BRIDGE [vmbr0] IP [dhcp, or e.g. 192.168.1.50/24]
# GATEWAY [] VLAN [] CORES [1] MEMORY [512] DISK [4] PORT [3000]
# SMTP_URL MAIL_FROM SITE_NAME DIGEST_HOUR TZ [host's timezone]
set -euo pipefail
die () { echo "error: $*" >&2; exit 1; }
log () { echo "==> $*"; }
command -v pct >/dev/null || die "run this on a Proxmox VE host"
[ "$(id -u)" -eq 0 ] || die "run as root"
[ $# -eq 1 ] && [ -f "$1" ] || die "usage: $0 <release tarball>"
tarball=$(readlink -f "$1")
installer="$(dirname "$(readlink -f "$0")")/install.sh"
[ -f "$installer" ] || die "install.sh must be next to this script"
: "${IMMICH_URL:?set IMMICH_URL to the internal URL of Immich}"
: "${PUBLIC_BASE_URL:?set PUBLIC_BASE_URL to the public URL of this proxy}"
: "${ADMIN_PASSWORD:?set ADMIN_PASSWORD for the /admin console}"
CTID=${CTID:-$(pvesh get /cluster/nextid)}
# Not HOSTNAME: bash sets that to the Proxmox host's own name
CT_HOSTNAME=${CT_HOSTNAME:-immich-magic-proxy}
STORAGE=${STORAGE:-local-lvm}
TEMPLATE_STORAGE=${TEMPLATE_STORAGE:-local}
BRIDGE=${BRIDGE:-vmbr0}
IP=${IP:-dhcp}
CORES=${CORES:-1}
MEMORY=${MEMORY:-512}
DISK=${DISK:-4}
PORT=${PORT:-3000}
TZ=${TZ:-$(cat /etc/timezone 2>/dev/null || timedatectl show -p Timezone --value 2>/dev/null || echo Etc/UTC)}
net="name=eth0,bridge=$BRIDGE,ip=$IP"
[ -n "${GATEWAY:-}" ] && net="$net,gw=$GATEWAY"
[ -n "${VLAN:-}" ] && net="$net,tag=$VLAN"
# ----- Debian 13 template ----------------------------------------------------
log "Finding the Debian 13 template"
pveam update >/dev/null
template=$(pveam available --section system | awk '{print $2}' | grep -E '^debian-13-standard_.*_amd64\.tar\.(zst|xz|gz)$' | sort -V | tail -n1)
[ -n "$template" ] || die "no debian-13-standard template offered by pveam"
if ! pveam list "$TEMPLATE_STORAGE" | grep -q "$template"; then
log "Downloading $template"
pveam download "$TEMPLATE_STORAGE" "$template"
fi
# ----- container -------------------------------------------------------------
log "Creating container $CTID ($CT_HOSTNAME)"
pct create "$CTID" "$TEMPLATE_STORAGE:vztmpl/$template" \
--hostname "$CT_HOSTNAME" \
--unprivileged 1 \
--features nesting=1 \
--cores "$CORES" --memory "$MEMORY" --swap 512 \
--rootfs "$STORAGE:$DISK" \
--net0 "$net" \
--timezone "$TZ" \
--onboot 1 \
--description "Immich Magic Proxy: invite-only sharing for Immich"
pct start "$CTID"
log "Waiting for the network"
for _ in $(seq 1 60); do
pct exec "$CTID" -- sh -c 'getent hosts deb.debian.org >/dev/null' && break
sleep 2
done
pct exec "$CTID" -- sh -c 'getent hosts deb.debian.org >/dev/null' || die "container $CTID has no network or DNS"
log "Updating Debian"
pct exec "$CTID" -- sh -c 'DEBIAN_FRONTEND=noninteractive apt-get update -q && DEBIAN_FRONTEND=noninteractive apt-get -y -q dist-upgrade'
# ----- settings, then install ------------------------------------------------
# Double-quoted with \ " $ ` escaped: the form systemd's EnvironmentFile
# parser reads back exactly, so passwords keep any spaces, quotes or
# backslashes. (It does not support shell-style 'a'\''b' concatenation.)
env_line () {
local value=$2
value=${value//\\/\\\\}
value=${value//\"/\\\"}
value=${value//\$/\\\$}
value=${value//\`/\\\`}
printf '%s="%s"\n' "$1" "$value"
}
settings=$(mktemp)
trap 'rm -f -- "$settings"' EXIT
{
env_line IMMICH_URL "$IMMICH_URL"
env_line PUBLIC_BASE_URL "$PUBLIC_BASE_URL"
env_line ADMIN_PASSWORD "$ADMIN_PASSWORD"
for name in SMTP_URL SMTP_HOST SMTP_PORT SMTP_USER SMTP_PASS SMTP_SECURE MAIL_FROM SITE_NAME DIGEST_HOUR; do
if [ -n "${!name:-}" ]; then env_line "$name" "${!name}"; fi
done
env_line TZ "$TZ"
env_line IPP_PORT "$PORT"
} > "$settings"
pct exec "$CTID" -- install -d -m 0755 /root/imp-install
pct push "$CTID" "$tarball" /root/imp-install/release.tar.gz
pct push "$CTID" "$installer" /root/imp-install/install.sh --perms 0755
# The env file is written before install.sh runs, so it starts the service
pct exec "$CTID" -- install -d -m 0750 /etc/immich-magic-proxy
pct push "$CTID" "$settings" /etc/immich-magic-proxy/env --perms 0600
pct exec "$CTID" -- /root/imp-install/install.sh /root/imp-install/release.tar.gz
pct exec "$CTID" -- rm -rf /root/imp-install
log "Checking the service"
for _ in $(seq 1 30); do
pct exec "$CTID" -- curl -s -o /dev/null "http://127.0.0.1:$PORT/share/healthcheck" && break
sleep 1
done
pct exec "$CTID" -- systemctl --no-pager --lines=5 status immich-magic-proxy || true
address=$(pct exec "$CTID" -- hostname -I | awk '{print $1}')
cat <<EOF
Immich Magic Proxy is running in container $CTID at http://$address:$PORT
Next:
1. Point your reverse proxy for $PUBLIC_BASE_URL at http://$address:$PORT
2. Open $PUBLIC_BASE_URL/admin and sign in with ADMIN_PASSWORD
Settings: pct exec $CTID -- nano /etc/immich-magic-proxy/env (then: systemctl restart immich-magic-proxy)
Logs: pct exec $CTID -- journalctl -u immich-magic-proxy -f
Upgrade: pct push $CTID <new tarball> /root/release.tar.gz && pct push $CTID install.sh /root/install.sh --perms 0755 &&
pct exec $CTID -- /root/install.sh /root/release.tar.gz
EOF