Native Immich Installation Guide

This guide provides instructions and helper scripts to install Immich natively (without Docker) on a Proxmox LXC container. It’s an updated version of Immich Native adapted for a setup that uses:

• Proxmox and LXC containers
• An NVIDIA GeForce 1080ti for GPU transcoding and machine learning
• Custom builds for libvips and sharp to support HEIC/HEIF thumbnails
• Uses specific timezone

Note: Officially, Immich can be installed via Docker, but this guide avoids excessive virtualization. The official documentation from Immich is valid, the env variables should be places in the env file, as they will be picked up ar run time.

Warning ⚠

This guide is specifically tailored for a setup using Proxmox and LXC containers running Debian 12 with NVIDIA GeForce 1080ti. Please ensure compatibility with your system before proceeding.

Table of Contents

• Native Immich Installation Guide
  • Warning ⚠
  • Table of Contents
  • Prerequisites
  • Preparing the LXC Container
    • NFS Setup
    • NVIDIA GPU Setup
  • Installing Required Software
    • Node.js
    • PostgreSQL
    • Redis
    • FFMPEG (Jellyfin version)
    • ImageMagick
    • libheif
    • libvips
  • Cloning and Setting Up Immich Native
    • Environment Preparation
    • Database Setup
    • Immich Installation & Configuration
  • Using the Custom install.sh Script
  • Installation Completion & Verification
  • Uninstallation Instructions
  • Acknowledgements

---

Prerequisites

• Proxmox with LXC containers
• An NVIDIA GPU (GeForce 1080ti recommended)
• Basic Linux command-line knowledge

---

Preparing the LXC Container

NFS Setup

1. Install NFS common:

   sudo apt install nfs-common -y

2. Update /etc/fstab to enable auto-mount of your storage.

NVIDIA GPU Setup

1. Install the NVIDIA driver (without the kernel module):

   ./NVIDIA-Linux-x86_64-550.120.run --no-kernel-module

2. Install CUDA:

   wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb
   sudo dpkg -i cuda-keyring_1.1-1_all.deb
   sudo add-apt-repository contrib
   sudo apt update
   nano /etc/apt/sources.list.d/cuda.list
      # add if not there
      # deb https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/ /
   sudo apt update
   sudo apt -y install cuda-toolkit-12-4
   echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   nvcc --version

---

Installing Required Software

Node.js

1. Setup Node.js LTS:

   curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
   sudo -E bash nodesource_setup.sh
   sudo apt update
   sudo apt install nodejs -y
   node -v # Expect something like v22.14.0
   npm -v # Expect something like 10.9.2

PostgreSQL

1. Install PostgreSQL and required packages:

   sudo apt install -y curl ca-certificates gnupg lsb-release
   curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /usr/share/keyrings/postgresql-keyring.gpg
   echo "deb [signed-by=/usr/share/keyrings/postgresql-keyring.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
   sudo apt update
   sudo apt install -y postgresql-17 postgresql-17-pgvector
   sudo systemctl enable postgresql
   sudo systemctl start postgresql

Redis

1. Install and verify Redis:

   sudo apt install -y redis-server
   sudo systemctl enable redis-server
   sudo systemctl start redis-server
   redis-cli ping # Should return "PONG"

FFMPEG (Jellyfin version)

1. Install Jellyfin ffmpeg:

   sudo apt install -y curl gnupg apt-transport-https
   sudo mkdir -p /etc/apt/keyrings
   curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
   echo "deb [signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/debian bookworm main" | sudo tee /etc/apt/sources.list.d/jellyfin.list
   sudo apt update
   sudo apt install -y jellyfin-ffmpeg7
   sudo ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg
   sudo ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe
   ffmpeg -version # Check for "Jellyfin" in the version output

ImageMagick

1. Install ImageMagick development libraries:

   sudo apt install -y imagemagick libmagickcore-dev libmagickwand-dev

libheif

cd ~
wget https://github.com/strukturag/libheif/releases/download/v1.19.5/libheif-1.19.5.tar.gz
tar -xzf libheif-1.19.5.tar.gz
cd libheif-1.19.5
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install
sudo ldconfig

libvips

1. Install Requirements:

   sudo apt update
   sudo apt install -y git cmake meson ninja-build build-essential pkg-config \
   libglib2.0-dev libjpeg-dev libpng-dev libtiff-dev libexif-dev libxml2-dev liborc-0.4-dev \
   libaom-dev libarchive-dev libcairo2-dev libcgif-dev libexpat1-dev libffi-dev libfontconfig1-dev libfreetype-dev \
   libfribidi-dev libharfbuzz-dev libimagequant-dev liblcms2-dev libpango1.0-dev libpixman-1-dev \
   librsvg2-dev libspng-dev libwebp-dev zlib1g-dev libcgif-dev libcfitsio-dev libopenslide-dev libmatio-dev \
   libpoppler-glib-dev

2. Compile nifti_clib:

   cd ~
   git clone https://github.com/neurolabusc/nifti_clib.git
   cd nifti_clib
   mkdir build && cd build
   cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
   make -j$(nproc)
   sudo make install

3. Compile libvips:

   cd ~
   git clone https://github.com/libvips/libvips.git
   cd libvips
   sudo meson setup build --prefix=/usr --buildtype=release \
   -Dopenjpeg=enabled -Dimagequant=enabled -Dheif=enabled -Dpoppler=enabled \
   -Drsvg=enabled -Dopenexr=enabled -Dopenslide=enabled -Dmatio=enabled \
   -Dnifti=enabled -Dcfitsio=enabled -Dcgif=enabled -Dmagick=enabled -Dmodules=enabled
   ninja -C build
   sudo ninja -C build install
   sudo ldconfig

4. Verify Installation:

   vips --version
   pkg-config --modversion vips

---

Cloning and Setting Up Immich Native

Environment Preparation

1. Clone the Repository:

cd ~
git clone https://github.com/arter97/immich-native
cd immich-native

2. Add Immich User:

sudo adduser --home /var/lib/immich/home --shell=/sbin/nologin --no-create-home --disabled-password --disabled-login immich
sudo mkdir -p /var/lib/immich
sudo chown immich:immich /var/lib/immich
sudo chmod 700 /var/lib/immich

Database Setup

1. Create the Database and User:

   sudo -u postgres psql

   Then inside the PostgreSQL shell, run:

   create database immich;
   create user immich_user with encrypted password 'YOUR_STRONG_RANDOM_PW';
   grant all privileges on database immich to immich_user;
   ALTER USER immich_user WITH SUPERUSER;
   \c immich
   CREATE EXTENSION IF NOT EXISTS vector;
   \q

Immich Installation & Configuration

1. Install Additional Dependencies:

   sudo apt install --no-install-recommends -y \
     python3-venv python3-dev uuid-runtime autoconf build-essential unzip jq perl \
     libnet-ssleay-perl libio-socket-ssl-perl libcapture-tiny-perl libfile-which-perl \
     libfile-chdir-perl libpkgconfig-perl libffi-checklib-perl libtest-warnings-perl \
     libtest-fatal-perl libtest-needs-perl libtest2-suite-perl libsort-versions-perl \
     libpath-tiny-perl libtry-tiny-perl libterm-table-perl libany-uri-escape-perl \
     libmojolicious-perl libfile-slurper-perl liblcms2-2 wget

2. Define the Application Location: Choose /opt/immich as the installation directory:

   sudo mkdir /opt/immich

3. Prepare Required Media Directories: Immich expects specific folders (refer to Immich System Integrity). Create them as follows:

   for dir in encoded-video library upload profile thumbs backups; do
     sudo mkdir -p /media/photos/$dir
     sudo touch /media/photos/$dir/.immich
   done

4. Configure the Environment File: Update the env file with:

   • DB_USERNAME=immich_user
   • DB_PASSWORD=YOUR_STRONG_RANDOM_PW
   • IMMICH_HOST=0.0.0.0
   • UPLOAD_LOCATION=/media/photos
   • IMMICH_MEDIA_LOCATION=/media/photos

   Then copy it to the installation directory:

   sudo cp env /opt/immich/
   sudo chown immich:immich /opt/immich/env

---

Using the Custom install.sh Script

Your local install.sh script already includes all the necessary modifications compared to the original repository. These customizations are:

• Application Location: The script is set to use /opt/immich as the installation directory:

  IMMICH_PATH=/opt/immich 

• Install Sharp with Custom Options: Instead of the default command, the script installs Sharp using:

  npm install node-addon-api node-gyp
  SHARP_LIBVIPS_EXTERNAL=1 PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig npm install --build-from-scratch sharp 

• Network Binding: The section that forces binding to 127.0.0.1 is commented out, allowing Immich to listen on all interfaces.

• Error Handling: The script includes enhanced error handling that provides more detailed information about failures.

Simply run your custom script to proceed with the installation:

./install.sh 

Updating Immich

To update Immich to a newer version:

1. Modify the Version: Edit the install.sh script and change the REV variable to the desired version:

   # Change this line to the version you want
   REV=v1.127.0

2. Run the installation script: The script will handle the update process:

   ./install.sh

3. Verify the update: After the update is complete, verify that Immich is running with the new version:

   systemctl status immich

---

Installation Completion & Verification

After running the installation script:

• The Immich application should be available at http://localhost:2283.
• Immich will automatically start at system boot.
• You can now install the mobile app from your preferred app store to enjoy all its features.

---

Uninstallation Instructions

To uninstall Immich, follow these steps:

1. Remove Systemd Services:

   systemctl list-unit-files --type=service | grep "^immich" | while read i unused; do
     sudo systemctl stop $i
     sudo systemctl disable $i
   done
   
   sudo rm /lib/systemd/system/immich*.service
   sudo systemctl daemon-reload

2. Remove Immich Files:

   sudo rm -rf /opt/immich 

3. Delete Immich User:

   sudo deluser immich 

4. Remove the Immich Database:

   sudo -u postgres psql 

   Then run:

   drop database immich; 
   drop user immich_user; 
   \q 

5. Optionally Remove Dependencies: Review /var/log/apt/history.log to remove packages installed specifically for Immich.

---

Acknowledgements

Thanks to the original arter97/immich-native project for providing the base work. Contributions and improvements are welcome via pull requests.