Home / Home Lab / Proxmox

Install Immich on Proxmox 9.2 with Debian 13

Posted by Junnius Post a Comment



This guide shows a simple and clean way to run Immich on Proxmox 9.2 using a Debian 13 VM and the official Docker Compose deployment.

A full VM keeps Docker isolated from the Proxmox host and avoids the nesting, permission, and device-mapping complexity that can come with Docker inside LXC.

Recommended setup:

  • Proxmox VE 9.2
  • Debian 13 VM
  • 2 vCPU
  • 6 GB RAM
  • 32 GB OS disk on SSD
  • Temporary local storage for photos and videos
  • VirtIO network
  • Docker Engine
  • Docker Compose plugin


1. Create the Debian 13 VM

In this case, I will create a Debian 13 VM based on the template I've created in Proxmox using these settings:

  • CPU: 2 cores
  • CPU Type: host for a single-node homelab
  • Memory: 6 GB
  • OS Disk: 32 GB SCSI on SSD storage
  • Network: VirtIO
  • Bridge: vmbr0



Later I will use a separate disk or network storage for the media library, but for this initial test I will use the existing VM disk.

To keep the storage path consistent, I will use /mnt/immich-data as the Immich media location and bind-mount it from /home/debian/immich.

This makes it easier to move the media library to a dedicated disk or network share later without changing the Immich UPLOAD_LOCATION.

For long-term use, keeping the operating system and Immich library on separate storage is recommended because it makes storage expansion and backup management easier.


2. Update Debian and Install Basic Tools

Update Debian and install the QEMU Guest Agent, Parted, and basic utilities.

:::code sudo apt update sudo apt full-upgrade -y sudo apt install -y qemu-guest-agent parted ca-certificates curl wget nano sudo systemctl enable --now qemu-guest-agent :::

In Proxmox, also enable VM > Options > QEMU Guest Agent.


3. Prepare the Temporary Immich Data Storage

For this initial test, no additional virtual disk will be used.

Create a directory on the existing Debian filesystem that will temporarily store the Immich media library.

:::code sudo mkdir -p /home/debian/immich :::

Create the mount point that will be used by Immich.

:::code sudo mkdir -p /mnt/immich-data :::

Bind-mount the temporary storage directory to the Immich data mount point.

:::code sudo mount --bind /home/debian/immich /mnt/immich-data :::

Verify the mount.

:::code findmnt /mnt/immich-data df -h /mnt/immich-data :::

To make the bind mount persistent after reboot, edit /etc/fstab.

:::code sudo nano /etc/fstab :::

Add the following line:

:::code /home/debian/immich /mnt/immich-data none bind 0 0 :::

Test the configuration.

:::code sudo mount -a findmnt /mnt/immich-data :::

Note: /home/debian/immich and /mnt/immich-data currently use the same VM OS disk. The bind mount does not provide additional storage capacity or storage isolation.

The purpose of this layout is to keep /mnt/immich-data as the permanent storage path used by Immich. Later, when dedicated storage becomes available, the bind mount can be replaced with a separate disk, NFS share, or other supported storage mounted directly at /mnt/immich-data.


4. Install Docker Engine

Add Docker's official repository key.

:::code sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc :::

Load the Debian release information and add Docker's official repository.

:::code . /etc/os-release echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $VERSION_CODENAME stable" | sudo tee /etc/apt/sources.list.d/docker.list :::

Update APT and install Docker Engine with the Docker Compose plugin.

:::code sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin :::

Verify the installation.

:::code sudo docker --version sudo docker compose version :::



5. Download Immich

Create a dedicated directory for the Immich configuration.

:::code sudo mkdir -p /opt/immich sudo chown $USER:$USER /opt/immich cd /opt/immich :::

Download the Docker Compose file and example environment file from the latest Immich release.

:::code wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env :::


6. Configure Immich

Generate a strong alphanumeric PostgreSQL password.

:::code openssl rand -hex 24 :::

Copy the generated password, then edit the Immich environment file.

:::code nano /opt/immich/.env :::

Change these values:

:::code UPLOAD_LOCATION=/mnt/immich-data DB_DATA_LOCATION=/opt/immich/postgres TZ=Asia/Makassar DB_PASSWORD=PASTE_GENERATED_PASSWORD_HERE :::

Keep the remaining values from the official .env file unchanged unless you have a specific reason to modify them.

This temporary testing layout keeps:

  • Photos and videos: /mnt/immich-data, currently bind-mounted from /home/debian/immich
  • PostgreSQL database: /opt/immich/postgres

Both locations currently reside on the VM's local OS disk. This is acceptable for initial testing, but a dedicated disk or network storage should be considered later for a larger media library.

Keep the PostgreSQL database on local SSD-backed storage. Do not put DB_DATA_LOCATION on SMB, NFS, or other network storage.




7. Start Immich

Start the Immich containers.

:::code cd /opt/immich sudo docker compose up -d :::



Check the container status.

:::code sudo docker compose ps :::

Find the Debian VM IP address.

:::code hostname -I :::

Open Immich from another computer on your network:

http://VM-IP:2283

Example:

http://192.168.8.250:2283

Create your first account from the Immich web interface. The first registered account becomes the administrator.







Enable the Storage Template Engine. This allows Immich to organize uploaded photos and videos into a cleaner, human-readable folder structure instead of relying only on UUID-based filenames and paths. It also makes the media library easier to browse, migrate, and manage directly from the filesystem or NAS later.




Once complete the initial setup, I uploaded some photos and videos from my past trip. I also tried to make an album.


After uploading photos, the active job can be seen by click profile picture > Administration > Job Queues



8. Update and Back Up Immich

Update Immich

Pull the latest container images.

:::code cd /opt/immich sudo docker compose pull :::

Recreate the containers using the updated images.

:::code sudo docker compose up -d :::

Verify that all services are running.

:::code sudo docker compose ps :::


Back Up Immich

Your backup should protect both:

  • The Immich library under /mnt/immich-data, currently stored in /home/debian/immich
  • The Immich PostgreSQL database

Immich database backups do not replace backups of the actual photos and videos.

For this temporary testing setup, both the media library and PostgreSQL database reside on the same VM disk. A Proxmox VM backup can therefore protect the complete testing environment.

For long-term use, keeping another copy of the photo library on separate storage is recommended. When dedicated storage becomes available, it can later be mounted directly at /mnt/immich-data.


Why Use a VM Instead of LXC?

Running Docker inside LXC can work, but it adds another containerization layer and may require nesting, additional permissions, or device configuration.

For a homelab, a small Debian VM provides a clean separation between Proxmox and Docker while remaining easy to back up, migrate, troubleshoot, and upgrade.

Security Notes

  • Do not expose TCP port 2283 directly to the Internet.
  • Use a reverse proxy with HTTPS, VPN, or another secure access method for remote access.
  • Keep Debian, Docker, and Immich updated.
  • Keep independent backups of your original photos and videos.
  • Do not store the PostgreSQL database on network storage.


Conclusion

A Debian 13 VM with Docker Compose is a simple and maintainable way to run Immich on Proxmox 9.2.

Workflow: Create VM → Prepare Storage → Install Docker → Deploy Immich → Back Up


Quick Code Summary

Here are the essential commands in one place for quick reference.

:::code # Update Debian and install required tools sudo apt update sudo apt full-upgrade -y sudo apt install -y qemu-guest-agent parted ca-certificates curl wget nano sudo systemctl enable --now qemu-guest-agent # Create the temporary Immich data directory sudo mkdir -p /home/debian/immich # Create the Immich data mount point sudo mkdir -p /mnt/immich-data # Bind-mount the temporary directory sudo mount --bind /home/debian/immich /mnt/immich-data # Verify the bind mount findmnt /mnt/immich-data df -h /mnt/immich-data # Make the bind mount persistent sudo nano /etc/fstab # Add this line to /etc/fstab /home/debian/immich /mnt/immich-data none bind 0 0 # Test the persistent mount configuration sudo mount -a findmnt /mnt/immich-data # Add Docker's official signing key sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add Docker's official Debian repository . /etc/os-release echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $VERSION_CODENAME stable" | sudo tee /etc/apt/sources.list.d/docker.list # Install Docker Engine and Docker Compose sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # Create the Immich application directory sudo mkdir -p /opt/immich sudo chown $USER:$USER /opt/immich cd /opt/immich # Download the official Immich Compose files wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env # Generate the PostgreSQL password openssl rand -hex 24 # Configure storage paths, timezone, and database password nano /opt/immich/.env # Start Immich cd /opt/immich sudo docker compose up -d # Verify Immich services sudo docker compose ps # Show the VM IP address hostname -I :::


:::toc enable

Post a Comment for "Install Immich on Proxmox 9.2 with Debian 13"

Post a Comment