diff --git a/.dockerignore b/.dockerignore index f549885..397cef4 100644 --- a/.dockerignore +++ b/.dockerignore @@ -11,3 +11,4 @@ /upload-app/.env /data/ /app/data/ +/dist-release/ diff --git a/.gitignore b/.gitignore index 3bf3cb0..3117968 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ app/public/js/ upload-app/public/js/ /data/ /app/data/ +/dist-release/ diff --git a/README.md b/README.md index bb98bd4..0be29f4 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ A fork of [Immich Public Proxy](https://github.com/alangrainger/immich-public-pr ## Setup +To run it in an LXC container (Proxmox, Incus, LXD) instead of Docker, see [`lxc/README.md`](lxc/README.md). + 1. Set the environment (see `docker-compose.yml`) and start it with `docker compose up -d --build`. Mount a volume at `/data`: it holds the SQLite database of recipients, sessions and comments. Back it up. 2. Open `/admin` and sign in with `ADMIN_PASSWORD`. diff --git a/lxc/README.md b/lxc/README.md new file mode 100644 index 0000000..96607f4 --- /dev/null +++ b/lxc/README.md @@ -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--.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 ' \ +./proxmox-create.sh immich-magic-proxy-.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-.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 immich-magic-proxy-.tar.gz /root/release.tar.gz +pct push install.sh /root/install.sh --perms 0755 +pct exec -- /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/ /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. diff --git a/lxc/build-release.sh b/lxc/build-release.sh new file mode 100755 index 0000000..93ff442 --- /dev/null +++ b/lxc/build-release.sh @@ -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-.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" diff --git a/lxc/install.sh b/lxc/install.sh new file mode 100755 index 0000000..6f9d9fc --- /dev/null +++ b/lxc/install.sh @@ -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-.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 " +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 " +#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 </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 diff --git a/lxc/proxmox-create.sh b/lxc/proxmox-create.sh new file mode 100755 index 0000000..665d2aa --- /dev/null +++ b/lxc/proxmox-create.sh @@ -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-.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 " +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 < /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