How To Install Immich on AlmaLinux 10

Self-hosting your photo and video collection has become increasingly important as privacy concerns grow and cloud storage costs escalate. Immich stands out as a powerful, open-source alternative to Google Photos and Apple iCloud, offering advanced features like machine learning-powered search, facial recognition, and automatic backup capabilities. When paired with AlmaLinux 10’s enterprise-grade stability and security, you get a robust platform perfect for managing your digital memories.

This comprehensive guide walks you through every step of installing Immich on AlmaLinux 10, from initial system preparation to advanced configuration and troubleshooting. Whether you’re a homelab enthusiast or managing photos for a small business, you’ll have a fully functional self-hosted photo management system by the end of this tutorial.

Prerequisites and System Requirements

Hardware Requirements

Before proceeding with the installation, ensure your AlmaLinux 10 system meets Immich’s minimum hardware specifications. The application requires at least 4GB of RAM and 2 CPU cores for basic functionality. However, for optimal performance, especially when handling large photo libraries or enabling machine learning features, consider these recommended specifications:

• RAM: 8GB or more for smooth operation with ML features enabled
• CPU: 4 cores or more for faster photo processing and thumbnail generation
• Storage: SSD recommended with at least 100GB free space, though requirements scale with your photo library size
• Network: Gigabit Ethernet for fast photo uploads and synchronization

Software Prerequisites

Your AlmaLinux 10 installation should be fresh and fully updated to prevent potential conflicts. You’ll need root or sudo privileges throughout this installation process. Ensure you have a stable internet connection for downloading Docker images and Immich components.

The installation requires several packages that may not be present in a minimal AlmaLinux installation, including curl, wget, and git for downloading configuration files and managing the installation process.

Network and Security Prerequisites

Immich operates on port 2283 by default, which must be accessible from devices you plan to use for photo uploads. If you intend to access Immich from external networks, consider implementing proper SSL certificates and firewall configurations. Planning your network architecture early prevents security vulnerabilities and connectivity issues later.

Preparing the AlmaLinux 10 Environment

System Updates and Package Management

Start by updating your AlmaLinux 10 system to ensure all packages are current and security patches are applied. Open a terminal session and execute the following commands:

sudo dnf update -y
sudo dnf install -y curl wget nano git firewalld

This update process may take several minutes depending on your system’s current state and internet connection speed. The additional packages provide essential utilities for downloading Immich configuration files and managing the installation process.

After the update completes, reboot your system to ensure all kernel updates take effect:

sudo reboot

Creating Dedicated User Account

For enhanced security, avoid running Immich services as the root user. Create a dedicated user account specifically for managing your Immich installation:

sudo useradd -m -s /bin/bash immich-admin
sudo usermod -aG wheel immich-admin
sudo passwd immich-admin

This approach follows security best practices by limiting privileges and providing better isolation between system services and your photo management application.

Firewall Configuration

Configure AlmaLinux 10’s firewall to allow Immich traffic while maintaining system security. Enable and configure firewalld with the necessary port openings:

sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-port=2283/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

For external access, you may need additional firewall rules depending on your network configuration and reverse proxy setup.

Installing Docker and Docker Compose

Docker Installation on AlmaLinux 10

Immich relies on Docker containers for deployment, making Docker installation the next critical step. Add the official Docker repository to your AlmaLinux 10 system:

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Install Docker CE and its components:

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Start and enable the Docker service to ensure it runs automatically on system boot:

sudo systemctl start docker
sudo systemctl enable docker

Add your user to the docker group for non-root Docker access:

sudo usermod -aG docker $USER
newgrp docker

Docker Compose Installation

Modern Docker installations include Docker Compose as a plugin, but verify its availability and functionality:

docker compose version

If the command returns version information, Docker Compose is properly installed. Test Docker functionality with a simple container:

docker run hello-world

Docker Environment Verification

Confirm your Docker installation can pull and run containers successfully. This test ensures your system can handle Immich’s container requirements before proceeding with the main installation.

Setting Up Immich Directory Structure

Creating Project Directory

Establish a well-organized directory structure for your Immich installation. Following the pattern demonstrated in containerization best practices, create the directory structure:

sudo mkdir -p /opt/stacks/immich
sudo chown -R $USER:$USER /opt/stacks
cd /opt/stacks/immich

This organization approach keeps all container stacks organized and makes maintenance easier over time. The /opt/stacks pattern provides a clean separation between different containerized applications.

Downloading Required Files

Download the official Immich Docker Compose configuration and environment files directly from the project repository:

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Verify the files downloaded correctly by checking their contents:

ls -la
head -20 docker-compose.yml

Create backup copies of these configuration files before making modifications:

cp docker-compose.yml docker-compose.yml.backup
cp .env .env.backup

Configuring Immich Environment

Understanding the .env File

The environment file controls critical aspects of your Immich installation, including database passwords, storage locations, and service configurations. Open the .env file for editing:

nano .env

Essential Configuration Parameters

Configure the most important environment variables for your installation:

Storage Configuration:

UPLOAD_LOCATION=/opt/stacks/immich/library
DB_DATA_LOCATION=/opt/stacks/immich/postgres

Database Security:
Generate a secure password for PostgreSQL. Use only alphanumeric characters to avoid Docker parsing issues:

DB_PASSWORD=YourSecurePassword123

Timezone Configuration:
Uncomment and set your timezone for proper timestamp handling:

TZ=Asia/Jakarta

Version Pinning:
Pin to a specific Immich version for stability:

IMMICH_VERSION=release

Optional Advanced Configurations

For users requiring specialized setups, consider these advanced options:

External Storage Integration:
Mount network shares for large photo libraries by modifying the docker-compose.yml file to include additional volume mappings.

GPU Acceleration:
Enable hardware acceleration for machine learning features by uncommenting the appropriate hardware acceleration sections in the compose file.

Docker Compose Configuration Deep Dive

Understanding Service Components

The Immich stack consists of several interconnected services:

• immich-server: Main application server handling web interface and API requests
• immich-machine-learning: AI-powered features including facial recognition and smart search
• database: PostgreSQL with vector extension for metadata and search functionality
• redis: Caching layer for improved performance

Volume and Network Configuration

Immich’s Docker configuration creates persistent volumes for data storage and establishes internal networking between services. The database and uploaded files persist across container updates through volume mappings specified in your .env file.

Understanding this architecture helps troubleshoot issues and plan backup strategies. Each service communicates through Docker’s internal networking, with only the main server exposed on port 2283.

Installing and Starting Immich

Initial Deployment

With configuration complete, start your Immich installation from the project directory:

cd /opt/stacks/immich
docker compose up -d

This command downloads required Docker images and starts all services in detached mode. The initial download may take several minutes depending on your internet connection speed.

First-time Startup Process

Monitor the startup process by viewing container logs:

docker compose logs -f

Watch for successful database initialization, service health checks, and any error messages. The machine learning service may take additional time to download AI models on first startup.

Verify all containers are running properly:

docker compose ps

All services should show “running” status with healthy indicators.

Initial Immich Setup and Configuration

Web Interface Access

Once all containers are running, access the Immich web interface by navigating to your server’s IP address on port 2283:

http://your-server-ip:2283

The first-time setup wizard guides you through creating an administrator account and configuring basic settings.

Basic Configuration Settings

Administrator Account Creation:
Create a secure administrator account with a strong password. This account manages user permissions and system settings.

Library Configuration:
Set up your photo library organization preferences, including automatic thumbnail generation and metadata extraction settings.

Upload Settings:
Configure supported file formats and upload size limits based on your storage capacity and usage patterns.

Mobile App Configuration

Download the official Immich mobile applications from your device’s app store. Connect to your self-hosted instance using your server’s IP address and port 2283.

Configure automatic backup settings for camera roll synchronization and specify which albums to back up automatically.

Advanced Features and Optimization

Machine Learning Features

Immich’s AI capabilities provide powerful photo organization tools. The machine learning service automatically processes uploaded photos for:

• Facial Recognition: Automatically groups photos by detected faces
• Object Detection: Enables searching for specific objects in photos
• Scene Recognition: Categorizes photos by location and scene types

These features require additional processing time and system resources but significantly enhance photo discovery and organization capabilities.

External Storage Integration

For users with existing photo libraries or network-attached storage systems, Immich supports external library integration. Configure watched folders to automatically import photos from mounted network shares or external drives.

This feature allows gradual migration from existing photo management systems while maintaining current organizational structures.

Security Hardening and Best Practices

Access Control and Authentication

Implement strong authentication practices by enforcing complex passwords and enabling two-factor authentication when available. Create individual user accounts rather than sharing the administrator account.

Consider implementing OAuth integration with existing identity providers for enterprise environments or multi-user setups.

Network Security

For external access, implement reverse proxy solutions like Traefik or Nginx with proper SSL certificate management. Avoid exposing Immich directly to the internet without proper security measures.

Consider VPN access for remote photo management as an alternative to direct internet exposure.

Backup and Maintenance

Backup Strategies

Regular backups protect your photo library and configuration against hardware failures or data corruption. Implement automated backup procedures for:

Database Backups:

docker compose exec database pg_dump -U postgres immich > immich_backup_$(date +%Y%m%d).sql

Media Library Backups:
Use rsync or similar tools to back up your photo library to external storage or cloud services.

Routine Maintenance

Keep your Immich installation current with regular updates. Monitor system resources and logs for performance issues or errors requiring attention.

Implement log rotation to prevent disk space issues from extensive logging output.

Troubleshooting Common Issues

Installation Problems

Docker Connectivity Issues:
Verify Docker service status and network connectivity. Ensure your user has proper Docker group membership for non-root access.

Permission Problems:
Check file ownership and permissions on storage directories. The container user must have read/write access to configured storage locations.

Runtime Issues

Container Startup Failures:
Review Docker Compose logs for specific error messages. Common issues include port conflicts, insufficient system resources, or configuration errors.

Database Connection Problems:
Verify PostgreSQL container health and network connectivity between services. Check environment variable configuration for database credentials.

Upload and Storage Issues:
Confirm storage directory permissions and available disk space. Verify volume mappings match your .env file configuration.

Performance Optimization

Monitor system resource usage during heavy operations like initial library scans or machine learning processing. Adjust container resource limits if necessary to prevent system overload.

Consider SSD storage for database files and frequently accessed thumbnails to improve response times.

Congratulations! You have successfully installed Immich. Thanks for using this tutorial for installing the Immich on your AlmaLinux OS 10 system. For additional help or useful information, we recommend you check the official Immich website.