Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Photo Management Immich

Introduction

Welcome to the world of self-hosted photo and video management with Immich. In an era where cloud services like Google Photos or Apple iCloud Photos dominate the landscape, concerns about privacy, cost, and data ownership are increasingly relevant. Immich emerges as a powerful, open-source, and self-hostable alternative, aiming to provide a user experience comparable to its commercial counterparts while giving you complete control over your precious memories.

This section will guide you through understanding Immich, setting it up, using its features effectively, and managing it like a pro. We'll cover everything from the initial installation to advanced configurations, ensuring you have the knowledge to build and maintain your personal, secure photo management platform.

What is Immich?

Immich is a high-performance self-hosted photo and video backup solution directly from your mobile phone. It's designed with several key goals in mind:

Primary Backup Solution: To be the main location where your mobile photos and videos are stored securely.
Feature Parity: To eventually offer features comparable to leading cloud providers (timeline view, search, albums, sharing, object detection, facial recognition, etc.).
Performance: To be fast and responsive, even with large libraries.
Ease of Use: To provide intuitive web and mobile interfaces.
Data Ownership: To ensure you control your data, storing it on hardware you manage.

Why Choose Immich for Self-Hosting?

Privacy: Your photos and videos remain on your server, under your control. No third-party scanning for advertising or other purposes (unless you configure external ML services explicitly).
Cost-Effective: Beyond the initial hardware and ongoing electricity costs, there are no recurring subscription fees that scale with storage usage.
Control & Customization: You decide how your data is stored, backed up, and accessed. You can integrate it with other self-hosted services.
Active Development: Immich has a vibrant community and is under rapid development, meaning new features and improvements are constantly being added.
Modern Technology Stack: It utilizes technologies like Docker, PostgreSQL, Redis, and Typescript, making it relatively straightforward to deploy and manage for those familiar with modern web application architectures.

Target Audience and Prerequisites

This guide assumes you are a university student or enthusiast comfortable with:

Basic Linux command-line operations.
Fundamental networking concepts (IP addresses, ports).
Docker and Docker Compose: Understanding containerization is crucial as it's the primary deployment method for Immich. We will cover the specifics, but prior familiarity is highly beneficial.

We will progress from basic setup and usage to more advanced topics like reverse proxy configuration, backups, and performance tuning. Each section includes practical workshops to solidify your understanding. Let's begin the journey to reclaiming control over your digital memories!

1. Basic Level Understanding and Setup

This initial part focuses on grasping the fundamental concepts behind Immich and performing the initial installation. By the end of this section, you will have a running Immich instance and understand its basic architecture.

Core Concepts of Immich

Before diving into installation, it's essential to understand how Immich is structured and the key components involved. Immich employs a microservices architecture, which means it's composed of several independent but cooperating services, typically managed together using Docker Compose.

Architecture Overview

A standard Immich deployment consists of the following core components working together:

Immich Server (immich-server): This is the main backend API service. It handles core logic, authentication, database interactions, and orchestrates tasks for other services. It's the central brain of the operation.
Immich Web UI (immich-web): This service provides the web-based front-end that you interact with through your browser. It communicates with the Immich Server API to display photos, manage albums, change settings, etc.
Microservices (immich-microservices): This component handles background tasks that can be resource-intensive or time-consuming. This includes:
- Thumbnail Generation: Creating smaller versions of images for previews.
- Metadata Extraction: Reading EXIF (Exchangeable Image File Format) data, dates, GPS coordinates, etc., from media files.
- Video Transcoding (Optional): Converting videos into web-compatible formats if needed.
Machine Learning (immich-machine-learning): This dedicated service handles computationally expensive AI-related tasks, such as:
- Image Tagging/Classification: Identifying objects and scenes within photos (e.g., "dog," "beach," "car").
- Facial Detection and Recognition: Finding faces in photos and grouping similar faces together. This requires specific models and can be CPU/GPU intensive.
Database (PostgreSQL): Immich uses a PostgreSQL database to store all metadata about your photos and videos (filenames, paths, dates, tags, album associations, user information, etc.). Crucially, the photos themselves are NOT stored in the database; only their metadata is.
Cache (Redis): Redis is an in-memory data structure store used as a cache and message broker. It helps speed up certain operations and manage the queue for background tasks processed by the microservices.

Data Storage Explained

Metadata: Stored in the PostgreSQL database. This is critical; losing the database means losing all organization, user data, albums, tags, etc., even if the original files are intact.
Media Files (Library): Your actual photo and video files are stored directly on the filesystem in a location you specify (often referred to as the UPLOAD_LOCATION or library path). Immich typically organizes these files into a structured directory hierarchy based on user and date.
Thumbnails: Generated preview images are also stored on the filesystem, usually in a separate cache or generated-files directory linked to the main Immich volumes.

Key Features at a Glance

Mobile Upload: Dedicated iOS and Android apps for automatic background backup.
Web Interface: Full-featured browser access for management and viewing.
Timeline View: Chronological browsing of your photos.
Albums: Create and manage your own albums.
Sharing: Share albums or individual photos with other Immich users or via public links.
Multi-User Support: Separate accounts for different users (e.g., family members).
Metadata Search: Search based on dates, file types, and EXIF data.
AI-Powered Search: Search by detected objects, tags, and recognized faces (requires ML setup).
Geolocation: View photos on a map based on embedded GPS data.

Understanding these components and concepts provides a solid foundation for installing and managing your Immich instance effectively.

Workshop Understanding Immich's Components via Docker Compose

Goal: To familiarize yourself with the different services Immich uses by examining its docker-compose.yml file.

Prerequisites:

Access to a terminal on a machine where you intend to install Immich (or any machine with git and a text editor).
git command-line tool installed (sudo apt update && sudo apt install git on Debian/Ubuntu).

Steps:

Clone the Immich Repository: Open your terminal and clone the official Immich repository to get the example configuration files.
```
git clone https://github.com/immich-app/immich.git
cd immich/docker
```
Explanation: We use git clone to download the repository containing the source code and deployment files. We then navigate into the docker directory which holds the necessary Docker-related files.
Locate the Docker Compose File: Inside the docker directory, you'll find a file named docker-compose.yml.
Examine the docker-compose.yml File: Open this file using a text editor like nano, vim, or a graphical editor.
```
nano docker-compose.yml
```
Explanation: This YAML file defines the multi-container Docker application. Each top-level key under services: defines one container (service).
Identify the Services: Scroll through the file and identify the main services we discussed:
- immich-server
- immich-web
- immich-microservices
- immich-machine-learning
- redis
- database (or postgres)
- Look for an optional immich-proxy service (like Nginx) if it's included in the example.
Analyze a Service Definition (e.g., immich-server): Look at the configuration for one service, for example, immich-server:
- container_name: Sets a specific name for the container.
- image: Specifies the Docker image to use (e.g., ghcr.io/immich-app/immich-server:release).
- depends_on: Lists other services that this service needs to be running first (e.g., database, redis). This controls startup order.
- volumes: Defines how data persists. Look for mappings between host directories (left side) and container directories (right side). Pay attention to where configuration or data might be stored. Example: ./pgdata:/var/lib/postgresql/data for the database service maps a local directory pgdata to the PostgreSQL data directory inside the container.
- ports: Maps ports between the host machine and the container (e.g., 2283:3001 maps host port 2283 to container port 3001).
- env_file: Specifies a file (.env) containing environment variables used for configuration.
- environment: Allows setting environment variables directly.
- restart: always (or similar): Defines the container's restart policy.
Identify Key Configuration Points:
- Locate the database service section. Note the image used (e.g., tensorchord/pgvecto-rs:pg14-v0.2.0) and the volumes for data persistence. Find the env_file reference, indicating credentials will be externalized.
- Find the volumes: section for immich-server or immich-microservices. Look for the volume mapping related to photo uploads (it might use a variable like ${UPLOAD_LOCATION}).
- Note the ports exposed by immich-web or the immich-proxy service, as this is likely how you'll access the UI.
Close the Editor: Exit nano (usually Ctrl+X, then Y if prompted to save, then Enter).

Outcome: By inspecting the docker-compose.yml, you should now have a clearer picture of the individual software pieces that make up Immich, how they are configured to communicate (implicitly via Docker networking, explicitly via dependencies), and where persistent data like the database files and uploaded media are intended to be stored. This understanding is vital for troubleshooting and managing the application later.

Installation via Docker Compose

Docker Compose is the recommended and most common method for installing Immich. It simplifies the process of deploying the multi-container application defined in the docker-compose.yml file.

Prerequisites Revisited

Docker Engine: You need Docker installed and running on your host system. Follow the official Docker installation guide for your Linux distribution (e.g., Install Docker Engine on Ubuntu). Ensure your user is part of the docker group to run Docker commands without sudo (requires logging out and back in after adding the user to the group: sudo usermod -aG docker $USER).
Docker Compose: You need the Docker Compose plugin (v2 is recommended). If you installed Docker Desktop or used the latest Docker Engine installation scripts, it's likely included. Verify by running docker compose version. If not found, follow the Install the Compose plugin instructions.
Git: Needed to clone the repository (as done in the previous workshop). If you skipped it, install git now.
Minimum System Resources: Check the official Immich documentation for current recommendations. Generally, you'll need at least 2 CPU cores and 4GB of RAM for a basic experience, but more is recommended, especially if enabling Machine Learning features. Disk space depends entirely on the size of your photo/video library.

Installation Steps

Choose an Installation Directory: Create a dedicated directory on your host system where you will store the Immich configuration files (docker-compose.yml, .env) and potentially the persistent data volumes (though data volumes like uploads are often placed elsewhere).
```
mkdir ~/immich-app
cd ~/immich-app
```
Explanation: We create a directory named immich-app in the user's home directory (~) and navigate into it. This keeps the configuration organized.
Download Configuration Files: Obtain the necessary docker-compose.yml and .env files. The recommended way is usually provided in the official Immich documentation, often involving downloading them directly or cloning the repository as done previously. Let's assume you already cloned it in the previous workshop step. If not:
```
# If you didn't clone before:
# git clone https://github.com/immich-app/immich.git
# cd immich/docker

# If you did clone and are in ~/immich-app:
# Copy the example files from the cloned repo (adjust path if needed)
cp ../immich/docker/example.env .env
cp ../immich/docker/docker-compose.yml .
```
Explanation: We copy the example environment file (example.env) to .env and the docker-compose.yml file into our chosen installation directory (~/immich-app). The .env file is crucial as it holds personalized configuration settings.
Configure the .env File: This is a critical step. Open the .env file with a text editor (nano .env). Carefully review and modify the variables according to your needs. Key variables to check/set:
- DB_PASSWORD: Set a strong, unique password for the PostgreSQL database user. Do not leave the default.
- POSTGRES_PASSWORD: Set a strong, unique password for the PostgreSQL superuser. Do not leave the default. Ensure this matches the DB_PASSWORD if using the standard Immich setup where Immich connects as the main user. Read the comments in the .env file carefully regarding these passwords.
- UPLOAD_LOCATION: This is extremely important. Set this to the absolute path on your host machine where you want Immich to store all uploaded photos and videos. Make sure this directory exists and that the user running Docker (or the user inside the container, typically with UID/GID 1000) has write permissions. For example: UPLOAD_LOCATION=/mnt/media/immich-uploads. Create this directory: mkdir -p /mnt/media/immich-uploads and potentially adjust permissions if needed (sudo chown your_user:your_user /mnt/media/immich-uploads or adjust based on container user ID if necessary).
- DB_HOSTNAME: Usually should remain immich-database or database (matching the service name in docker-compose.yml).
- Ports: Check the ports defined (e.g., IMMICH_SERVER_PORT, IMMICH_WEB_PORT). Ensure they don't conflict with other services running on your host. The defaults (like 2283 for the server) are usually fine unless already in use. The docker-compose.yml might map these internal ports to different external ports.
- Other Variables: Review other variables related to logging, ML models, etc., but the database credentials and upload location are the most critical for initial setup. Save the file and exit the editor.
Pull Docker Images: Before starting the containers, it's good practice to pull the latest images specified in the docker-compose.yml.
```
docker compose pull
```
Explanation: This command downloads all the necessary Docker images (Immich server, web, microservices, ML, Redis, PostgreSQL) from their respective registries. This can take some time depending on your internet connection.
Start Immich Containers: Now, start the application in detached mode (-d), meaning it will run in the background.
```
docker compose up -d
```
Explanation: docker compose up reads the docker-compose.yml and .env files, creates the necessary networks and volumes, and starts all the defined services. The -d flag detaches the process from your terminal. Docker will automatically restart containers based on the restart: policy defined in the compose file (usually always or unless-stopped).
Verify Container Status: Check if all containers started successfully.
```
docker compose ps
```
Explanation: This command lists the containers managed by the current docker-compose.yml file and their status (should ideally show Up or Running). You can also use docker ps to see all running containers on your system.
Initial Access and Admin User Creation:
- Open your web browser and navigate to the IP address of your host machine followed by the port mapped to the Immich web service. By default in the docker-compose.yml, this is often port 2283 mapped from the internal container port 3000 or 3001. Check your docker-compose.yml under the immich-proxy or immich-web service's ports: section. For example: http://<your_host_ip>:2283.
- You should see the Immich welcome/login page.
- Click on the "Admin Sign Up" or similar button.
- Enter your desired email address, password, and name for the administrator account. This will be the first user and have full control over the Immich instance.
- Complete the sign-up process.

You now have a running Immich instance!

Workshop Installing Immich

Goal: To perform a hands-on installation of Immich using Docker Compose, verify its operation, and create the initial administrator user.

Prerequisites:

A Linux server/VM with Docker and Docker Compose installed and running.
User added to the docker group (or use sudo).
git installed.
A designated directory for installation (e.g., /mnt/data/immich-photos) chosen for storing photos/videos. Make sure this directory exists and you have write permissions.

Steps:

Prepare Installation Directory:

# Choose a main directory for Immich config
INSTALL_DIR=~/immich-config
mkdir -p $INSTALL_DIR
cd $INSTALL_DIR

# Define and create the actual photo storage location
UPLOAD_DIR=/mnt/data/immich-photos # IMPORTANT: Change this to your desired path
sudo mkdir -p $UPLOAD_DIR
sudo chown $USER:$USER $UPLOAD_DIR # Ensure your user owns it for now
# Note: Permissions might need adjustment later depending on the container's user ID
echo "Immich configuration will be in: $INSTALL_DIR"
echo "Immich photo library will be at: $UPLOAD_DIR"

Explanation: We set up variables for clarity, create the directories, and ensure the current user owns the upload directory.

Get Configuration Files:

# Download the docker-compose.yml and example.env directly (alternative to git clone)
wget https://raw.githubusercontent.com/immich-app/immich/main/docker/docker-compose.yml
wget https://raw.githubusercontent.com/immich-app/immich/main/docker/example.env -O .env
ls -l

Explanation: We use wget to download the latest standard compose file and the example environment file directly into our INSTALL_DIR, renaming the environment file to .env. ls -l confirms the files are present.

Configure .env:
```
nano .env
```
- Find UPLOAD_LOCATION=./library.
- Change it to the absolute path you created: UPLOAD_LOCATION=/mnt/data/immich-photos (replace with your actual $UPLOAD_DIR path).
- Find DB_PASSWORD=postgres. Change this to a very strong, unique password (e.g., use a password manager). Record this password securely.
- Find POSTGRES_PASSWORD=postgres. Change this to another (or the same, check comments in .env) very strong, unique password. Record this securely.
- Scroll through and review other settings like ports (e.g., IMMICH_WEB_PORT=2283). Note the web port for access later.
- Save the file (Ctrl+X, then Y, then Enter in nano).
Pull Docker Images:
```
docker compose pull
```
Explanation: Downloads all required container images. Wait for completion.
Start Immich:
```
docker compose up -d
```
Explanation: Starts all Immich services in the background.
Verify Containers:
```
sleep 10 # Wait a few seconds for containers to initialize
docker compose ps
```
Expected Outcome: You should see a list of containers (immich-server, immich-web, immich-microservices, immich-machine-learning, redis, database) all showing a State of Up or Running. If any containers failed to start, use docker compose logs <service_name> (e.g., docker compose logs immich-server) to check for errors. Common initial errors relate to incorrect paths/permissions for UPLOAD_LOCATION or database connection issues.
Access Web UI and Create Admin User:
- Find the IP address of your server (e.g., using ip addr show).
- Open a web browser on your computer and go to http://<your_server_ip>:2283 (replace <your_server_ip> with the actual IP and 2283 with the port you noted from the .env or docker-compose.yml if you changed it).
- You should see the Immich landing page. Click "Admin Sign Up".
- Enter your details (email, strong password, name) for the administrator account.
- Click "Sign Up".

Outcome: You have successfully installed Immich using Docker Compose, verified that all its components are running, configured the essential storage location and database passwords, and created the primary administrator account through the web interface. Your Immich instance is now ready for basic use.

2. Intermediate Level Usage and Configuration

With Immich installed, we now move to exploring its core functionalities: managing users, uploading media, organizing content, and utilizing search capabilities. This section aims to make you proficient in the day-to-day use of Immich.

User Management and Permissions

Immich is designed for multi-user environments, allowing you to create separate accounts for family members or friends, each with their own library, while also enabling controlled sharing.

Creating Additional Users

Only an administrator user can create new accounts.

Log in as Admin: Access your Immich web UI and log in using the administrator account created during setup.
Navigate to User Management: Go to "Administration" (usually accessible through your user profile icon in the top right) -> "User Management".
Create New User: Click the "Add User" or "+" button.
Enter User Details: Provide the necessary information for the new user:
- Email Address (used for login)
- Password (set an initial password; the user can change it later)
- Name
- Storage Quota (optional, set a limit on how much storage this user can consume)
Assign Roles/Permissions:
- Admin: Check the "Is Admin" box if this user should also have administrative privileges (ability to manage users, system settings, etc.). Use this sparingly.
- Regular User: Leave "Is Admin" unchecked for standard users. They can manage their own photos, albums, and settings but cannot access system-wide administration panels.
Confirm Creation: Save the new user. They can now log in using the credentials you provided.

Understanding Library Separation

By default, each user in Immich has their own isolated library. Photos uploaded by User A are not visible to User B unless explicitly shared. The UPLOAD_LOCATION you configured earlier acts as the root, and Immich typically creates subdirectories within it for each user (e.g., /mnt/data/immich-photos/user-a-uuid, /mnt/data/immich-photos/user-b-uuid). This ensures privacy and separation of content.

Sharing Concepts

Immich offers several ways to share photos and videos:

Album Sharing:
- Users can create albums and add specific photos/videos to them.
- Albums can be shared with specific other Immich users registered on the same instance.
- When sharing an album, you can typically grant "Viewer" (read-only) or "Contributor" (can add/remove photos) permissions to the users you share with.
- Shared albums appear in the "Sharing" section for the recipient users.
Public Sharing Links (for Albums):
- Users can generate unique, publicly accessible links for specific albums.
- Anyone with the link can view the album contents, even without an Immich account.
- Options often exist to password-protect these links or set an expiration date for enhanced security. Use public links with caution, especially for personal photos.
Individual Photo/Video Sharing (Less Common): While album sharing is the primary mechanism, some interfaces might allow sharing individual items, often by adding them to a new shared album first.

Partner Sharing

This is a powerful feature inspired by Google Photos, designed for close partners (e.g., spouses, family members).

Setup: Two users can establish a "Partner Sharing" relationship. This is usually initiated from the user settings or sharing section. One user sends an invitation, and the other accepts.
Functionality: Once partnered, users can choose to automatically share their entire library, or only photos from a specific date onwards, with their partner. Photos featuring specific recognized people (if face recognition is enabled) can also be selectively shared automatically.
Visibility: Shared photos appear seamlessly within the partner's main timeline view, often marked subtly to indicate they are from the partner.
Privacy: Each user controls what they share with their partner. Setting up partner sharing does not automatically grant access to the partner's entire library unless they also configure sharing back. It's a reciprocal but independently configured setup.

Understanding these user management and sharing features allows you to tailor Immich to your specific household or group needs, balancing privacy with the convenience of shared memories.

Goal: To practice creating a new user, sharing an album between users, and exploring the partner sharing setup.

Prerequisites:

A running Immich instance.
Logged in as the administrator user.

Steps:

Create a Second User:
- Navigate to "Administration" -> "User Management".
- Click "Add User".
- Enter the following details:
  - Email: testuser@example.com (or any other email)
  - Password: Choose a simple password for this test (e.g., password123). Remember it.
  - First Name: Test
  - Last Name: User
  - Leave "Is Admin" unchecked.
  - Leave "Storage Quota" blank (unlimited).
- Click "Create".
- Verify that "Test User" now appears in the user list.
Log in as the New User (Optional but Recommended):
- Log out from your admin account (click profile icon -> Logout).
- Log in using the credentials for testuser@example.com.
- Explore the interface briefly. Note that the "Administration" option is missing.
- Log out and log back in as the admin user.
Admin Uploads Photos:
- As the admin user, navigate to the main timeline/photos view.
- Click the "Upload" button (usually top right).
- Select and upload 3-5 sample photos from your computer. Wait for the upload to complete.
Admin Creates and Shares an Album:
- Go to the "Albums" section (usually in the left sidebar).
- Click "New Album".
- Give the album a name, e.g., "Shared Test Photos".
- Click "Select Photos". Choose the photos you just uploaded. Click "Add".
- Once the album is created and you are viewing it, look for a "Share" button or icon (often represented by three dots or a person icon).
- Click "Share". In the "Add Users" field, start typing Test User or testuser@example.com. Select the user from the list.
- Grant "Viewer" permission for now.
- Click "Save" or "Done".
Verify Sharing as the Second User:
- Log out as the admin user.
- Log in as testuser@example.com.
- Navigate to the "Sharing" section (left sidebar).
- You should see the "Shared Test Photos" album listed under "Shared with me".
- Click on the album to view the photos shared by the admin. Confirm you cannot add or remove photos (due to Viewer permission).
Explore Partner Sharing Setup (Do Not Complete Unless Desired):
- While logged in as testuser@example.com, click the profile icon (top right) -> "Account Settings".
- Look for a "Sharing" or "Partner Sharing" tab/section.
- You should see an option to "Set up partner sharing" or "Invite a partner".
- Click it and observe the process (you'd typically enter the email address of the admin user or vice-versa). Note the options presented (share entire library, share from a date, share photos of specific people).
- Do not actually send the invitation unless you intend to test this feature fully with the admin account. Simply observe the setup interface.
- Log out and log back in as the admin user.

Outcome: You have successfully created a non-admin user, uploaded photos, created an album, shared that album with the new user with specific permissions, and verified access from the recipient's account. You have also located and familiarized yourself with the interface for setting up Partner Sharing. This demonstrates the core multi-user and sharing capabilities of Immich.

Uploading and Organizing Media

Getting your photos and videos into Immich is fundamental. Immich offers several methods for this, catering to different workflows. Once uploaded, organizing them into albums helps in management and retrieval.

Upload Methods

Web Uploader:
- How it works: Accessible directly from the Immich web interface. Typically involves clicking an "Upload" button and then dragging-and-dropping files/folders or using a file browser dialog.
- Pros: Simple, universally accessible from any desktop browser, good for bulk uploads from a computer.
- Cons: Manual process, requires the browser window to remain open during the upload, less convenient for continuous mobile backup.
- Use Case: Initial migration of existing photo libraries from a computer, uploading photos from a dedicated camera.
Mobile App Upload:
- How it works: Install the official Immich mobile app (iOS/Android). Log in to your Immich server instance (you'll need your server URL, e.g., http://<your_server_ip>:2283, and user credentials). The app has settings for automatic background uploading.
- Configuration:
  - Server Endpoint URL: The full URL to access your Immich server. Use HTTPS if you have a reverse proxy set up.
  - Credentials: Your Immich username (email) and password.
  - Background Backup: Enable this for automatic uploads.
  - Wi-Fi Only: Option to upload only when connected to Wi-Fi to save mobile data.
  - Charging Only: Option to upload only when the phone is charging to save battery.
  - Select Albums/Folders: Choose which folders on your phone should be backed up.
  - Existing Assets: Decide whether to back up all existing photos/videos or only new ones taken after setup.
- Pros: Automated backup solution for mobile devices, "set and forget" convenience, replicates the cloud photo service experience.
- Cons: Requires correct server configuration and reachability from the mobile network (potentially needing a reverse proxy and domain name for external access), can consume battery and data (configurable).
- Use Case: The primary intended use case for Immich – continuously backing up photos taken on your smartphone.
Immich Command-Line Interface (CLI) Upload:
- How it works: Immich provides a separate CLI tool (immich-cli) that can be installed and used to upload files from a terminal. This is useful for scripting or bulk importing large existing libraries from a server or NAS.
- Pros: Scriptable, powerful for large migrations, can run on a server without a GUI.
- Cons: Requires command-line knowledge, installation of the separate tool.
- Use Case: Migrating very large collections (hundreds of GBs or TBs) from network drives or other storage locations where using the web UI or mobile app is impractical. (We won't detail the CLI setup here, but be aware of its existence for advanced scenarios).

Understanding the Library Structure (Internal)

When you upload media, Immich doesn't just dump files into the UPLOAD_LOCATION. It processes them:

Metadata Extraction: Reads EXIF data (camera model, date taken, GPS coordinates), generates checksums.
Storage: Stores the original file in a structured directory within the UPLOAD_LOCATION, typically organized by user ID and date (e.g., .../upload/library/<user-id>/originals/YYYY/MM/DD/). This ensures originals are preserved.
Thumbnail Generation: Creates various sizes of preview images (thumbnails) used in the web UI and mobile apps for faster browsing. These are usually stored in a separate thumbs or encoded-video directory structure linked to the original file.
Video Transcoding (Optional/On-Demand): If necessary, Immich might transcode videos into formats like MP4 (H.264/AAC) that are widely compatible with web browsers, especially for streaming. Original video files are typically preserved.
Database Entry: Creates records in the PostgreSQL database linking the file path, metadata, user, thumbnails, etc.

It's important to know that the structure inside UPLOAD_LOCATION is managed by Immich. You should generally not manually move, rename, or delete files within this structure, as it will break Immich's database references and the files will become inaccessible or "orphaned" within the application. Always manage photos (delete, move between albums) through the Immich UI or apps.

Organizing with Albums

Albums are virtual collections of photos/videos. Adding a photo to an album doesn't move the original file; it just creates an association in the database.

Manual Albums: You create an album and manually select which photos/videos belong to it. This is the most common way to group photos from specific events (e.g., "Vacation 2023," "Project Presentation Photos").
Automatic Albums (Feature Varies): Some photo managers offer albums automatically created based on criteria like dates, locations, or recognized faces. Check Immich's current features to see what automatic album capabilities are available (e.g., "People" albums based on face recognition).

Albums are essential for organizing content beyond the simple chronological timeline view, especially as your library grows.

Workshop Uploading Strategies

Goal: To practice uploading photos using both the web UI and the mobile app, and to create a manual album to organize some of the uploaded media.

Prerequisites:

A running Immich instance with at least one user account (admin or regular user).
Access to the Immich web UI.
A smartphone (iOS or Android) with the Immich app installed.
Your Immich server must be reachable from your smartphone's network (this might mean being on the same Wi-Fi network if you haven't set up external access yet).
Some sample photos on your computer and on your smartphone.

Steps:

Part 1: Web Upload and Album Creation

Log in to Web UI: Access your Immich instance via browser and log in.
Upload from Computer:
- Click the "Upload" button.
- Either drag and drop a few sample photos from your computer onto the upload area or click to browse and select them.
- Wait for the uploads to complete. You should see the photos appear in your timeline.
Create a Manual Album:
- Navigate to the "Albums" section.
- Click "New Album".
- Name it "Web Uploads Test".
- Click "Select Photos".
- Find and select the photos you just uploaded via the web interface.
- Click "Add".
- Verify that the album "Web Uploads Test" now exists and contains the selected photos.

Part 2: Mobile App Configuration and Upload

Install Immich App: If you haven't already, download and install the official Immich app from the iOS App Store or Google Play Store.
Configure App Connection:
- Open the Immich app.
- You'll be prompted for the Server Endpoint URL. Enter the full URL, including the port and scheme (http or https). For local access: http://<your_server_ip>:2283 (use the correct IP and port).
- Tap "Next" or "Connect".
- Enter your Immich login email and password.
- Tap "Login".
Configure Backup Settings:
- The app will likely guide you through initial backup settings. If not, find the backup settings (often under your profile icon -> Backup Settings or similar).
- Enable Backup: Toggle the switch to turn on automatic backup.
- Select Albums/Folders: Tap to choose which folders/albums on your phone you want to back up. Start with just your main Camera/DCIM folder for this test.
- Background Backup: Ensure this is enabled if you want uploads to happen automatically.
- Wi-Fi Only / Charging Only: Configure these based on your preference for this test (disabling them might trigger uploads faster, but be mindful of data/battery).
- Existing Assets: Decide if you want to upload photos already on your phone or just new ones. For testing, you might choose to upload existing ones (select a small album initially if possible).
Trigger Initial Mobile Upload:
- The app should start scanning the selected folders and begin uploading assets that aren't already backed up.
- You can usually monitor the upload progress within the app (look for an upload status indicator or section).
- Keep the app open initially to ensure the upload starts. Check if your phone is connected to the same network as the server if using local IP.
Verify Mobile Uploads in Web UI:
- Go back to the Immich web UI on your computer.
- Refresh the main timeline/photos view.
- You should start seeing photos from your phone appearing in the timeline as they are uploaded by the app.
- Note the timestamps – they should correspond to when the photos were taken, not when they were uploaded.

Outcome: You have successfully uploaded photos using both the web interface and the mobile app. You've configured the mobile app for backup and observed photos syncing from your phone to your self-hosted Immich server. You also practiced basic organization by creating a manual album. This covers the primary methods for populating your Immich library.

Leveraging Metadata and Search

A key advantage of digital photo management is the ability to find photos quickly. Immich leverages the metadata embedded within your media files and adds its own generated data (like AI tags) to provide powerful search capabilities.

The Importance of EXIF Data

EXIF (Exchangeable Image File Format) is a standard that specifies formats for images, sound, and ancillary tags used by digital cameras (including smartphones), scanners, etc. When you take a photo, your camera records information directly into the image file, such as:

Date and Time Taken: Crucial for chronological sorting and timeline views.
Camera Make and Model: Useful for filtering or finding photos from a specific device.
Camera Settings: Shutter speed, aperture, ISO, focal length (interesting for photographers).
GPS Coordinates: If location services were enabled on your camera/phone, the latitude and longitude where the photo was taken are embedded. Immich uses this for the Map view.
Image Resolution and Orientation.

Immich automatically reads this EXIF data during the upload process and stores relevant parts (like date taken, GPS) in its database, making it searchable. Maintaining accurate EXIF data (especially the "Date Taken") is vital for Immich to organize your library correctly.

How Immich Uses Metadata

Timeline: Primarily sorted by the "Date Taken" EXIF tag.
Map View: Plots photos on a world map using embedded GPS coordinates.
Information Panel: When viewing a photo, Immich displays available EXIF data (camera details, location, date, etc.).
Search Filters: Allows filtering searches based on dates, camera types, locations (if available).

Basic Search Functionality

The search bar in Immich (usually prominent at the top) allows for various types of queries:

Dates: Type specific dates ("December 25, 2023"), months ("August 2023"), or years ("2022").
Filenames: If you know part of a filename, you can search for it.
Locations: Search for places if photos have GPS data (e.g., "London," "Paris"). Immich might perform reverse geocoding (looking up place names from coordinates) to facilitate this.
File Types: Search for "videos," "motion photos," etc.
Recent Searches: Immich often remembers your recent searches for quick access.

Introduction to AI-Powered Search (Machine Learning)

This is where Immich truly shines and competes with cloud services. The immich-machine-learning container analyzes your photos to identify content:

Object/Scene Detection: It identifies common objects and scenes (e.g., "dog," "cat," "car," "beach," "mountains," "food"). These become searchable terms. You can often explore these tags in a dedicated "Explore" or "Things" section.
Facial Detection/Recognition:
- Detection: Identifies that a face is present in a photo.
- Recognition: Groups photos containing the same person together. You can then name these people (e.g., "Mom," "John Doe"), and search for photos containing them. This usually populates a "People" or "Faces" section.

How AI Search Works:

Analysis: When new photos are uploaded, they are queued for processing by the immich-machine-learning service.
Model Inference: The service uses pre-trained machine learning models to analyze the image content.
Tagging/Embedding: It generates tags (like "dog," "beach") or facial embeddings (mathematical representations of faces).
Database Storage: These generated tags and face data are stored in the Immich database, associated with the respective photos.
Search Indexing: The database is indexed to allow efficient searching based on these AI-generated terms.

When you search for "dog," Immich queries the database for all photos tagged with "dog" by the ML service. When you click on a person in the "People" section, it retrieves all photos linked to that person's facial recognition data.

This AI processing happens in the background and can take time, especially for large libraries or on systems with limited CPU/GPU resources.

Workshop Exploring Your Media

Goal: To practice using Immich's search capabilities, examine EXIF metadata, and observe the results of AI-based tagging (if ML is running).

Prerequisites:

A running Immich instance with some photos uploaded (ideally a mix of photos with different dates, some possibly containing GPS data, common objects, and people).
The Machine Learning container (immich-machine-learning) should be running (it is by default with the standard docker-compose.yml). Allow some time after upload for initial processing.

Steps:

Log in to Web UI: Access Immich and log in.
Basic Date Search:
- Go to the main Photos timeline view.
- Identify photos from a specific month or year that you uploaded.
- Go to the Search bar at the top.
- Type the month and year (e.g., "July 2023") or just the year (e.g., "2023").
- Observe how Immich filters the results to show only media matching that date range. Try searching for a specific day if you know one exists.
Examine EXIF Data:
- Click on any photo in your timeline or search results to view it larger.
- Look for an "Info" icon or button (often an 'i' in a circle) or a sidebar that displays details. Click it.
- Examine the information displayed:
  - Filename
  - Date Taken (this comes from EXIF)
  - Camera Make/Model (if available in EXIF)
  - Resolution
  - GPS Coordinates / Location (if available and processed)
  - Other EXIF details (aperture, ISO, etc.)
- Do this for a couple of different photos, perhaps one from your phone and one uploaded from your computer, to see how the available data might differ. If you have photos with GPS data, note the location shown.
Map View (if GPS data exists):
- Look for a "Map" or "Places" section in the left sidebar or main navigation. Click it.
- If any of your uploaded photos had GPS coordinates embedded in their EXIF data, you should see them plotted on a world map.
- Zoom in on locations to see thumbnails of the photos taken there. Click a thumbnail to view the photo.
AI Object/Tag Search:
- Go back to the Search bar.
- Think of common objects that might be in your photos (e.g., "car," "dog," "tree," "sky," "food," "computer").
- Type one of these terms into the search bar and press Enter.
- Immich should display photos that the machine learning service has identified as containing that object. Note: This depends on the ML service having processed the photos. If you just uploaded them, it might take time.
- Try searching for a few different common objects.
Explore AI Categories:
- Look for an "Explore" or "Search" section in the sidebar (distinct from the top search bar).
- Inside, you might find categories like "Things," "Places," etc.
- Click on "Things" (or similar). This should show you a grid of automatically detected categories based on the content of your photos. Click a category (e.g., "Animals," "Screenshots") to see the relevant photos.
Explore Faces (if populated):
- In the "Explore" or "Search" section, look for "People" or "Faces".
- If the ML service has detected faces and grouped them, you will see thumbnails of different individuals found in your photos.
- Click on a face group. Immich will show you all photos it believes contain that person.
- You can often add a name to a recognized face group (e.g., click "Add Name" or similar). Once named, you should be able to search for that person by name in the main search bar.

Outcome: You have practiced using various search methods in Immich, including date-based filtering, examining detailed EXIF metadata, visualizing photos on a map using GPS data, and leveraging the AI-powered search for objects and faces. This demonstrates how Immich helps you find and rediscover your memories efficiently.

3. Advanced Level Customization and Maintenance

This section delves into more complex aspects of managing your Immich instance, focusing on security, data integrity, performance, and leveraging its more advanced features. These steps are crucial for running a reliable and robust self-hosted photo management system long-term.

Reverse Proxy and HTTPS Setup

Running Immich directly exposed on its default port (e.g., 2283) is acceptable for local network access only. For secure access, especially over the internet, using a reverse proxy to enable HTTPS is highly recommended, if not essential.

Why Use a Reverse Proxy?

HTTPS/SSL Encryption: A reverse proxy can handle SSL/TLS termination. This means traffic between the user's browser/mobile app and the proxy is encrypted (HTTPS), protecting login credentials and photo data from eavesdropping, especially over public Wi-Fi or the internet. Immich itself might run on HTTP behind the proxy within your secure local network.
Single Access Point: If you host multiple web services on the same server, a reverse proxy can direct traffic based on the domain name (e.g., immich.yourdomain.com goes to Immich, files.yourdomain.com goes to a file-sharing app), allowing them all to run on the standard HTTPS port 443.
Improved Security: The proxy acts as a buffer, hiding the internal structure and ports of your Immich instance. Some proxies offer additional security features like rate limiting or web application firewalls (WAFs).
Custom Domain Names: Allows you to access Immich via an easy-to-remember domain name (like photos.my-family.net) instead of just an IP address and port. This is crucial for mobile app access from outside your home network.
Load Balancing (Advanced): For very high-traffic sites, proxies can distribute load, though this is less common for typical personal Immich instances.
Compression/Caching: Proxies can compress content (like Gzip) to speed up loading times and potentially cache static assets.

Common Reverse Proxy Options

Nginx Proxy Manager (NPM):
- Pros: User-friendly web interface for configuration, simplifies Let's Encrypt SSL certificate management, runs well in Docker. Excellent for users who prefer a GUI over manual config files.
- Cons: Another service to manage, might offer slightly less flexibility than manual Nginx/Caddy for complex scenarios.
Traefik:
- Pros: Highly dynamic, integrates tightly with Docker (can auto-configure based on container labels), built-in Let's Encrypt support. Popular in container-centric environments.
- Cons: Configuration (often via YAML or TOML files, or Docker labels) can have a steeper learning curve initially compared to NPM's GUI.
Caddy:
- Pros: Known for its extreme simplicity, automatic HTTPS by default (manages Let's Encrypt automatically with minimal config), simple configuration file (Caddyfile).
- Cons: Less feature-rich web UI compared to NPM (if any), newer than Nginx/Traefik but very capable.
Manual Nginx/Apache:
- Pros: Maximum flexibility and control, widely documented.
- Cons: Requires manual configuration file editing, manual setup of Let's Encrypt (e.g., using certbot). Steeper learning curve for beginners.

Conceptual Overview of Configuration

Regardless of the proxy chosen, the basic steps are similar:

DNS Setup: You need a domain name (e.g., yourdomain.com). In your DNS provider's settings, create an A record (or AAAA for IPv6) pointing a subdomain (e.g., immich.yourdomain.com) to the public IP address of your server where the reverse proxy is running.
Install Reverse Proxy: Set up your chosen reverse proxy (often as a Docker container itself). Ensure its ports 80 (for HTTP/Let's Encrypt validation) and 443 (for HTTPS) are forwarded through your firewall/router to the proxy server.
Configure Proxy Host/Site: Within the reverse proxy's configuration:
- Define the domain name (immich.yourdomain.com).
- Specify the forwarding target (backend): This should be the internal IP address (or Docker container name) and port where the Immich service (usually immich-proxy or immich-web from the docker-compose.yml) is listening. For example, if Immich's web service is immich-web listening on port 3001 within the Docker network, the target might be http://immich-web:3001. If accessing via host IP from another container/machine, it might be http://<immich_host_ip>:<immich_port>.
- Enable SSL/HTTPS: Configure the proxy to obtain and manage an SSL certificate (usually Let's Encrypt). Most modern proxies automate this.
- Additional Settings (Optional): Configure settings like Host header forwarding, WebSocket support (Immich might require this for real-time updates), HSTS (HTTP Strict Transport Security), etc. Consult Immich and your proxy's documentation for recommended settings.
Test Access: Try accessing https://immich.yourdomain.com. You should see the Immich login page, served over HTTPS with a valid certificate. Update your mobile app's Server Endpoint URL to use this new HTTPS address.

Workshop Securing Immich with Nginx Proxy Manager

Goal: To set up Nginx Proxy Manager (NPM) in Docker (if not already running) and configure it to serve your Immich instance securely over HTTPS using a custom domain name and a Let's Encrypt certificate.

Prerequisites:

A running Immich instance (accessible via http://<local_ip>:<port>).
Docker and Docker Compose installed.
A registered domain name (e.g., yourdomain.com).
Access to your domain's DNS provider settings.
Your server's public IP address (must be reachable from the internet).
Ports 80 and 443 forwarded from your router/firewall to the host machine where NPM will run. (This host can be the same or different from the Immich host, as long as they can communicate).

Steps:

Part 1: DNS Setup

Log in to DNS Provider: Access the control panel for your domain name registrar or DNS hosting service (e.g., Cloudflare, Namecheap, GoDaddy).
Create A Record: Navigate to the DNS management section. Create a new A record:
- Type: A
- Name/Host: Enter the subdomain you want to use for Immich (e.g., immich if your domain is yourdomain.com, resulting in immich.yourdomain.com). Some providers might require the full immich.yourdomain.com.
- Value/Points to: Enter the public IP address of the server where Nginx Proxy Manager will run.
- TTL (Time To Live): Leave as default or set to a low value (like 5 minutes) initially for faster propagation during testing.
Save Changes: Save the DNS record. DNS changes can take anywhere from a few minutes to several hours to propagate globally. You can use tools like dnschecker.org to verify propagation.

Part 2: Install Nginx Proxy Manager (if needed)

Create NPM Directory and Compose File: On the server where you want to run NPM (can be the same host as Immich):
```
mkdir ~/npm-data
cd ~/npm-data
nano docker-compose.yml
```
Paste NPM Docker Compose Configuration: Paste the following content into docker-compose.yml.
```
ser                                
```
Explanation: This defines two services: app (NPM itself) and db (its database). It This is a standard NPM setup. href="#__codelineno-14-1">version: '3.8' vices: app: image: 'jc21/nginx-proxy-manager:latest' container_name: 'npm-app' restart: unless-stopped ports: # Public HTTP Port: - '80:8080' # Public HTTPS Port: - '443:4443' # Admin Web Port: - '8181:81' # Map host port 8181 to container port 81 for admin UI volumes: - ./data:/data - ./letsencrypt:/etc/letsencrypt environment: # Set to 1 to allow columns in basic auth usernames DISABLE_IPV6: 'true' # Optional: uncomment if you have IPv6 issues db: image: 'jc21/mariadb-aria:latest' container_name: 'npm-db' restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: 'npm-db-password-please-change' # CHANGE THIS MYSQL_DATABASE: 'npm' MYSQL_USER: 'npm' MYSQL_PASSWORD: 'npm-db-user-password-please-change' # CHANGE THIS volumes: - ./data/mysql:/var/lib/mysql >volumes: data: letsencrypt: maps ports 80, 443 for proxied traffic and 8181 for the admin UI. Crucially, change the default MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD values to strong, unique passwords.
Save and Start NPM: Save the file (Ctrl+X, Y, Enter in nano) and start NPM:
```
# Make sure to change passwords in docker-compose.yml first!
docker compose up -d
docker compose ps
```
Expected Outcome: Both npm-app and npm-db containers should be running.

Part 3: Configure NPM

Access NPM Admin UI: Open your browser and navigate to http://<npm_server_ip>:8181. Replace <npm_server_ip> with the IP address of the host running NPM.
Initial Login: Log in with the default administrator credentials:
- Email: admin@example.com
- Password: changeme
- You will be immediately prompted to change these details. Update the email and set a strong password.
Add Proxy Host for Immich:
- Navigate to "Hosts" -> "Proxy Hosts".
- Click "Add Proxy Host".
- Details Tab:
  - Domain Names: Enter the full domain name you configured in DNS (e.g., immich.yourdomain.com).
  - Scheme: Select http (unless your Immich service itself is configured for HTTPS, which is uncommon behind a proxy).
  - Forward Hostname / IP: Enter the IP address or Docker container name of your Immich service.
    - If NPM and Immich are on the same Docker host and same custom Docker network: Use the Immich service name from its docker-compose.yml (e.g., immich-server or immich-web or potentially immich-proxy if it exists in the compose file). Check the Immich compose file.
    - If NPM and Immich are on different hosts (or different Docker networks without connection): Use the local IP address of the host running Immich (e.g., 192.168.1.10).
  - Forward Port: Enter the port that the Immich service is listening on. Check Immich's docker-compose.yml. This is not the externally mapped port (like 2283) but the internal port (often 3001 for immich-server or 80/8080 if using the immich-proxy service). Let's assume 3001 for immich-server.
  - Enable Block Common Exploits: Recommended.
  - Enable Websockets Support: Important! Enable this, as Immich often uses WebSockets for real-time updates.
- SSL Tab:
  - SSL Certificate: Select "Request a new SSL Certificate".
  - Enable Force SSL: Recommended. Forces all traffic to use HTTPS.
  - Enable HTTP/2 Support: Recommended for performance.
  - Email Address for Let's Encrypt: Enter your valid email address (used for certificate expiry notifications).
  - Agree to Let's Encrypt Terms: Check the box.
- Save: Click the "Save" button. NPM will now attempt to contact Let's Encrypt to obtain a certificate for your domain. This requires ports 80/443 to be correctly forwarded and your DNS A record to have propagated.
Verify Certificate and Access:
- Wait a minute or two. The status icon next to your proxy host entry should turn green (indicating a valid certificate). If it shows errors, double-check DNS propagation, port forwarding, and the firewall on your NPM host. Check the NPM container logs (docker logs npm-app) for details.
- Once successful, open a new browser tab and navigate to https://immich.yourdomain.com (using HTTPS and your domain).
- Expected Outcome: You should see the Immich login page, served securely over HTTPS with a valid lock icon in your browser's address bar.
Update Mobile App: If using the Immich mobile app, update the "Server Endpoint URL" in the app's settings to https://immich.yourdomain.com.

Outcome: You have successfully configured Nginx Proxy Manager to act as a reverse proxy for Immich, enabling secure HTTPS access via a custom domain name with an automatically managed Let's Encrypt SSL certificate. This significantly enhances the security and usability of your self-hosted Immich instance, especially for external access.

Backup and Recovery Strategies

Your photo and video library represents irreplaceable memories. Implementing a robust backup strategy for your Immich instance is not optional; it's critical. A failure (hardware, software corruption, accidental deletion) without backups can lead to permanent data loss.

What Needs Backing Up?

A complete Immich backup requires saving several distinct components:

Immich Database:
- What it contains: All metadata – user accounts, passwords (hashed), album definitions, photo-to-album links, AI tags, face recognition data, file paths, settings, sharing information, etc.
- Why it's critical: Losing the database means losing all organization and metadata. Your photo files would still exist, but Immich would have no knowledge of them or how they were organized. Recovery without a database backup is extremely difficult, essentially requiring a re-import and losing all albums, tags, users (except admin), etc.
- Location: Managed by the PostgreSQL container (e.g., in the /var/lib/postgresql/data volume mapped in docker-compose.yml).
Media Files (Upload Location):
- What it contains: Your original photo and video files as uploaded to Immich. Potentially also includes generated thumbnails and transcoded videos depending on configuration and volume mapping.
- Why it's critical: These are your actual memories.
- Location: The directory specified by UPLOAD_LOCATION in your .env file (e.g., /mnt/data/immich-photos). You must back up this entire directory.
Configuration Files:
- What they contain: Settings required to recreate your Immich environment.
- Why they're critical: Needed for smooth restoration and ensuring the instance runs with the same parameters.
- Files:
  - docker-compose.yml: Defines the services, volumes, and networks.
  - .env: Contains crucial settings like database credentials, upload location path, ports, API keys, etc.
(Optional but Recommended) Docker Volumes:
- What they contain: Besides the primary upload location (which you back up directly), Docker might manage other named volumes for things like generated thumbnails, configuration caches, etc., especially if not explicitly mapped to host paths in docker-compose.yml. Backing up persistent named volumes ensures a faster recovery, avoiding regeneration time. Find these using docker volume ls.

Backup Methods

A good strategy involves backing up the database and files separately but consistently.

1. Database Backup (PostgreSQL)

Method: Use the pg_dump utility. This command connects to the running PostgreSQL database and creates a logical backup (a SQL script or archive file) containing the database structure and data.

Command (Run from the host machine):

# Identify your PostgreSQL container name (e.g., 'immich_database', 'npm-db' if shared)
# Check your immich docker-compose.yml, default is likely 'immich-database'
DB_CONTAINER_NAME="immich-database"

# Get database connection details from your .env file
# Ensure you source the .env or manually provide these:
# DB_USERNAME=$(grep POSTGRES_USER .env | cut -d '=' -f2) # Or the specific IMMICH_DB_USERNAME
# DB_NAME=$(grep POSTGRES_DB .env | cut -d '=' -f2)
# DB_PASSWORD=$(grep POSTGRES_PASSWORD .env | cut -d '=' -f2) # Or IMMICH_DB_PASSWORD

# Example values (replace with your actual values from .env):
DB_USERNAME="immich"
DB_NAME="immich"
DB_PASSWORD="your_strong_db_password" # The password for the 'immich' user

# Define backup file path and name
BACKUP_DIR="/path/to/your/backups/immich-db"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="$BACKUP_DIR/immich_db_backup_$TIMESTAMP.sql"

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Execute pg_dump inside the container
docker exec -t "$DB_CONTAINER_NAME" pg_dump -U "$DB_USERNAME" -d "$DB_NAME" -W > "$BACKUP_FILE"
# Note: -W might prompt for password interactively.
# For scripting, you might need to set PGPASSWORD environment variable:
# docker exec -t -e PGPASSWORD="$DB_PASSWORD" "$DB_CONTAINER_NAME" pg_dump -U "$DB_USERNAME" -d "$DB_NAME" -Fc -f "/tmp/db_backup.dump" # -Fc for custom format
# docker cp "$DB_CONTAINER_NAME:/tmp/db_backup.dump" "$BACKUP_DIR/immich_db_backup_$TIMESTAMP.dump"
# docker exec -t "$DB_CONTAINER_NAME" rm "/tmp/db_backup.dump"

# Recommended: Use custom format (-Fc) for more flexibility
BACKUP_FILE_CUSTOM="$BACKUP_DIR/immich_db_backup_$TIMESTAMP.dump"
docker exec -t -e PGPASSWORD="$DB_PASSWORD" "$DB_CONTAINER_NAME" pg_dump -U "$DB_USERNAME" -d "$DB_NAME" -Fc > "$BACKUP_FILE_CUSTOM"

echo "Database backup created at $BACKUP_FILE_CUSTOM"

Explanation: We use docker exec to run pg_dump inside the running PostgreSQL container. We pass the username (-U) and database name (-d). Using -Fc creates a compressed, custom-format backup which is generally preferred over plain SQL (.sql). The output is redirected to a timestamped file on the host. Setting PGPASSWORD avoids interactive password prompts, suitable for scripts.

2. File System Backup (Upload Location & Config)

Method: Use file synchronization tools like rsync or dedicated backup software like restic, BorgBackup, or Duplicati. rsync is simple and effective for creating mirrored copies. restic/BorgBackup offer deduplication, encryption, and snapshot capabilities, making them more efficient for long-term versioned backups, especially to remote storage.

Using rsync (Simple Mirror):

# Define source directories
IMMICH_CONFIG_DIR="~/immich-config" # Where your .env and docker-compose.yml are
IMMICH_UPLOAD_DIR="/mnt/data/immich-photos" # Your UPLOAD_LOCATION

# Define backup destination
BACKUP_BASE_DIR="/path/to/your/backups/immich-files"

# Create backup directories
mkdir -p "$BACKUP_BASE_DIR/config"
mkdir -p "$BACKUP_BASE_DIR/uploads"

# Sync config files
rsync -avh --delete "$IMMICH_CONFIG_DIR/" "$BACKUP_BASE_DIR/config/"

# Sync media files (uploads)
# Use --delete to remove files from backup if deleted from source
rsync -avh --delete "$IMMICH_UPLOAD_DIR/" "$BACKUP_BASE_DIR/uploads/"

echo "File backup completed to $BACKUP_BASE_DIR"

Explanation: rsync -avh copies files recursively (-a), verbosely (-v), preserving permissions/timestamps, and using human-readable sizes (-h). --delete ensures that files deleted from the source are also removed from the backup destination, keeping it a mirror. Remove --delete if you want the backup to be purely additive (retaining deleted files in the backup).

Important Considerations

Consistency: Ideally, stop the Immich containers (docker compose stop) before taking backups, especially the database backup, to ensure data consistency. However, pg_dump is designed to create consistent snapshots even on a live database. Backing up files while Immich is writing new uploads might result in minor inconsistencies (e.g., a photo present in the filesystem backup but its corresponding database entry missing if the DB backup was taken just before). For critical consistency, stop the application. For most home uses, backing up live might be acceptable, understanding the small risk.
Frequency: How often should you back up? Consider how much data you can afford to lose. For active libraries, daily backups are recommended.
Retention: Keep multiple backup versions (e.g., daily for a week, weekly for a month, monthly for a year). Tools like restic or Borg manage retention policies easily. Simple rsync mirroring only keeps the latest state unless you manually create timestamped target directories.
The 3-2-1 Rule: Have at least 3 copies of your data, on 2 different media types, with 1 copy off-site.
- Copy 1: Your live Immich instance.
- Copy 2: Local backup (e.g., on a separate USB drive or NAS attached to your server).
- Copy 3: Off-site backup (e.g., another physical location, encrypted cloud storage like Backblaze B2, AWS S3). This protects against local disasters (fire, theft, flood). Tools like restic or Duplicati excel at encrypted backups to cloud targets.
Testing Recovery: Regularly test restoring your backups to a separate test environment. Backups are useless if they cannot be restored successfully.

Recovery Process Overview

Set up New Host (if needed): Install OS, Docker, Docker Compose.
Restore Configuration: Copy your backed-up docker-compose.yml and .env file to the appropriate directory (e.g., ~/immich-config).
Restore Upload Location: Copy the contents of your backed-up upload location (e.g., $BACKUP_BASE_DIR/uploads/) to the path specified in UPLOAD_LOCATION in the restored .env file on the new host. Ensure permissions are correct.
Prepare Database: Start only the PostgreSQL container (e.g., docker compose up -d immich-database).

Restore Database: Use pg_restore (the counterpart to pg_dump) to load the backup file into the newly started database container.

DB_CONTAINER_NAME="immich-database"
DB_USERNAME="immich"
DB_NAME="immich"
DB_PASSWORD="your_strong_db_password"
RESTORE_FILE="/path/to/your/backups/immich-db/immich_db_backup_YYYYMMDD_HHMMSS.dump" # Your chosen backup file

# Copy backup file into container temporarily
docker cp "$RESTORE_FILE" "$DB_CONTAINER_NAME:/tmp/restore.dump"

# Execute pg_restore inside the container
# Use --clean to drop existing objects before restoring
# Use -d postgres first if the target immich DB doesn't exist yet to create it
docker exec -t -e PGPASSWORD="$DB_PASSWORD" "$DB_CONTAINER_NAME" pg_restore -U "$DB_USERNAME" -d "$DB_NAME" --clean --if-exists "/tmp/restore.dump"

# Or, if creating the DB first:
# docker exec -t -e PGPASSWORD="$YOUR_ROOT_DB_PASSWORD" "$DB_CONTAINER_NAME" createdb -U "$YOUR_ROOT_DB_USER" "$DB_NAME"
# docker exec -t -e PGPASSWORD="$DB_PASSWORD" "$DB_CONTAINER_NAME" pg_restore -U "$DB_USERNAME" -d "$DB_NAME" "/tmp/restore.dump"

# Remove temporary file
docker exec -t "$DB_CONTAINER_NAME" rm "/tmp/restore.dump"

echo "Database restore completed."

Start All Immich Services: Run docker compose up -d.
Verify: Access Immich via the web UI and check if users, photos, albums, and settings are restored correctly.

Workshop Implementing a Basic Backup Plan

Goal: To create simple shell scripts for backing up the Immich database and the photo library/configuration files using pg_dump and rsync to a local backup directory.

Prerequisites:

A running Immich instance.
Know the container name for your PostgreSQL service (e.g., immich-database).
Know the username, password, and database name used by Immich (from .env).
Know the path to your UPLOAD_LOCATION.
Know the path to your Immich configuration files (docker-compose.yml, .env).
A separate directory on your server designated for backups (e.g., /mnt/backups/immich). Ensure it exists and you have write permissions.

Steps:

Create Backup Directory:

BACKUP_ROOT="/mnt/backups/immich" # IMPORTANT: Change if needed
sudo mkdir -p "$BACKUP_ROOT/database"
sudo mkdir -p "$BACKUP_ROOT/files/config"
sudo mkdir -p "$BACKUP_ROOT/files/uploads"
sudo chown -R $USER:$USER "$BACKUP_ROOT" # Ensure your user owns it
echo "Backup directories created under $BACKUP_ROOT"

Create Database Backup Script:

Create a new script file: nano ~/backup_immich_db.sh

Paste the following content, carefully replacing placeholder values with your actual Immich database details and backup path:

#!/bin/bash

# --- Configuration ---
DB_CONTAINER_NAME="immich-database" # Verify this matches your compose file
DB_USER="immich"            # Verify from .env (e.g., IMMICH_DB_USERNAME or POSTGRES_USER)
DB_NAME="immich"            # Verify from .env (e.g., IMMICH_DB_DATABASE or POSTGRES_DB)
DB_PASSWORD="YOUR_IMMICH_DB_PASSWORD" # !! REPLACE WITH YOUR ACTUAL PASSWORD from .env !!
BACKUP_DIR="/mnt/backups/immich/database" # Your DB backup destination

# --- Script Logic ---
echo "Starting Immich database backup..."

# Create timestamp
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="$BACKUP_DIR/immich_db_$TIMESTAMP.dump"

# Execute pg_dump using custom format (-Fc)
echo "Dumping database '$DB_NAME' from container '$DB_CONTAINER_NAME'..."
docker exec -t \
  -e PGPASSWORD="$DB_PASSWORD" \
  "$DB_CONTAINER_NAME" \
  pg_dump -U "$DB_USER" -d "$DB_NAME" -Fc > "$BACKUP_FILE"

# Check exit status
if [ $? -eq 0 ]; then
  echo "Database backup successful: $BACKUP_FILE"
  # Optional: Clean up old backups (e.g., keep last 7)
  echo "Cleaning up old database backups (keeping last 7)..."
  ls -tp "$BACKUP_DIR" | grep '\.dump$' | tail -n +8 | xargs -I {} rm -- "$BACKUP_DIR/{}"
else
  echo "ERROR: Database backup failed!"
  rm -f "$BACKUP_FILE" # Remove potentially incomplete file
  exit 1
fi

echo "Database backup script finished."
exit 0

Save the script (Ctrl+X, Y, Enter).
Make it executable: chmod +x ~/backup_immich_db.sh

Create File Backup Script:

Create a new script file: nano ~/backup_immich_files.sh

Paste the following content, carefully replacing placeholder values with your actual Immich paths:

#!/bin/bash

# --- Configuration ---
CONFIG_SOURCE_DIR="$HOME/immich-config" # !! REPLACE with path to your docker-compose.yml/.env !!
UPLOAD_SOURCE_DIR="/mnt/data/immich-photos" # !! REPLACE with your UPLOAD_LOCATION from .env !!
BACKUP_DEST_DIR="/mnt/backups/immich/files" # Your file backup destination base

# --- Script Logic ---
echo "Starting Immich file backup..."

# Backup config files
echo "Backing up configuration files from $CONFIG_SOURCE_DIR..."
rsync -avh --delete "$CONFIG_SOURCE_DIR/" "$BACKUP_DEST_DIR/config/"
if [ $? -ne 0 ]; then
    echo "ERROR: Configuration file backup failed!"
    # Decide if you want to exit or continue with uploads backup
    # exit 1
else
    echo "Configuration backup successful."
fi

# Backup upload/media files
echo "Backing up media files from $UPLOAD_SOURCE_DIR..."
rsync -avh --delete "$UPLOAD_SOURCE_DIR/" "$BACKUP_DEST_DIR/uploads/"
if [ $? -ne 0 ]; then
    echo "ERROR: Media file backup failed!"
    exit 1
else
    echo "Media backup successful."
fi

echo "File backup script finished."
exit 0

Save the script (Ctrl+X, Y, Enter).
Make it executable: chmod +x ~/backup_immich_files.sh

Run the Backup Scripts:

echo "Running database backup..."
~/backup_immich_db.sh

echo -e "\nRunning file backup..."
~/backup_immich_files.sh

Verify Backups:
- Check the contents of your backup directories:
```
ls -lh "$BACKUP_ROOT/database"
ls -lh "$BACKUP_ROOT/files/config"
ls -lh "$BACKUP_ROOT/files/uploads" # Should mirror your UPLOAD_LOCATION
```
- Expected Outcome: You should see a .dump file in the database directory and mirrored copies of your config files and uploaded media in the respective file backup directories. The database backup script should also have cleaned up older backups if you ran it multiple times, keeping only the last 7.
(Optional) Automate with Cron: To run these backups automatically (e.g., daily), you can add them to your user's crontab:
- Edit crontab: crontab -e
- Add lines like these to run the backups every day at, say, 3:00 AM and 3:30 AM respectively:
```
# Example: Run backups daily at 3:00 AM and 3:30 AM
0 3 * * * /bin/bash /home/YOUR_USERNAME/backup_immich_db.sh >> /home/YOUR_USERNAME/immich_db_backup.log 2>&1
30 3 * * * /bin/bash /home/YOUR_USERNAME/backup_immich_files.sh >> /home/YOUR_USERNAME/immich_files_backup.log 2>&1
```
  Explanation: Replace YOUR_USERNAME with your actual username. >> ... 2>&1 redirects both standard output and errors to log files in your home directory. Adjust the schedule (0 3 * * *) as needed. Save the crontab.

Outcome: You have created and tested basic backup scripts for your Immich database and files using standard Linux tools. You understand the components involved and have a foundation for automating these backups. Remember to implement the off-site part of the 3-2-1 rule for true data safety!

Performance Tuning and Monitoring

As your Immich library grows or if you run it on resource-constrained hardware, performance might become a concern. Understanding potential bottlenecks and how to monitor the system is key to maintaining a smooth experience.

Hardware Considerations

CPU: Crucial for general responsiveness, database operations, and especially background tasks like thumbnail generation and machine learning (object detection, face recognition). A modern multi-core CPU (4+ cores recommended) is beneficial. ML tasks are CPU-intensive unless you have GPU acceleration configured (which is a more advanced setup).
RAM: Immich components (server, database, ML, Redis) consume memory. 4GB is often cited as a minimum, but 8GB or even 16GB+ is recommended for larger libraries and smoother operation, especially with ML enabled. Insufficient RAM leads to swapping to disk, drastically reducing performance.
Storage Speed: The speed of the disk where your UPLOAD_LOCATION and database volume reside significantly impacts performance.
- Uploads/Imports: Faster disk writes speed up imports.
- Thumbnail Generation: Involves reading originals and writing thumbnails; benefits from fast read/write.
- Database: Database operations (queries for search, loading albums) benefit greatly from fast random I/O. Using an SSD (SATA or preferably NVMe) for the Docker volumes (especially database and config/cache volumes) is highly recommended over traditional HDDs. Storing the main photo library (UPLOAD_LOCATION) on a large HDD is acceptable, but performance-critical components benefit most from SSDs.
Network: A fast local network (Gigabit Ethernet) improves upload speeds from devices on the LAN and responsiveness of the web UI/apps.

Monitoring Container Resources

Docker provides built-in tools to monitor the resource consumption of your containers.

docker stats: Provides a real-time stream of CPU usage, memory usage, network I/O, and disk I/O for all running containers (or specified ones).
```
# Monitor all containers managed by the current compose file
docker compose stats

# Monitor specific services
docker compose stats immich-server immich-machine-learning database

# Monitor all running containers on the system
docker stats
```
Usage: Run this command while performing actions in Immich (e.g., uploading photos, scrolling the timeline, running a search) to see which services are using the most resources. High CPU usage on immich-microservices or immich-machine-learning indicates background job processing. High CPU/RAM on database indicates heavy querying. High usage on immich-server indicates API load.
docker logs: Checking container logs can reveal errors or specific activities.
```
docker compose logs -f immich-microservices # Follow logs in real-time
docker compose logs --tail 50 immich-server # Show last 50 lines
```
Usage: Look for errors, warnings, or messages indicating which jobs are running (e.g., "generating thumbnail," "detecting objects").

Understanding Background Jobs

Immich relies heavily on background jobs processed by the immich-microservices and immich-machine-learning containers. These jobs run asynchronously after you upload media or trigger certain actions.

Thumbnail Generation: Creates different sized previews. Can be I/O and somewhat CPU intensive initially for large uploads.
Metadata Extraction: Reads EXIF data. Usually quick.
Video Transcoding: Converts videos for web playback. Very CPU intensive.
Object/Scene Recognition (ML): Analyzes image content. CPU intensive (or GPU if configured).
Facial Detection/Recognition (ML): Finds and compares faces. CPU intensive (or GPU).
Reverse Geocoding: Looks up place names from GPS coordinates. Requires network access.

These jobs run in queues managed by Redis. Performance bottlenecks can occur if the job queues grow faster than the workers can process them, often due to insufficient CPU or RAM.

Adjusting Concurrency Settings (If Available)

Immich's configuration (primarily through the .env file) may offer variables to control the concurrency or behavior of background jobs. Check the official Immich documentation or the example.env file for variables like:

IMMICH_MACHINE_LEARNING_WORKERS: Number of parallel workers for ML tasks.
IMMICH_MICROSERVICES_WORKERS: Number of parallel workers for microservices tasks.
Variables controlling thumbnail quality/formats.

Caution: Increasing worker counts consumes more CPU and RAM. Adjust these carefully based on your hardware capabilities and monitoring results. Setting them too high on underpowered hardware can worsen performance due to resource contention.

Database Maintenance (Conceptual)

Like any database, PostgreSQL benefits from periodic maintenance:

VACUUM: Reclaims storage occupied by dead tuples (rows left behind after updates or deletes). PostgreSQL has an autovacuum daemon, but manual VACUUM (especially VACUUM FULL, which requires downtime) can sometimes be beneficial, although less frequently needed with modern PostgreSQL versions and autovacuum tuning.
ANALYZE: Updates statistics about table contents, which the query planner uses to choose efficient execution plans. Autovacuum usually runs ANALYZE as well.
Indexing: Immich's developers define necessary indexes. However, if you experience slow searches for specific, frequent queries, analyzing those queries (EXPLAIN ANALYZE) might reveal opportunities for custom indexes (an advanced topic requiring SQL knowledge).

Routine maintenance is often handled automatically, but being aware of these concepts helps in diagnosing persistent database performance issues.

Troubleshooting Performance Issues

Monitor: Use docker stats to identify the resource-constrained service(s).
Check Logs: Look for errors or clues in docker logs.
Check Background Job Queues (Advanced): Tools exist to inspect Redis queues, which can show if jobs are piling up. Immich might offer admin UI insights into job status.
Hardware Upgrade: If consistently hitting CPU, RAM, or I/O limits, upgrading hardware might be the only solution. Prioritize SSDs for Docker volumes/database and sufficient RAM.
Adjust Concurrency: Experiment with lowering worker counts in .env if resource exhaustion is suspected.
Disable Heavy Features: Temporarily disable ML features if they overload your system, to isolate the issue.
Database Tuning (Advanced): Consult PostgreSQL documentation for tuning parameters (e.g., shared_buffers, work_mem), but change defaults cautiously.

Workshop Monitoring Immich Performance

Goal: To use docker stats to observe Immich's resource usage during common operations like uploading and background processing.

Prerequisites:

A running Immich instance.
Access to the server's terminal where Immich is running via Docker Compose.
Ability to trigger uploads either via the web UI or mobile app.

Steps:

Open Two Terminals:
- Connect to your Immich server via SSH or open two terminal windows/tabs on the server desktop.
- Terminal 1: Navigate to your Immich configuration directory (where docker-compose.yml resides).
```
cd ~/immich-config # Or your installation directory
```
- Terminal 2: Will be used for observation.
Start Monitoring in Terminal 2:
- Run docker stats or docker compose stats to get a baseline view of resource usage when Immich is relatively idle.
```
# Option 1: Monitor only Immich containers
docker compose stats

# Option 2: Monitor all containers on the system
# docker stats
```
- Observe: Note the typical CPU (%) and Memory Usage for immich-server, immich-microservices, immich-machine-learning, database, and redis. They should be relatively low when idle (though the database might have some base memory usage).
Trigger Web Upload in Terminal 1 / Browser:
- Go to the Immich web UI in your browser.
- Prepare a small batch of photos (e.g., 10-20 moderate-sized JPEGs) for upload.
- Click "Upload" and select the photos.
- Switch quickly to Terminal 2.
- Observe docker stats Output:
  - You'll likely see increased Network I/O as files are transferred.
  - immich-server CPU and memory usage might increase as it handles the API requests and initial processing.
  - Shortly after the upload completes, you should see immich-microservices CPU usage spike significantly as it starts generating thumbnails and extracting metadata.
  - If ML features are enabled, immich-machine-learning CPU usage will also spike (potentially after immich-microservices) as it analyzes the new images. This may last longer than thumbnail generation.
  - database usage might increase moderately as metadata and tags are written.
  - redis usage might show brief spikes as jobs are queued and processed.
Trigger Mobile Upload (Optional):
- If your mobile app is configured, take a few new photos on your phone.
- Ensure the app is allowed to upload (check Wi-Fi/charging settings if enabled).
- Observe docker stats in Terminal 2: You should see a similar pattern as the web upload, potentially starting with immich-server handling the incoming connection, followed by spikes in immich-microservices and immich-machine-learning.
Trigger Search / Heavy Browsing:
- Wait for the background processing from the uploads to subside (CPU usage on microservices/ML should decrease).
- In the web UI, perform some actions:
  - Scroll rapidly through your main photo timeline.
  - Perform an AI search (e.g., search for "car" or a person's name).
  - Open an album with many photos.
- Observe docker stats in Terminal 2:
  - immich-server CPU/memory might increase to handle API requests.
  - database CPU/memory might spike significantly during complex searches or when loading large data sets.
  - immich-web or the frontend service might show some CPU usage for rendering (less likely to be a bottleneck).
Analyze Observations:
- Which service(s) used the most CPU during uploads? (Likely microservices and machine-learning).
- Which service(s) used the most CPU/Memory during search/browsing? (Likely server and database).
- Did any service approach its memory limit (if one is set in compose)?
- Was the CPU consistently maxed out during background processing?

Outcome: By using docker stats, you have observed the dynamic resource consumption of different Immich components during various activities. You can now better identify which parts of the system are most resource-intensive under different loads (upload processing vs. user interaction). This knowledge is the first step in diagnosing performance bottlenecks and making informed decisions about hardware resources or configuration tuning.

Understanding and Customizing Machine Learning Features

Immich's machine learning (ML) capabilities for image classification (tagging objects/scenes) and facial recognition are powerful features that significantly enhance searchability and organization, bringing it closer to commercial cloud offerings. Understanding how these work and their implications is important for advanced users.

Overview of ML Tasks

Image Classification/Tagging:
- Goal: To identify objects, scenes, or concepts within an image and assign relevant tags (e.g., "dog," "beach," "car," "portrait," "screenshot").
- How: Uses a pre-trained deep learning model (often a Convolutional Neural Network - CNN like CLIP or ResNet variants). The image is fed into the model, which outputs probabilities for various known classes. Immich stores tags exceeding a certain confidence threshold.
- Benefit: Enables searching for photos based on their content (e.g., find all "beach" photos). Populates the "Explore" -> "Things" section.
Facial Detection:
- Goal: To locate human faces within an image, determining their bounding box (position and size).
- How: Uses specialized models trained to identify facial features.
- Benefit: A prerequisite for facial recognition. Allows Immich to know where faces are in photos.
Facial Recognition (Clustering & Identification):
- Goal: To determine if faces detected in different photos belong to the same person.
- How:
  - Embedding: For each detected face, a specialized facial recognition model generates a "facial embedding" – a compact numerical representation (a vector) that captures the unique characteristics of that face.
  - Clustering: Immich compares these embeddings. Faces with similar embeddings (closer together in the high-dimensional vector space) are grouped into clusters, each representing a unique individual.
  - Identification: When you assign a name to a cluster (a person), Immich stores this association. You can then search by name, and Immich retrieves all photos containing faces belonging to that named cluster.
- Benefit: Automatically groups photos of the same person, populates the "People" section, allows searching by name.

Processing Workflow

When new media is uploaded, it's added to job queues (managed by Redis).
The immich-machine-learning container picks up jobs from these queues.
It loads the necessary ML models (these might be downloaded on first use or included in the Docker image).
It runs the models on the image/video data (inference).
The results (tags, face coordinates, face embeddings) are sent back to the immich-server to be stored in the PostgreSQL database, linked to the corresponding media asset.

Hardware Requirements and Performance

CPU: ML inference, especially for complex models, is computationally expensive. Without a dedicated GPU, these tasks rely heavily on the CPU. Processing a large backlog of photos can take significant time (hours or even days) depending on the CPU speed and number of cores allocated to the ML container.
GPU Acceleration (Advanced): Immich (and the underlying ML libraries) often supports using NVIDIA GPUs (via CUDA) or potentially other accelerators (like Intel Quick Sync Video for certain tasks, though less common for inference models) to drastically speed up ML processing. Configuring GPU passthrough to the Docker container requires specific drivers, Docker runtime configuration (e.g., nvidia-docker), and potentially custom Immich ML images built with GPU support. This is an advanced setup but can reduce processing times from hours to minutes.
RAM: ML models need to be loaded into memory. The specific models used by Immich determine the RAM requirements for the immich-machine-learning container. Insufficient RAM will prevent models from loading or cause poor performance. Check Immich documentation for recommended RAM for ML features.

Configuration Options (.env)

Your .env file may contain variables to control ML behavior:

IMMICH_MACHINE_LEARNING_ENABLED: Master switch to turn ML features on/off.
IMMICH_MACHINE_LEARNING_URL: The internal URL the server uses to communicate with the ML container (e.g., http://immich-machine-learning:3003).
Variables to select specific models (e.g., for classification or face recognition) if Immich offers choices. Different models have varying accuracy, speed, and resource requirements.
Threshold settings (e.g., minimum confidence score for a tag to be applied).
Worker counts (IMMICH_MACHINE_LEARNING_WORKERS) as discussed previously.

Consult the example.env file and official Immich documentation for the most current and relevant configuration variables.

Privacy Implications

Local Processing: By default, Immich's standard ML container performs all analysis locally on your server using the downloaded models. Your photos are not sent to external cloud services for analysis (unless you explicitly configure Immich to use an external ML API, which is not the default setup).
Facial Recognition Data: Facial embeddings and the links between faces and names are stored in your local database. This is sensitive data. Securing access to your Immich instance and its database backups is crucial.
Model Provenance: The models themselves are typically pre-trained on large, diverse datasets. Understanding the potential biases within these datasets (which can affect recognition accuracy across different demographics) is important, though usually beyond the end-user's control.

Managing ML Features

Enabling/Disabling: You can toggle ML features via the .env file (requires restarting the containers: docker compose down && docker compose up -d).
Triggering Re-scans: Immich usually provides administrative options to re-scan the library for specific ML tasks (e.g., re-detect faces, re-classify images) if models are updated or if initial processing failed. This is found in the Administration -> Jobs section.
Managing People/Tags: The web UI allows you to name recognized people, merge face clusters that belong to the same person, correct misidentified tags (if the interface allows), and hide specific results.

Workshop Exploring ML Features

Goal: To observe the results of Immich's ML processing, explore detected tags and recognized faces, and understand how to trigger ML-related jobs.

Prerequisites:

A running Immich instance with the immich-machine-learning container active.
A library containing a variety of photos: include pictures with common objects (animals, vehicles, food), scenes (beach, city, nature), and people (ideally multiple photos of the same individuals).
Sufficient time has passed since upload for ML jobs to have processed at least some of the library. Processing time varies greatly with library size and hardware.

Steps:

Log in to Web UI: Access your Immich instance.
Explore "Things" (Object/Scene Tags):
- Navigate to the "Explore" or "Search" section in the sidebar.
- Click on the "Things" (or similarly named) category.
- Observe: You should see a grid or list of tags automatically generated from your photos (e.g., "Sky," "Trees," "Cats," "Cars," "Buildings," "Food"). The tags present depend entirely on the content of your library.
- Click on a few different tags. Verify that the photos displayed generally match the tag selected. Note that accuracy isn't always 100%.
Explore "People" (Facial Recognition):
- In the same "Explore" / "Search" section, click on "People".
- Observe: If faces were detected and clustered, you will see thumbnails representing different individuals found across your photos. Each thumbnail represents a cluster of similar faces.
- Click on one of the face thumbnails. Immich will display all photos it believes contain this person.
- Assign a Name: Find the option to name this person (e.g., a text box saying "Who is this?" or an "Add Name" button). Type a name (e.g., "Alice") and save it.
- Repeat for another distinct person if available.
Search by AI Tags and People:
- Go to the main Search bar at the top.
- Search by Tag: Type one of the tags you saw in the "Things" section (e.g., "beach") and press Enter. Verify the results match.
- Search by Name: Type the name you assigned to a person (e.g., "Alice") and press Enter. Verify that photos containing that person are displayed.
Examine ML Info on a Photo:
- Open a photo that contains recognized objects or people.
- Open the "Info" panel for that photo.
- Observe: Scroll through the information. In addition to EXIF data, you might see a section listing the AI tags assigned to this photo (e.g., "Tags: Outdoors, Nature, Mountain") and thumbnails/names of recognized people in that specific photo.
Explore Administration Jobs (Optional Observation):
- Navigate to "Administration" -> "Jobs".
- Observe: This section typically shows the status of background tasks. Look for job types related to:
  - Metadata Extraction
  - Thumbnail Generation
  - Object Tagging / Image Classification
  - Facial Detection / Facial Recognition
- You might see counts of pending, active, completed, or failed jobs. This gives insight into whether ML processing is ongoing or complete.
- Look for buttons that might allow you to manually trigger jobs for the entire library (e.g., "Detect Faces," "Classify Images"). Do not trigger these unless necessary, as they can take a long time. Just note their existence.

Outcome: You have explored the practical results of Immich's background ML processing. You've seen automatically generated content tags, grouped faces recognized as the same person, named individuals, and used this AI-generated information for searching. You also know where to look in the administration panel to get insights into the status of these background jobs. This provides a deeper appreciation for how ML enhances the photo management experience in Immich.

Conclusion

Throughout this guide, we've journeyed from the fundamental concepts of Immich to its installation, daily usage, and advanced management. You've learned how Immich uses a microservices architecture, how to install it using Docker Compose, manage users and sharing permissions, upload media via web and mobile, and leverage its powerful metadata and AI-driven search capabilities. We've also covered crucial advanced topics like securing your instance with HTTPS via a reverse proxy, establishing a robust backup and recovery strategy, monitoring performance, and understanding the intricacies of its machine learning features.

Immich represents a significant step forward in self-hosted photo management, offering a compelling alternative to cloud-based services by prioritizing privacy, control, and data ownership without heavily compromising on features. Its active development means it's constantly evolving, bringing new capabilities and refinements.

Where to Go Next?

Explore the Immich CLI: For power users, the command-line interface offers advanced options for bulk import, scripting, and management.
Dive into the API: Immich provides an API that can be used for integration with other tools or custom scripts.
Engage with the Community: Join the official Immich Discord or Matrix channels, check GitHub Discussions and Issues. The community is a great resource for help, ideas, and staying updated.
Refine Your Backup Strategy: Implement the 3-2-1 rule fully, incorporating automated off-site backups using tools like restic or BorgBackup pointed at cloud storage or another physical location.
GPU Acceleration: If you have compatible hardware and need faster ML processing, investigate setting up GPU acceleration for the immich-machine-learning container.

Remember that running any self-hosted service requires ongoing responsibility. Regularly update Immich (carefully reading release notes), monitor its performance, check your backups periodically, and stay informed about security best practices.

By investing the time to set up and manage Immich, you gain unparalleled control over your most precious digital memories, ensuring they remain truly yours, securely stored and accessible according to your rules.

Troubleshooting Common Issues

Even with careful setup, you might encounter issues. Here are some common problems and steps to diagnose and resolve them:

1. Installation Problems

Issue: docker compose up -d fails with errors about ports already being allocated.
- Cause: Another service on your host machine (or another Docker container) is already using one of the ports Immich needs (e.g., 2283, 5432 for default PostgreSQL, 6379 for Redis, or 80/443 if using the built-in proxy).
- Solution:
  - Identify the conflicting port mentioned in the error message.
  - Use sudo ss -tulnp | grep <port_number> or sudo netstat -tulnp | grep <port_number> to find the process using that port.
  - Either stop the conflicting service or change the port mapping in your Immich docker-compose.yml. For example, change ports: - "2283:3001" to ports: - "2284:3001" to map host port 2284 instead. Remember to update your access URL and potentially the .env file accordingly.
Issue: Containers fail to start, logs show errors related to volume permissions (Permission denied).
- Cause: The user ID (UID) and group ID (GID) inside the Immich containers do not have write permission to the directories mapped as volumes on the host, especially the UPLOAD_LOCATION. Docker containers often run as a specific UID/GID (commonly 1000:1000).
- Solution:
  - Ensure the host directories (e.g., /mnt/data/immich-photos, database volume path) exist.
  - Adjust ownership and/or permissions on the host directories. A common approach is to set the ownership to match the UID/GID used by the container (often 1000): sudo chown -R 1000:1000 /mnt/data/immich-photos. Alternatively, adjust permissions more broadly (e.g., sudo chmod -R 775 /mnt/data/immich-photos and ensure the container user is part of the owning group), but be mindful of security implications. Check Immich documentation for recommended permissions setup.
Issue: Database container fails to start, logs mention initialization errors or incompatible data directories.
- Cause: Trying to reuse an existing PostgreSQL data directory from a different version or configuration, or data corruption.
- Solution: If this is a fresh install, ensure the mapped volume directory for PostgreSQL data (e.g., ./pgdata) is empty or doesn't exist initially; Docker will create it. If migrating or recovering, ensure the data is compatible or follow specific migration steps. As a last resort for a fresh install, stop Immich (docker compose down -v <- WARNING: -v removes named volumes, including the database! Use with extreme caution and only if you have backups or no data yet), delete the host volume directory content, and start again (docker compose up -d).

2. Upload Failures

Issue: Web UI or Mobile App uploads fail with network errors or generic failure messages.
- Cause: Network connectivity issues, reverse proxy misconfiguration, incorrect server URL in the app, insufficient storage space, file size limits (if configured), or permission problems in the UPLOAD_LOCATION.
- Solution:
  - Connectivity: Verify the Immich server is reachable from the client device (ping the IP/domain, check firewall rules). Ensure the Server Endpoint URL in the mobile app is correct (including http:// or https:// and the port if needed).
  - Reverse Proxy: If using a proxy, check its logs for errors. Ensure WebSocket support is enabled. Check for body size limits in the proxy config (e.g., Nginx client_max_body_size) that might be blocking large file uploads.
  - Storage: Check available disk space on the volume hosting UPLOAD_LOCATION using df -h.
  - Permissions: Double-check permissions on the UPLOAD_LOCATION directory on the host (see Installation Problems).
  - Immich Logs: Check immich-server and immich-microservices logs (docker compose logs immich-server) for specific error messages during the upload attempt.

3. Performance Issues

Issue: Web UI is slow, searches take a long time, background tasks (thumbnails, ML) seem stuck or very slow.
- Cause: Insufficient hardware resources (CPU, RAM, slow disk I/O), overwhelming number of background jobs, database bottlenecks.
- Solution:
  - Monitor: Use docker stats to identify bottlenecks (see Performance Tuning section).
  - Check Resources: Ensure the host machine isn't running out of RAM or consistently maxing out CPU.
  - Disk I/O: Use tools like iotop (sudo apt install iotop) on the host to check if disk I/O is the limiting factor, especially for the disks hosting Docker volumes and the upload library. Consider moving database/config volumes to an SSD.
  - Job Status: Check Administration -> Jobs in the Immich UI to see if queues are backed up.
  - Restart: Sometimes a simple restart (docker compose restart) can resolve temporary glitches.
  - Resource Allocation: If running in a VM, ensure sufficient CPU cores and RAM are allocated to the VM.
  - Tuning: Review concurrency settings in .env (cautiously). Consider disabling non-essential, resource-heavy features temporarily to diagnose.

4. Access Problems

Issue: Cannot access Immich via the web browser or mobile app.
- Cause: Containers not running, firewall blocking ports, incorrect IP address or port, DNS resolution issues (if using domain name), reverse proxy down or misconfigured.
- Solution:
  - Check Containers: Run docker compose ps to ensure all Immich containers (especially immich-server, immich-web/immich-proxy) are running. If not, check logs (docker compose logs <service_name>) and try restarting (docker compose restart <service_name> or docker compose up -d).
  - Firewall: Ensure the host firewall (e.g., ufw, firewalld) allows incoming connections on the port Immich is exposed on (e.g., 2283, or 80/443 if using a proxy). Example ufw: sudo ufw allow 2283/tcp.
  - IP/Port: Double-check you are using the correct IP address and port for the Immich host.
  - DNS: If using a domain name, use ping immich.yourdomain.com and nslookup immich.yourdomain.com from the client machine to verify DNS resolution is working correctly and pointing to the right IP address.
  - Reverse Proxy: If using a proxy, ensure the proxy container itself is running and check its logs. Verify the proxy configuration points to the correct internal Immich service IP/hostname and port. Ensure ports 80/443 are correctly mapped and allowed through the firewall to the proxy container.

5. Machine Learning Issues

Issue: No AI tags appear, People/Faces section remains empty even after uploading photos with people.
- Cause: immich-machine-learning container not running or failing, ML features disabled in .env, insufficient resources for ML models to run, background jobs failing or stalled.
- Solution:
  - Verify Container: Check docker compose ps ensures immich-machine-learning is running. Check its logs (docker compose logs immich-machine-learning) for errors related to model loading or processing.
  - Check .env: Ensure ML is enabled (IMMICH_MACHINE_LEARNING_ENABLED=true or similar). Restart containers after changes.
  - Resources: Monitor resource usage (docker stats). The ML container might need more RAM or CPU allocated (via Docker resource limits or by upgrading host hardware).
  - Job Status: Check Administration -> Jobs. Look for failed ML-related jobs. Try triggering a re-scan for the relevant task (e.g., "Detect Faces").
  - Wait: ML processing takes time, especially for large libraries on slower hardware. Allow ample time after uploads.

Where to Get More Help

Official Immich Documentation: Always the first place to look for setup guides, configuration options, and feature explanations.
Immich GitHub Repository: Check for existing Issues (both open and closed) that match your problem. If you find a bug, you can report it here.
Immich Discord/Matrix: Active communities where you can ask questions and get help from developers and other users. Be sure to provide details about your setup, what you've tried, and relevant logs.

By systematically checking these common areas, you can often diagnose and resolve issues with your Immich instance. Remember to provide clear information and logs when seeking help from the community.

Photo Management Immich

Introduction

1. Basic Level Understanding and Setup

Core Concepts of Immich

Workshop Understanding Immich's Components via Docker Compose

Installation via Docker Compose

Workshop Installing Immich

2. Intermediate Level Usage and Configuration

User Management and Permissions

Workshop Managing Users and Basic Sharing

Uploading and Organizing Media

Workshop Uploading Strategies

Leveraging Metadata and Search

Workshop Exploring Your Media

3. Advanced Level Customization and Maintenance

Reverse Proxy and HTTPS Setup

Workshop Securing Immich with Nginx Proxy Manager

Backup and Recovery Strategies

Workshop Implementing a Basic Backup Plan

Performance Tuning and Monitoring

Workshop Monitoring Immich Performance

Understanding and Customizing Machine Learning Features

Workshop Exploring ML Features

Conclusion

Troubleshooting Common Issues