Immich: Difference between revisions

(11 intermediate revisions by 8 users not shown)

Line 5:

{{file|/etc/nixos/configuration.nix|nix|3=services.immich.enable = true;

services.immich.port = 2283;}}

To access Immich from other devices via network, add the following as well:

{{file|/etc/nixos/configuration.nix|nix|3=services.immich.host = "0.0.0.0";

services.immich.openFirewall = true;}}

More options are available: {{nixos:option|services.immich.}}

== Tips and Tricks ==

=== Custom Media Location ===

While the official Immich documentation recommends modifying <code>UPLOAD_LOCATION</code> environmental variable for Docker build, NixOS does not support modifying it. Instead, {{nixos:option|services.immich.mediaLocation}} may be used, which simply sets [https://docs.immich.app/install/environment-variables/　<code>IMMICH_MEDIA_LOCATION</code>] variable, while this is not recommended in the official documentation:

{{file|/etc/nixos/configuration.nix|nix|3=services.immich.mediaLocation = "/var/lib/immich";

}}

{{warning|If you have used Immich before, changing this option will completely stop Immich service, disabling access from browser. You may need to reset / remove Postgresql database.}}

{{info|If you only need to change the location where raw data is stored, [https://docs.immich.app/guides/external-library/ External Libraries] may be used.}}

=== Enabling Hardware Accelerated Video Transcoding ===

Add the Immich user to the <code>render</code> and <code>video</code> groups, and enable [[Accelerated Video Playback]] on your system:{{file|/etc/nixos/configuration.nix|nix|3=hardware.graphics = {

Add the Immich user to the <code>render</code> and <code>video</code> groups, override the <code>PrivateDevices</code> service config setting to allow the service to access <code>/dev/dri/</code> and enable [[Accelerated Video Playback]] on your system:{{file|/etc/nixos/configuration.nix|nix|3=# `null` will give access to all devices.

# You may want to restrict this by using something like `[ "/dev/dri/renderD128" ]`

services.immich.accelerationDevices = null;

hardware.graphics = {

# ...

# See: https://wiki.nixos.org/wiki/Accelerated_Video_Playback

};

users.users.immich.extraGroups = [ "video" "render" ]; }}

Line 35:

Line 54:

};

}}

=== Using borg for backups ===

Following Immichs [https://immich.app/docs/administration/backup-and-restore/ backup docs] and [https://immich.app/docs/guides/template-backup-script backup script] an automated backup using [[Borg backup]] could look something like this:

{{File|3=services.borgbackup.jobs."Immich" = {

paths = config.services.immich.mediaLocation;

repo = "<path-to-borg-repo>";

startAt = "Sat 04:00";

compression = "zstd";

encryption.mode = "none";

prune.keep = {

last = 2;

};

};|name=/etc/nixos/configuration.nix|lang=nix}}

Make sure to manually create a borg repo at the desired location beforehand with <code>sudo borg init --encryption=none <path-to-borg-repo</code>

== Troubleshooting ==

=== Fixing postgresql database issue after 25.05 upgrade ===

==== Postgresql collation version mismatch ====

After upgrading you might run into an issue like this, leading to immich-server continuously failing and restarting: <syntaxhighlight>Jul 01 14:23:12 server2 immich[178592]: Postgres notice: {

Jul 01 14:23:12 server2 immich[178592]: severity_local: 'WARNING',

Jul 01 14:23:12 server2 immich[178592]: severity: 'WARNING',

Jul 01 14:23:12 server2 immich[178592]: code: '01000',

Jul 01 14:23:12 server2 immich[178592]: message: 'database "immich" has a collation version mismatch',

Jul 01 14:23:12 server2 immich[178592]: detail: 'The database was created using collation version 2.39, but the operating system provides version 2.40.',

Jul 01 14:23:12 server2 immich[178592]: hint: 'Rebuild all objects in this database that use the default collation and run ALTER DATABASE immich REFRESH COLLATION VERSION,>

Jul 01 14:23:12 server2 immich[178592]: file: 'postinit.c',

Jul 01 14:23:12 server2 immich[178592]: line: '477',

Jul 01 14:23:12 server2 immich[178592]: routine: 'CheckMyDatabase'

Jul 01 14:23:12 server2 immich[178592]: }</syntaxhighlight>To fix this, run <code>sudo -u immich psql -d immich</code> and execute these two commands:<syntaxhighlight lang="sql" line="1">

ALTER DATABASE immich REFRESH COLLATION VERSION;

REINDEX DATABASE immich;

</syntaxhighlight>

==== Upgrading pgvecto.rs ====

If you still run into issues after restarting postgresql and immich-server services, some additional postgresql database changes might be necessary to [https://web.archive.org/web/20240910231531/https://docs.pgvecto.rs/admin/upgrading.html#upgrading upgrade pgvecto.rs table]:

Run <code>sudo -u postgres psql</code> and execute consecutively:<syntaxhighlight lang="sql" line="1">

CREATE EXTENSION IF NOT EXISTS unaccent;

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE EXTENSION IF NOT EXISTS vectors;

CREATE EXTENSION IF NOT EXISTS cube;

CREATE EXTENSION IF NOT EXISTS earthdistance;

CREATE EXTENSION IF NOT EXISTS pg_trgm;

ALTER EXTENSION vectors UPDATE;

SELECT pgvectors_upgrade();

</syntaxhighlight>Finally, restart postgresql and immich: <code>systemctl restart postgresql && systemctl restart immich-server</code>

=== Immich server too old on NixOS stable ===

If you encounter errors like <code>Error processing stream</code> or <code>Error in runInIsolateGentle for remote-sync</code> on Android/iOS clients, the cause may be that the Immich server version packaged in <code>nixos-stable</code> is behind the mobile apps.

You can use the Immich package from <code>nixos-unstable</code> while keeping the rest of your system on stable. Add the following to the top of your <code>/etc/nixos/configuration.nix</code>:

let

unstableTarball = fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz";

in {

nixpkgs.config = {

packageOverrides = pkgs: {

unstable = import unstableTarball {

config = config.nixpkgs.config;

};

}

</syntaxhighlight>

Then override the Immich package in your service config:

services.immich.package = pkgs.unstable.immich;

</syntaxhighlight>

[[Category:Server]]

[[Category:Web Applications]]

@@ Line 5: / Line 5: @@
 {{file|/etc/nixos/configuration.nix|nix|3=services.immich.enable = true;
 services.immich.port = 2283;}}
+To access Immich from other devices via network, add the following as well:
+{{file|/etc/nixos/configuration.nix|nix|3=services.immich.host = "0.0.0.0";
+services.immich.openFirewall = true;}}
 More options are available: {{nixos:option|services.immich.}}
 == Tips and Tricks ==
+=== Custom Media Location ===
+While the official Immich documentation recommends modifying <code>UPLOAD_LOCATION</code> environmental variable for Docker build, NixOS does not support modifying it. Instead, {{nixos:option|services.immich.mediaLocation}} may be used, which simply sets [https://docs.immich.app/install/environment-variables/　<code>IMMICH_MEDIA_LOCATION</code>] variable, while this is not recommended in the official documentation:
+{{file|/etc/nixos/configuration.nix|nix|3=services.immich.mediaLocation = "/var/lib/immich";
+}}
+{{warning|If you have used Immich before, changing this option will completely stop Immich service, disabling access from browser. You may need to reset / remove Postgresql database.}}
+{{info|If you only need to change the location where raw data is stored, [https://docs.immich.app/guides/external-library/ External Libraries] may be used.}}
 === Enabling Hardware Accelerated Video Transcoding ===
-Add the Immich user to the <code>render</code> and <code>video</code> groups, and enable [[Accelerated Video Playback]] on your system:{{file|/etc/nixos/configuration.nix|nix|3=hardware.graphics = {
+Add the Immich user to the <code>render</code> and <code>video</code> groups, override the <code>PrivateDevices</code> service config setting to allow the service to access <code>/dev/dri/</code> and enable [[Accelerated Video Playback]] on your system:{{file|/etc/nixos/configuration.nix|nix|3=# `null` will give access to all devices.
+# You may want to restrict this by using something like `[ "/dev/dri/renderD128" ]`
+services.immich.accelerationDevices = null;
+hardware.graphics = {
   # ...
   # See: https://wiki.nixos.org/wiki/Accelerated_Video_Playback
 };
 users.users.immich.extraGroups = [ "video" "render" ]; }}
@@ Line 35: / Line 54: @@
 };
 }}
+=== Using borg for backups ===
+Following Immichs [https://immich.app/docs/administration/backup-and-restore/ backup docs] and [https://immich.app/docs/guides/template-backup-script backup script] an automated backup using [[Borg backup]] could look something like this:
+{{File|3=services.borgbackup.jobs."Immich" = {
+  paths = config.services.immich.mediaLocation;
+  repo = "<path-to-borg-repo>";
+  startAt = "Sat 04:00";
+  compression = "zstd";
+  encryption.mode = "none";
+  prune.keep = {
+    last = 2;
+  };
+};|name=/etc/nixos/configuration.nix|lang=nix}}
+Make sure to manually create a borg repo at the desired location beforehand with <code>sudo borg init --encryption=none <path-to-borg-repo</code>
+== Troubleshooting ==
+=== Fixing postgresql database issue after 25.05 upgrade ===
+==== Postgresql collation version mismatch ====
+After upgrading you might run into an issue like this, leading to immich-server continuously failing and restarting: <syntaxhighlight>Jul 01 14:23:12 server2 immich[178592]: Postgres notice: {
+Jul 01 14:23:12 server2 immich[178592]:   severity_local: 'WARNING',
+Jul 01 14:23:12 server2 immich[178592]:   severity: 'WARNING',
+Jul 01 14:23:12 server2 immich[178592]:   code: '01000',
+Jul 01 14:23:12 server2 immich[178592]:   message: 'database "immich" has a collation version mismatch',
+Jul 01 14:23:12 server2 immich[178592]:   detail: 'The database was created using collation version 2.39, but the operating system provides version 2.40.',
+Jul 01 14:23:12 server2 immich[178592]:   hint: 'Rebuild all objects in this database that use the default collation and run ALTER DATABASE immich REFRESH COLLATION VERSION,>
+Jul 01 14:23:12 server2 immich[178592]:   file: 'postinit.c',
+Jul 01 14:23:12 server2 immich[178592]:   line: '477',
+Jul 01 14:23:12 server2 immich[178592]:   routine: 'CheckMyDatabase'
+Jul 01 14:23:12 server2 immich[178592]: }</syntaxhighlight>To fix this, run <code>sudo -u immich psql -d immich</code> and execute these two commands:<syntaxhighlight lang="sql" line="1">
+ALTER DATABASE immich REFRESH COLLATION VERSION;
+REINDEX DATABASE immich;
+</syntaxhighlight>
+==== Upgrading pgvecto.rs ====
+If you still run into issues after restarting postgresql and immich-server services, some additional postgresql database changes might be necessary to [https://web.archive.org/web/20240910231531/https://docs.pgvecto.rs/admin/upgrading.html#upgrading upgrade pgvecto.rs table]:
+Run <code>sudo -u postgres psql</code> and execute consecutively:<syntaxhighlight lang="sql" line="1">
+CREATE EXTENSION IF NOT EXISTS unaccent;
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS vectors;
+CREATE EXTENSION IF NOT EXISTS cube;
+CREATE EXTENSION IF NOT EXISTS earthdistance;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+ALTER EXTENSION vectors UPDATE;
+SELECT pgvectors_upgrade();
+</syntaxhighlight>Finally, restart postgresql and immich: <code>systemctl restart postgresql && systemctl restart immich-server</code>
+=== Immich server too old on NixOS stable ===
+If you encounter errors like <code>Error processing stream</code> or <code>Error in runInIsolateGentle for remote-sync</code> on Android/iOS clients, the cause may be that the Immich server version packaged in <code>nixos-stable</code> is behind the mobile apps.
+You can use the Immich package from <code>nixos-unstable</code> while keeping the rest of your system on stable. Add the following to the top of your <code>/etc/nixos/configuration.nix</code>:
+<syntaxhighlight lang="nix" line>
+let
+  unstableTarball = fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz";
+in {
+  nixpkgs.config = {
+    packageOverrides = pkgs: {
+      unstable = import unstableTarball {
+        config = config.nixpkgs.config;
+      };
+    };
+  };
+}
+</syntaxhighlight>
+Then override the Immich package in your service config:
+<syntaxhighlight lang="nix" line>
+services.immich.package = pkgs.unstable.immich;
+</syntaxhighlight>
 [[Category:Server]]
 [[Category:Web Applications]]