SoFunction
Updated on 2025-04-13

Detailed explanation of immich configuration file

Preface

Immich is a self-hosted photo and video backup solution that allows users to store, manage and share their media files on private servers.

This project is designed to provide an experience similar to Google Photos or iCloud Photo Library, but users have complete control over their data. Through self-hosting, users do not need to rely on third-party cloud service providers to store private photos and videos, which increases privacy protection and data ownership.

The main features of Immich include:

  • Self-hosted: All data is stored on the user's own server.
  • Photo and video backup: Provides automatic media file backup function.
  • Easy to access: Through the web interface and mobile apps, users can easily access, manage and share their media libraries.
  • Data control: Users have and control over their own data, rather than stored in third-party cloud services.
  • Privacy protection: Since it is a self-hosted solution, users’ photos and videos will not be accessed by unauthorized third parties.

Immich is usually deployed in containerization through Docker, making installation and maintenance simple. The project is open sourced, community-driven, constantly updated and improved on GitHub.

Using Immich, users need to have a certain technical background, especially knowledge about how to deploy and maintain self-hosted services.

But for users who want to improve privacy and security of personal data, Immich offers a great solution.

Configuration file explanation

# Specify the version of Docker Compose file to 3.8version: "3.8"

# Define the name of the project as immichname: immich

# Define multiple servicesservices:
  # Define a service name immich-server  immich-server:
    # Set the name of the container to immich_server    container_name: immich_server
    # Pull the immich-server image from GitHub Container Registry. The version is specified by the IMMICH_VERSION environment variable, and the default is release    image: /immich-app/immich-server:${IMMICH_VERSION:-release}
    # Commands executed after the container is started    command: [ "", "immich" ]
    # Specify the mounted volume    volumes:
      # Mount the host's UPLOAD_LOCATION directory to /usr/src/app/upload of the container      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      # Mount the host's /etc/localtime into the container and synchronize the time in a read-only manner      - /etc/localtime:/etc/localtime:ro
    # Specify environment variable file    env_file:
      # Use the .env file in the current directory      - .env
    # Specify port mapping    ports:
      # Map the container's port 3001 to the host's port 2283      - 2283:3001
    # Define service dependencies    depends_on:
      # immich-server depends on redis and database services      - redis
      - database
    # Set the container's restart policy to always restart    restart: always

  # Define another service name immich-microservices  immich-microservices:
    # Set the name of the container to immich_microservices    container_name: immich_microservices
    # Use the same mirroring and versioning policies    image: /immich-app/immich-server:${IMMICH_VERSION:-release}
    # Command to start microservices    command: [ "", "microservices" ]
    # Also specify the mounted volume    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    # Use the same environment variable file    env_file:
      - .env
    # Also relies on redis and database services    depends_on:
      - redis
      - database
    # Also set to always restart    restart: always

# The following is the part that defines the volumes to specify the required Docker volumesvolumes:
  # Define a volume name pgdata to persist PostgreSQL database data  pgdata:
  # Define a volume named model-cache, which is used to cache machine learning model data  model-cache:

This file defines a series of services for Immich applications, including the main application server, microservices, machine learning services, Redis cache, and PostgreSQL database services.

Through this configuration file, all components of the Immich application can be started at once, and functions such as dependency management between services and automatic restart policies can be implemented.

Environment variables .env file explanation

# You can find all supported environment variables documentation in this URL: /docs/install/environment-variables# The above line is a comment that illustrates how to find the official documentation about all supported environment variables.
# The file you upload will be stored in this locationUPLOAD_LOCATION=./library
# Set the `UPLOAD_LOCATION` environment variable to define the storage location of uploaded files.  This is set to the `library` folder in the current directory.
# Immich version used.  You can pin it to a specific version, such as "v1.71.0"IMMICH_VERSION=release
# Set the `IMMICH_VERSION` environment variable to specify the version Immich is used.  Set to `release` here, which means that the latest release version will be used.
# Connection password for Postgres.  You should change it to a random passwordDB_PASSWORD=postgres
# Set the `DB_PASSWORD` environment variable to define the password to connect to the PostgreSQL database.  The default setting is `postgres`, and it is recommended to change to a more secure password.
# The following line does not need to be changed###################################################################################
# The above line is a comment, indicating that the following environment variables usually do not need to be modified.
DB_HOSTNAME=immich_postgres
# Set the `DB_HOSTNAME` environment variable and specify the host name of the PostgreSQL database service.  Here is the service name `immich_postgres` defined in the file.
DB_USERNAME=postgres
# Set the `DB_USERNAME` environment variable to define the user name that connects to the PostgreSQL database.  The default setting is `postgres`.
DB_DATABASE_NAME=immich
# Set the `DB_DATABASE_NAME` environment variable and specify the name of the PostgreSQL database.  Here is set to `immich`.
REDIS_HOSTNAME=immich_redis
# Set the `REDIS_HOSTNAME` environment variable and specify the host name of the Redis service.  Here is the service name `immich_redis` defined in the file.

This .env file provides basic configuration for the Immich service and the database it depends on (PostgreSQL) and Redis service.

Through these environment variables, the Immich service can correctly connect to the database and Redis, while specifying the location where the file is uploaded.

Summarize

The above is personal experience. I hope you can give you a reference and I hope you can support me more.