User Tools

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
services:immich [2024/02/22 15:52] – [Installation] willyservices:immich [2025/03/13 14:41] (current) – [Installation] willy
Line 1: Line 1:
 ====== Immich ====== ====== Immich ======
  
-[[https://immich.app/|Immich]] is a modern photo management web application which aims to be similar to Google Photo. I use it to backup my phone photos and also manage my older collection of older photos of when i was using physical cameras. +[[https://immich.app/|Immich]] is a modern photo management web application which aims to be similar to Google Photo. It can be uses to backup phone photos and also manage older collection of older photos.
  
-Immich is a fairly new player in the game (development started around 2022/2023) but it's growing a lot and is gaining a lot of traction. The alternatives are, in my opinion, less refined even if they are apparently older than Immich. +Immich come along a long way in the past year, and even if i had initially tried it out but abandoned due to the lack of some basic (for my use case) features, i can say that as little as less than one year later it proved not only to be **the one** top photo management backup and gallery solution for self-hosting, but a damn good one too. The devs really rocks and work hard, and Immich itself is so flexible that there are little excuses not to use it!
  
-Immich now also support external libraries which is a good point for my use case, since all my older photos are already sorted in folders. When Immich will be able to autogenerate albums from those folders, it will be perfect too.+Immich, at this time, still does not support //base_url// out of the box. A lot of discussion is going on around the topic and somebody found a nice fix using a specific NGINX setup, but i think it's better to stick to subdomains for Immich, at least until it will __officially__ support sub-paths. Anyway, you should really use subdomains with something so complex as Immich to leverage cross-domain security. 
 + 
 +While installing Immich overall is not a huge task, you should really read carefully this page **and** all the very good documentation on Immich website itself.
  
-Immich, at this time, does not support //base_url// out of the box. A lot of discussion is going on around the topic and somebody found a nice fix using a specific NGINX setup, which i will describe in this page. 
  
 ===== Installation ===== ===== Installation =====
  
-I tried to install Immich on bare-metal and give up. The total lack of documentation is regretting and the only existing guide is obsolete. Sadly, using containers is the only viable way to install Immich. The devs clearly stated they do not intend to provide any bare-metal installation instructions and this frankly sucks, even more so that the default docker images provided run as root by default. Anyway, i will show you how to fix this by running Immich using Podman (see [[gentoo:containers|Using Containers on Gentoo]]) root-less. Better than nothing.+I will assume you will store all Immich stuff under **/data/photos**. You will need two folders here: 
 +  * /data/photos/Library: will contain your photos and all additional Immich files (cache, thumbnails, encoded videos...). You want to backup the //library// (yes, lowercase!) and //backups// subfolders in here. 
 +  * /data/photos/immich_database: will contain PostgreSQL stuff, you do not want to backup this folder.
  
-So, let's get going. Create an **immich** user:+Immich needs to be installed using a docker compose file. This is the official and only supported installation method. I will show you, of course, how to run it rootless with podman. Immich installation is detailed [[https://immich.app/docs/install/docker-compose|here]], and i suggest you take a look at. 
 + 
 +I assume you have already created the photo user and group (see [[selfhost:photomanagement|here]], but in case you didn't, here you go:
 <code bash> <code bash>
-useradd -d /data/damons/immich immich+useradd -d /data/daemons/photos photos 
 +mkdir /data/photos 
 +mkdir /data/photos/Library 
 +mkdir /data/photos/immich_database
 </code> </code>
  
-And download the standard immich docker-compose and env files:+And download the standard Immich docker-compose and env files:
 <code bash> <code bash>
-su - immich+su - photos
 wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
-wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml +#optional: wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml 
-wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml+#optional: wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
 wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
 </code> </code>
 (enabling hardware acceleration is optional and i will not cover it here, as it's not needed in my use-case) (enabling hardware acceleration is optional and i will not cover it here, as it's not needed in my use-case)
  
-Since you are going to use podman instead of docker, you need to add a specific network to the docker compose file. Also, you want to add support for your external photo libraries.+I will __not__ give you a full docker-compose file, because Immich sometimes ships with backward incompatibilities, you **must** start from the one linked above and do the following modifications: 
 +  * Specify a network to all containers 
 +  * Add any specific volumes for specific external galleries 
 +  * Remove the //restart// and //healthcheck// sections 
 + 
 +This is the specific code for the network:
 <code> <code>
-# Set the following locations to immich-server, immich-microservices; +# Add these two lines to each one of the services (immich-server, immich-microservices, immich-machine-learning, redis, database, ...)
-    volumes: +
-      - ${UPLOAD_LOCATION}:/usr/src/app/upload +
-      - /etc/localtime:/etc/localtime:ro +
-      - ${EXTERNAL_PATH}:/usr/src/app/external +
- +
-# Add these two lines to each one of the services (immich-server, immich-microservices, immich-machine-learning, redis, database)+
     networks:     networks:
       - immich-net       - immich-net
Line 45: Line 52:
 </code> </code>
  
-Please note that you can have more than one mount, ideally one for each folder tree that contains photos you want to add as external library to Immich.+Please note that you can have more than one mount, ideally one for each folder tree that contains photos you want to add as //external library// to Immich.
  
 edit the **/data/daemons/immich/.env** file to adapt at least your //Uploads// and //external// folder: edit the **/data/daemons/immich/.env** file to adapt at least your //Uploads// and //external// folder:
 <code> <code>
-UPLOAD_LOCATION=/data/Media/Photos/Uploads +# The location where your uploaded files are stored 
-EXTERNAL_PATH=/path/to/your/external/photos/trees +UPLOAD_LOCATION=/data/photos/Library 
-IMMICH_VERSION=release+# The location where your database files are stored 
 +DB_DATA_LOCATION=/data/photos/immich_database
 </code> </code>
  
-then fire up the containers:+You can fine-tune the rest of the env file to your needs. 
 + 
 + 
 +===== Configuration ===== 
 + 
 +You should follow all the steps below before starting using Immich for real, as they have some implications and it's better to sort out stuff before, than reorganize everything later. Immich does a pretty great job of ensuring it's consistent and changeable at a later point in time tough. Still better to dedicate a little time to think stuff out before than later. 
 + 
 + 
 +==== External Library setup ==== 
 + 
 +External libraries let you integrate into Immich existing and already sorted out image libraries. It's a very welcome feature that let's you use Immich in evary conceivable scenario. 
 + 
 +[[https://immich.app/docs/features/libraries|This]] page will give you more details on how to set up an external library. 
 + 
 +You have to perform two steps: 
 +  * Add the external library path as a volume in docker compose 
 +  * From Immich web GUI, create the external library pointing to that path 
 + 
 +So, in your docker-compose.yml ensure that you have mapped each external library like this example: 
 +<code> 
 +services: 
 +  immich-server: 
 +    volumes: 
 +      - /data/photos/ExistingGallery:/mnt/media/ExistingGallery:ro 
 +</code> 
 + 
 +Then, you have to go to //Immich web gui -> administration -> external libraries// and add create a new library. Each library must belong to an user and shall have one or more paths, the ones mapped as above, inside. 
 + 
 +You can also setup a watcher to monitor for new files or period scans to ensure new added files get updated inside Immich as well.  
 + 
 +Keep in mind that Immich will **not touch** the files inthe external library at all, which means that any change to those files metadata will **not** be embedded in the external library files. 
 + 
 + 
 + 
 +==== Storage Template setup ==== 
 + 
 +Storage templates let's you choose how Immich should store photos and videos on your filesystem. This is specially useful if you like to sort your photos for albums and/or year-month-day. I think this is a very powerful feature of Immich and a very welcome addition to it's features. 
 + 
 +My template is:  
 +<code> 
 +{{y}}/{{#if album}}{{album}}{{else}}Others{{/if}}/{{filename}} 
 +</code> 
 + 
 +this template will store folders by **year** and **album**. If the photo is not stored in an album, it will go into a folder called **Others**. 
 + 
 +That can be setup from //Immich web gui -> administration -> settings -> storage templates//. 
 + 
 +You also need to __enable__ it from the same setting area. Remember to run the update storage templates task if you change it. Also, remember to check that it's working as intended before you have thousand of photos stored the wrong way. 
 + 
 + 
 +==== SSO authentication setup ==== 
 + 
 +Immich support direct integration with [[selfhost:sso|Authelia SSO]], specific instructions can be found [[https://www.authelia.com/integration/openid-connect/immich/|on this page]]. 
 + 
 +First of all, you need to configure Authelia with a new client: 
 +<code> 
 +identity_providers: 
 +  oidc: 
 +    ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. 
 +    ## See: https://www.authelia.com/c/oidc 
 +    clients: 
 +      - client_id: << see below to generate ClientID >> 
 +        client_name: 'immich' 
 +        client_secret: << see below to generale ClientSecret >> 
 +        public: false 
 +        authorization_policy: 'one_factor' 
 +        redirect_uris: 
 +          - 'https://immich.mydomain.com/auth/login' 
 +          - 'https://immich.mydomain.com/user-settings' 
 +          - 'app.immich:///oauth-callback' 
 +        scopes: 
 +          - 'openid' 
 +          - 'profile' 
 +          - 'email' 
 +        userinfo_signed_response_alg: 'none' 
 +</code> 
 + 
 +To generate a ClientID:
 <code bash> <code bash>
-su - immich +authelia crypto rand --length 72 --charset rfc3986
-podman compose up -d+
 </code> </code>
 +This information will need to copied to both authelia config and immich settings.
  
-When you want to update Immich, just:+To generate a Client Secret:
 <code bash> <code bash>
-su - immich +authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
-podman compose down +
-podman compose pull +
-podman compose up -d+
 </code> </code>
 +Please note **both** the hash and the password itself! You will need the password itself in the next step.
  
-Be aware that Immich is bleeding edge and sometimes there are **breaking** updates! Always check on Immich [[https://github.com/immich-app/immich/releases|Releases page]] the release notes and take actions accordingly. **YOU HAVE BEEN WARNED**.+Then you need to configure Immich to use Authelia SSO, so go to //Immich web gui → administration → settings → Authentication settings// and enter the following information: 
 +  * Issuer URL: https://auth.example.com/.well-known/openid-configuration. 
 +  * Client ID: << the generated ClientID >>. 
 +  * Client Secret: insecure_secret. 
 +  * Scope: openid profile email. 
 +  * Button Text: Login with Authelia. 
 +  * Auto Register: Enable if desired.
  
-==== NGINX reverse proxy ==== 
  
-Immich does not support bas_url, so: 
  
-<file txt immich.conf> 
-location /immich { 
-        auth_pam off; 
-         return      301 http://$host:2283/; 
-} 
-</file> 
  
-The following setup is recomended if you can host on root: +==== Bakcup setup ====
-<file txt immich.conf> +
-    location / { +
-        proxy_pass http://<snip>:2283; +
-        proxy_set_header Host              $http_host; +
-        proxy_set_header X-Real-IP         $remote_addr; +
-        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for; +
-        proxy_set_header X-Forwarded-Proto $scheme;+
  
-        # http://nginx.org/en/docs/http/websocket.html +I assume you have setup a backup schedule like described [[selfhost:backup|here]], with restic.
-        proxy_http_version 1.1; +
-        proxy_set_header   Upgrade    $http_upgrade; +
-        proxy_set_header   Connection "upgrade"; +
-        proxy_redirect off; +
-    } +
-</file>+
  
-you need also to disable authentication.+For Immich you should backup: 
 +  * **/data/photos/Library/library**: where actual photos are stored 
 +  * **/data/photos/Library/backups**: where postgres backups are stored
  
-=== Immich on sub_path ===+You should also go to //Immich web gui -> administration -> settings -> backups// and reduce the retain to 1 or 2 backups, since you will be backing them up with restic.
  
-Immich does not yet support sub-paths. But using the following specific proxy setup will work: 
-<code> 
-location /immich { 
-                        proxy_pass http://192.168.1.100:2283; 
-                        rewrite /immich/(.*) /$1 break; 
  
-                        proxy_buffering        on; +==== NGINX reverse proxy ====
-                        proxy_cache            immich_revprox; +
-                        proxy_cache_valid      200 206 1d;+
  
-                        sub_filter_once off; +Immich officially **only** support subdomain and not subpath deployment. Use the following NGINX configuration, i will assume your subdomain is called **immich.mydomain.com**. See [[selfhost:nginx|here]] for more details.
-                        sub_filter_types text/html; +
-                        sub_filter ' href="/' ' href="/immich/'; +
-                        sub_filter ' src="/' ' src="/immich/'; +
-                        sub_filter ' action="/' ' action="/immich/'; +
-                        sub_filter 'import("/_app' 'import("/immich/_app'; +
-                        sub_filter 'base: ""' 'base: "/immich"';+
  
-                        location /immich/_app/immutable/chunks { +<file - immich.conf>  
-                                proxy_pass http://192.168.1.100:2283; +    server { 
-                                rewrite /immich/(.*) /$1 break;+        server_name immich.mydomain.com; 
 +        listen 8443 ssl;  
 +        listen 443 ssl;  
 +        client_max_body_size 5000M; 
 +        large_client_header_buffers 4 32k;
  
-                                sub_filter_types *; +        access_log /var/log/nginx/immich.mydomain.com_access_log main; 
-                                sub_filter '"/api/socket.io"' '"/immich/api/socket.io"'; +        error_log /var/log/nginx/immich.mydomain.com_error_log info;
-                        }+
  
-                        location ~ /immich/_app/immutable/chunks/index\\. { +        location / { 
-                                proxy_pass http://192.168.1.100:2283; +        location / { 
-                                rewrite /immich/(.*) /$1 break;+                proxy_pass http://127.0.0.1:2283; 
 +                #proxy_pass http://127.0.0.1:8009; 
 +                proxy_redirect    default; 
 +                proxy_set_header  Host $host; 
 +                proxy_set_header  X-Real-IP $remote_addr; 
 +                proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for; 
 +                proxy_set_header  X-Forwarded-Host $server_name; 
 +                proxy_set_header  X-Forwarded-Proto $scheme; 
 +        } 
 +        include com.mydomain/certbot.conf; 
 +} 
 +</file>
  
-                                sub_filter_types *; +===== Autostart =====
-                                sub_filter '"/' '"/immich/'; +
-                        }+
  
-                        location ~ /immich/_app/immutable/chunks/api\\. { +To start it, and set it up on boot, as usual follow my indications [[gentoo:containers|Using Containers on Gentoo]], so link the **user-containers** init script: 
-                                proxy_pass http://192.168.1.100:2283; +<code> 
-                                rewrite /immich/(.*) /$1 break;+ln -s /etc/init.d/user-containers /etc/init.d/user-containers.immich 
 +</code>
  
-                                sub_filter_types *; +and create the following config file: 
-                                sub_filter '="/api"' '="/immich/api"'; +<file - /etc/conf.d/user-containers.immich> 
-                                sub_filter 'basePath:"/api"' 'basePath:"/immich/api"'; +USER=immich 
-                        }+DESCRIPTION="The photo gallery and backup solution" 
 +</file>
  
-                        location ~ /immich/api { +Add the service to the default runlevel and start it now: 
-                                proxy_pass http://192.168.1.100:2283; +<code bash> 
-                                rewrite /immich/(.*) /$1 break;+rc-update add user-containers.immich default 
 +rc-service user-containers.immich start 
 +</code>
  
-                                proxy_cache off; 
-                                 
-                                sub_filter_types *; 
-                                sub_filter '"redirectUri":"/' '"redirectUri":"/immich/'; 
-                        } 
-                } 
-    </code> 
-     
-    TO BE TESTED 
-     
          
-=== First usage ===+==== Command line CLI ====
  
-Fire up your browser at http://<server ip>:2283 and follow instructions. +Immich has a CLI which requires NPM: 
-To add //external libraries//, it's currently (Immich 1.92.1) a bit convoluted. First you need, as administrator, to go to each user settings (under administration panel) and add the external path as specified in the docker compose (ex: **/usr/src/app/external**) then, as specific user, you also need to add an external library and repeat the same path in your user settings. It's confusing, i think this will be improved in future releases.+<code bash> 
 +emerge nodejs 
 +</code>
  
-=== Command line CLI ===+as user immich: 
 +<code bash> 
 +npm i -g @immich/cli 
 +</code>
  
-Immich has a CLI qhich requires NPM:+The CLI might require login for upload operations:
 <code bash> <code bash>
- > emerge nodejs+immich login-key https://10.0.0.1/immich/api [apiKey] 
 +immich upload --recursive directory/
 </code> </code>
  
-as root: 
-npm i -g @immich/cli 
  
-as une user: +===== Update =====
-immich login-key http://127.0.0.1:2283/api [apiKey]+
  
-immich upload --recursive directory/+When you want to update Immich, just: 
 +<code bash> 
 +su - immich 
 +podman compose down 
 +podman compose pull 
 +podman compose up -d 
 +</code>
  
 +Be aware that Immich is bleeding edge and sometimes there are **breaking** updates! Always check on Immich [[https://github.com/immich-app/immich/releases|Releases page]] the release notes and take actions accordingly. **YOU HAVE BEEN WARNED**.
  
  

This website uses technical cookies only. No information is shared with anybody or used in any way but provide the website in your browser.

More information