{"id":15168346,"url":"https://github.com/loeeeee/immich-in-lxc","last_synced_at":"2025-10-01T00:32:00.712Z","repository":{"id":238880211,"uuid":"797765864","full_name":"loeeeee/immich-in-lxc","owner":"loeeeee","description":"Install Immich in LXC with optional CUDA support","archived":false,"fork":false,"pushed_at":"2024-10-29T14:17:22.000Z","size":184,"stargazers_count":54,"open_issues_count":4,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T16:12:26.624Z","etag":null,"topics":["bare-metal","cuda","guide","immich","install-script","lxc","machine-learning","proxmox-ve","ubuntu"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loeeeee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-08T13:26:08.000Z","updated_at":"2024-10-27T22:37:32.000Z","dependencies_parsed_at":"2024-09-15T07:38:31.336Z","dependency_job_id":"302f8491-54c4-4506-b8da-68e69d332a6b","html_url":"https://github.com/loeeeee/immich-in-lxc","commit_stats":null,"previous_names":["loeeeee/immich-in-lxc"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loeeeee%2Fimmich-in-lxc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loeeeee%2Fimmich-in-lxc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loeeeee%2Fimmich-in-lxc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loeeeee%2Fimmich-in-lxc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loeeeee","download_url":"https://codeload.github.com/loeeeee/immich-in-lxc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234803453,"owners_count":18889257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","cuda","guide","immich","install-script","lxc","machine-learning","proxmox-ve","ubuntu"],"created_at":"2024-09-27T06:01:45.252Z","updated_at":"2025-10-01T00:32:00.706Z","avatar_url":"https://github.com/loeeeee.png","language":"Shell","funding_links":[],"categories":["Shell","machine-learning"],"sub_categories":[],"readme":"# Immich with CUDA/ROCm Support in LXC (w/o Docker)\n\nA complete guide for installing Immich in LXC, VM, or bare-metal without Docker, but with \n\n- **CUDA/ROCm support for machine-learning** (if one choose so), \n- **hardware acceleration for transcoding**,\n- **HEIF, RAW, and JXL support**,\n- Experimental Intel iGPU/dGPU/NPU support for machine-learning (if one choose so), \n- easy and fast upgrade, and\n- accessible proxy settings for PyPi and NPM registry.\n\n## Introduction\n\n[Immich](https://github.com/immich-app/immich) is a\n\n\u003e High performance self-hosted photo and video management solution\n\nI really like Immich and its coherent experience across both mobile and web. However, the official Documents only provides Docker installation guide, which is less than ideal for a LXC user. But, in fairness to Immich, not providing a bare-metal installation guide can be justified, as it is more than a simple binary and does require some efforts to set up in current state.\n\n**This guide is heavily inspired by another guide [Immich Native](https://github.com/arter97/immich-native), and the install script \u0026 service files are modified from the ones in that repo. KUDO to its author, arter97!** \n\nCompared to Immich Native, this repo additionally offers the support for CUDA-accelerated machine learning and (out-of-box) support for processing HEIF, i.e. common smart phone image format, and RAW, i.e. common fancy big camera image format, images.\n\n### Why hardware acceleration?\n\n\u003e I paid for the whole Speedometer, I'm gonna use the whole Speedometer.\n\u003e\n\u003e -- Abraham Lincoln\n\nJokes aside, hardware acceleration really helps during importing library containing many videos, or live photos (essentially a photo and video bundle), or when one would like to switch to or test out a bigger and better machine learning model to improve smart search or face search functionality, which requires a redo of the entire indexing process. However, during current stage and foreseeable future, the heavy work of generating thumbnails will remain on using SIMD commands on CPU, and cannot be accelerated by GPU.\n\nLastly, by using this repo, one could reliably set up a hardware-accelerated Immich instance without much hassle. So why not.\n\n## Immich Components\n\n\n\u003cdetails\u003e\n\u003csummary\u003eNot so important\u003c/summary\u003e\n\n- Immich\n    - Web Server\n    - Machine Learning Server\n- Database\n    - Redis\n    - Postgresql\n        - VectorChord\n- System\n    - Jellyfin-ffmpeg\n    - Node.js\n    - git\n- (Optional) Reverse Proxy\n    - Nginx\n- (Optional) NVIDIA\n    - Driver (i.e. CUDA Runtime)\n    - CuDNN (Version 9)\n- (Optional) AMD\n    - ROCm driver (6.4.1)\n\nAs one could tell, it is a lot of works, and a lot of things to get right. However, Immich is quite resilience and will fall-back to a baseline default when hardware acceleration does not work.\n\nFor the simplicity of the guide, all the components are installed in a single LXC container. However, it is always possible to run different components in different LXC containers. As it is always a design choice.\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n## Host setup\n\n\u003cdetails\u003e\n\u003csummary\u003eNot so important\u003c/summary\u003e\n\nI am using `Proxmox VE 8` as the LXC host, which is based on `Debian 12`, and I have a NVIDIA GPU, with a proprietary driver (550) installed. Some others are using a N100 mini PC box with Intel Quick Sync. And all of these do not matter.\n\nHowever, if possible, use an LXC or VM with `Ubuntu 24.04 LTS` as it offers an easier set-up.\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n## Prepare the LXC container, or whatever\n\nFirst, create a LXC/VM normally. Make sure there is reasonable amount CPU and memory, because we are going to install and compile a lot of things, and it would not hurt to give it a bit more. For a CPU-only Immich server, there should be at least 8 GiB of storage, and one with nVidia GPU, at least 16 GiB storage needs to be available. However, once one starts using Immich, it will create a lot of cache (for thumbnails and low-res transcoded videos), so don't forget to resize the LXC volumes accordingly. \n\nAlso, there is no need for a privileged container (which is not recommended in almost all scenarios), if one does not plan to mount a file system, e.g., NFS, SMB, etc., directly inside the LXC container.\n\nThis tutorial is tested on `Ubuntu 24.04 LTS` and `Debian 12` LXCs. Things will differ slightly in different distributions, though. Additionally, if one wants to have HW-accelerated ML, it is not recommend to use older release of `Ubuntu`, as it has older version of dependency in its repository, introducing additional complexity, like package pinning.\n\n## Hardware-accelerated machine learning\n\n\u003cdetails\u003e\n\u003csummary\u003eNvidia\u003c/summary\u003e\n\nFirstly, prepare a LXC with GPU available by following the guide at [another repository](https://github.com/loeeeee/loe-handbook-of-gpu-in-lxc/blob/main/src/gpu-passthrough.md) of mine. This process is referred to as NVIDIA GPU pass-through in LXC.\n\nAfter finishing all of the steps in that guide, the guest OS should execute command `nvidia-smi` without any error.\n\nThe major component that Immch requires is [ONNX runtime](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html#requirementsto), and here we are installing its dependency.\n\n\u003cdetails\u003e\n\u003csummary\u003eUbuntu 24.04\u003c/summary\u003e\n\nFor Immich machine learning support in `Ubuntu`, we need to install CuDNN and CUDA Toolkit. The default cuDNN version in apt is version 8, which is no longer supported by ONNX Runtime. Thus, we need to install the latest version 9.\n\nThe CuDNN install commands are from [official website of NVIDIA](https://developer.nvidia.com/cudnn-downloads), and should all be run as root. Also, one should check the NVIDIA website for updates.\n\n```bash\nwget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb\ndpkg -i cuda-keyring_1.1-1_all.deb\napt-get update\n\napt-get -y install cudnn-cuda-12\n```\n\nIn addition to the cuDNN, we also need libcublas12 things.\n\n```bash\napt install -y libcublaslt12 libcublas12 libcurand10\n```\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDebian 12\u003c/summary\u003e\n\nFor Immich machine learning support in `Debian`, we need to install CuDNN and CUDA Toolkit.\n\nWe install the entire CUDA Toolkit because install `libcublas` depends on CUDA Toolkit, and when install the toolkit, this right version of this component will be included.\n\nThe CuDNN install commands are from [official website of NVIDIA](https://developer.nvidia.com/cudnn-downloads), and should all be run as root. Also, one should check the NVIDIA website for updates.\n\n```bash\n# CuDNN part\nwget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb\ndpkg -i cuda-keyring_1.1-1_all.deb\nadd-apt-repository contrib\napt-get update\napt-get -y install cudnn\n## Specified by NVIDIA, but does not seem to install anything\napt-get -y install cudnn-cuda-12\n\n# CUDA Toolkit part\napt install -y cuda-toolkit\n```\n\n\u003cbr\u003e\n\u003c/details\u003e\n\nZu easy, innit?\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eIntel/OpenVINO\u003c/summary\u003e\n\nThis part is intended for users who would like to utilize Intel's OpenVINO execution provider. ([System requirement](https://docs.openvino.ai/2024/about-openvino/release-notes-openvino/system-requirements.html), [List of supported devices](https://docs.openvino.ai/2024/about-openvino/compatibility-and-support/supported-devices.html)) The document listed the support for not only Intel iGPU and dGPU, but also its NPU, which seems very cool.\n\nDisclaimer: This part is not yet tested by the repo owner, and it is composed based on documentation. However, success have been reported ([Issue #58](https://github.com/loeeeee/immich-in-lxc/issues/58)), even though one could not see the background tasks ([Issue #62](https://github.com/loeeeee/immich-in-lxc/issues/62)). \n\n\u003cdetails\u003e\n\u003csummary\u003eMoe\u003c/summary\u003e\nFirstly, prepare a LXC with proper hardware available. For iGPU user, one could use `intel_gpu_top` to see its availability.\n\nThen, install the dependency specified by Immich for Intel.\n\n```bash\n./dep-intel.sh\n```\n\nFinally, after first-time execution of the `install.sh`, which happens at later part of the guide (so safe to skip for now), modify the generated `.env` file.\n\n```env\nisCUDA=openvino\n```\n\nI know, this is ugly as hell, but whatever, it works.\n\nNow, when installing Immich, it will be using OpenVINO as its ML backend.\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eOthers\u003c/summary\u003e\n\nSince Immich depends on ONNX runtime, it is **possible** that other hardware that is not officially supported by Immich can be used to do machine learning tasks. The idea here is that installing the dependency for the hardware following [ONNX's instruction](https://onnxruntime.ai/docs/execution-providers/#summary-of-supported-execution-providers). \n\nSome users have also reported successful results using GPU Transcoding in Immich by following the Proxmox configurations from this video: [iGPU Transcoding In Proxmox with Jellyfin Media Center](https://www.youtube.com/watch?v=XAa_qpNmzZs) - Just avoid all the Jellyfin stuff and do the configurations on the Immich container instead. At the end, you should be able to use your iGPU Transcoding in Immich by going to needs to go to `Administration \u003e Settings \u003e Video Transcoding Settings \u003e Hardware Acceleration \u003e Acceleration API` and select `Quick Sync` to explicitly use the GPU to do the transcoding.\n\nGood luck and have fun!\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\n## Immich Installation\n\n### User creation\n\nFirst of all, create a Immich user, if you already done so in the above optional section, you may safely skip the following code block. The user created here will run Immich server.\n\n```bash\nadduser --shell /bin/bash --disabled-password immich --comment \"Immich Mich\"\n# --shell changes the default shell the immich user is using. In this case it will use /bin/bash, instead of the default /bin/sh, which lacks many eye-candy\n# --disabled-password skips creating password, and (sort of) only allows using su to access the user. If you need to change the password of the user, use the command: passwd immich\n# --comment adds user contact info, not super useful but mandatory, probably thanks to Unix legacy.\napt install -y git\nusermod -aG video,render immich\n```\n\n### Clone the repo\n\nI have make some helper script in this repo, so all one needs to do is clone the repo. We change to the user immich so that the files we cloned will have proper permission. And, just in case one does not know, the commands are as follow.\n\n```bash\nsu immich\ncd ~\ngit clone https://github.com/loeeeee/immich-in-lxc.git\n```\n\nAdditionally, it is recommend to have our working directory set to the repo's directory.\n\n```bash\ncd immich-in-lxc\n```\n\n### Install custom photo-processing library\n\nLikely because of license issue, many libraries included by distribution package managers do not support all the image format we want, e.g., HEIF, RAW, etc. Thus, we need compile these libraries from source. It can be painful to figure out how to do this, but luckily, I have already sorted out for you.\n\n#### Install compile tools and compile 始める\n\n\nNow `exit` the immich user, as the upcoming commands should be run as `root` user.\n\n```bash\n./pre-install.sh\n```\n\nIt is just so satisfying to see the compiling log rolling down the terminal, ain't it? Look carefully at the log, though. There should not be any error. However, some warning about relink will pop up, which is normal.\n\n### Config PostgreSQL like a champ\n\n\nThe following steps apply to both `Debian 12` and `Ubuntu 24.04` instances.\n\nEnter PostgreSQL control interface\n\n```bash\n# As root\nsu postgres\n# Now you are user:postgres\npsql\n```\n\nIn the psql interface, run:\n```SQL\nCREATE DATABASE immich;\nCREATE USER immich WITH ENCRYPTED PASSWORD 'A_SEHR_SAFE_PASSWORD';\nGRANT ALL PRIVILEGES ON DATABASE immich to immich;\nALTER USER immich WITH SUPERUSER;\n\\q\n```\n\nNote: change password, seriously.\n\nNote: To change back to the pre-su user, `exit` should do the trick.\n\n#### Database Migration for Existing Users (v1.133.0+)\n\n**Note:** Starting with Immich v1.133.0, the project has migrated from pgvecto.rs to [VectorChord](https://github.com/tensorchord/VectorChord) for better performance and stability.\n\nIf you're upgrading from a version prior to v1.133.0 and have an existing Immich installation, you may need to perform a database migration. The migration from pgvecto.rs to VectorChord is automatic, but you should:\n\n1. **Backup your database** before upgrading\n2. Ensure you're upgrading from at least v1.107.2 or later\n\n**Note:** If you have an existing `$INSTALL_DIR/runtime.env` (e.g. /home/immich/runtime.env) file with `DB_VECTOR_EXTENSION=pgvector`, you should update it to `DB_VECTOR_EXTENSION=vectorchord` for the new VectorChord extension.\n\nFor more details on the VectorChord migration, see the [official Immich v1.133.0 release notes](https://github.com/immich-app/immich/releases/tag/v1.133.0).\n\n### Install Immich Server\n\nThe star of the show is the install script, i.e. `install.sh` in this repo. It installs or updates the current Immich instance. The Immich instance itself is stateless, thanks to its design. Thus, it is safe to delete the `app` folder that will resides inside `INSTALL_DIR` folder that we are about to config. \n\nNote: **DO NOT DELETE UPLOAD FOLDER SPECIFIED BY `INSTALL_DIR` IN `.env`**. It stores all the user-uploaded content. \n\nAlso note: One should always do a snapshot of the media folder during the updating or installation process, just in case something goes horribly wrong.\n\n#### The environment variables\n\nAn example .env file that will be generated when no `.env` file is found inside current working directory when executing the script.\n\nLet us go ahead and execute the script as `immich` user (or the user that will be running immich). No worry, when `.env` file is not found, the script will gracefully exit and will not change to the file system.\n\n```bash\nsu immich # Or the user who is going to run immich. It should be the same user as the one used for installing Node.js.\n./install.sh\n```\n\nThen, we should have a `.env` file in current directory. \n\n- `REPO_TAG` is the version of the Immich that we are going to install,\n- `INSTALL_DIR` is where the `app` and `source` folders will resides in (e.g., it can be a `mnt` point),\n- `UPLOAD_DIR` is where the user uploads goes to  (it can be a `mnt` point), \n- `isCUDA` when set to true, will install Immich with CUDA supprt. For other GPU Transcodings, this is likely to remain false. (available flag: true, false, openvino, rocm)\n- For user with compromised network accessibility:\n    - `PROXY_NPM` sets the mirror URL that npm will use, if empty, it will use the official one,\n    - :new:`PROXY_NPM_DIST` sets the dist URL that node-gyp will use, if empty, it will use the official one, and\n    - `PROXY_POETRY` sets the mirror URL that poetry will use, if empty, it will use the official one.\n\nNote: The `immich` user should have read and write access to both `INSTALL_DIR` and `UPLOAD_DIR`.\n\nNote: :new: means user might need to create the empty entry to make script run.\n\n#### Run the script\n\nAfter the `.env` is properly configured, we are now ready to do the actual installation.\n\n```bash\n./install.sh\n```\n\nNote, `install.sh` should be executed as user `immich`, or the user who is going to run immich.\n\nIt should go without errors, just like ever dev says.\n\nAfter several minutes, ideally, it would say,\n\n```bash\nDone. Please install the systemd services to start using Immich.\n```\n\nLastly, we need to review and modify the `runtime.env` that is inside your specified `INSTALL_DIR` (not the runtime.env inside this repo). The default values could also work, unless you changed the `DB_PASSWORD` when installing Postgres. \n\n**Note:** If your `DB_PASSWORD` contains special characters (such as `$`, `!`, etc.), you must wrap the value in single quotes, e.g., `DB_PASSWORD='your$pec!alP@ss'`. This prevents shell expansion issues when the environment file is sourced. (See [issue #95](https://github.com/loeeeee/immich-in-lxc/issues/95) for details.)\n\nFor Timezones `TZ`, you can consult them in the [TZ Database Wiki](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).\n\n#### Post install script\n\nThe post install script will copy the systemd service files to proper location (and overwrite the original ones), assuming one is using Ubuntu, or something similar. Additionally, it creates a folder for log at `/var/log/`. Both operation requires `sudo/root` privilege, so make sure to review the script before proceeding.\n\n```bash\n./post-install.sh\n```\n\nThen, modify the `service` files to make sure every path name is spelled correctly. You might need to modify the variables `WorkingDirectory`, `EnvironmentFile`, `ExecStart` with the `INSTALL_DIR` specified in the `.env` file (in case you didn't leave the default INSTALL_DIR).\n\n```bash\nnano /etc/systemd/system/immich-ml.service # Modify WorkingDirectory, EnvironmentFile, and ExecStart with your INSTALL_DIR, in case you changed it.\n```\n```bash\nnano /etc/systemd/system/immich-web.service # Modify ExecStart with your INSTALL_DIR, in case you changed it.\n```\n\nAfter that, we are ready to start our Immich instance!\n\n```bash\nsystemctl daemon-reload \u0026\u0026 \\\nsystemctl start immich-ml \u0026\u0026 \\\nsystemctl start immich-web\n```\n\nThe default setting exposes the Immich web server on port `2283` on all available address. For security reason, one should put a reverse proxy, e.g. Nginx, HAProxy, in front of the immich instance and add SSL to it.\n\nTo make the service persistent and start after reboot,\n\n```bash\nsystemctl enable immich-ml \u0026\u0026 \\\nsystemctl enable immich-web\n```\n\n#### Immich config\n\nBecause we are install Immich instance in a none docker environment, some DNS lookup will not work. For instance, we need to change the URL inside `Administration \u003e Settings \u003e Machine Learning Settings \u003e URL` to `http://localhost:3003`, otherwise the web server cannot communicate with the ML backend.\n\nAdditionally, for LXC with CUDA or other GPU Transcoding support enabled, one needs to go to `Administration \u003e Settings \u003e Video Transcoding Settings \u003e Hardware Acceleration \u003e Acceleration API` and select your GPU Transcoding (e.g., `NVENC` - for CUDA) to explicitly use the GPU to do the transcoding.\n\n## Update the Immich instance\n\nThe Immich server instance is designed to be stateless, meaning that deleting the instance, i.e. the `INSTALL_DIR/app` folder, (NOT DATABASE OR OTHER STATEFUL THINGS) will not break anything. Thus, to upgrade the current Immich instance, all one needs to do is essentially install the latest Immich.\n\n- **v1.133.0+ Breaking Changes:** If upgrading to v1.133.0 or later, ensure you're upgrading from at least v1.107.2 or later. If you're on an older version, upgrade to v1.107.2 first and ensure Immich starts successfully before continuing.\n\nFirst thing to do is to stop the old instance.\n\n```bash\nsystemctl stop immich-ml \u0026\u0026 \\\nsystemctl stop immich-web\n```\n\nAfter stopping the old instance, update this repo by doing a `git pull` in the folder `immich-in-lxc` (using the `immich` user). \n\nThen, the modify `REPO_TAG` value in `.env` file based on the one in `install.env`. \n\nFinally, run the `install.sh` and it will update Immich, hopefully without problems.\n\nAlso, don't forget to start the service again, to load the latest Immich instance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floeeeee%2Fimmich-in-lxc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floeeeee%2Fimmich-in-lxc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floeeeee%2Fimmich-in-lxc/lists"}