How To Install Immich on Debian 13
Immich has emerged as the leading open-source alternative to Google Photos, offering users complete control over their photo and video libraries. This self-hosted solution provides advanced features including facial recognition, automatic backup, and intelligent search capabilities without compromising your privacy. Installing Immich on Debian 13 gives you a robust platform for managing your media collection while maintaining full ownership of your data.
This comprehensive guide covers multiple installation methods for Immich on Debian 13. Whether you prefer Docker containerization, Snap packages, or native installation, we’ll walk you through each approach with detailed instructions. You’ll learn about system requirements, security considerations, and optimization techniques to ensure your Immich installation runs smoothly and efficiently.
System Requirements and Prerequisites
Hardware Requirements
Before installing Immich on your Debian 13 system, ensure your hardware meets the minimum specifications. Your server needs at least 2GB of RAM for basic functionality, though 4GB or more is recommended for optimal performance with larger media libraries. A dual-core CPU provides adequate processing power, but quad-core processors handle face recognition and thumbnail generation more efficiently.
Storage requirements vary significantly based on your media collection size. Allocate at least 10GB for the application and database, plus additional space equal to your media library size for thumbnails and processed files. SSD storage dramatically improves performance, especially during initial library scanning and face detection processes.
Network bandwidth becomes crucial if you plan to access Immich remotely or upload large video files. A stable internet connection with at least 10Mbps upload speed ensures smooth mobile app synchronization and web interface responsiveness.
Software Prerequisites
Debian 13 provides an excellent foundation for Immich installation, offering stable package management and long-term support. Ensure your system runs the latest Debian 13 updates to avoid compatibility issues and security vulnerabilities. The installation process requires sudo privileges, so verify your user account has administrative access or belongs to the sudo group.
Essential packages include curl, wget, and git for downloading configuration files and repositories. Docker installations additionally require systemd for service management and proper container orchestration. Update your package cache and install these dependencies before proceeding with Immich installation.
Your system should have at least 1GB of free disk space in the root partition for temporary files during installation. PostgreSQL database requirements demand additional storage for metadata and search indexes, scaling with your media collection size.
Pre-Installation System Setup
Begin by updating your Debian 13 system to ensure all packages are current and security patches are applied:
sudo apt update && sudo apt upgrade -yInstall essential utilities that support the installation process:
sudo apt install curl wget git unzip software-properties-common -yCreate a dedicated user for Immich if you prefer running the service with limited privileges:
sudo useradd -m -s /bin/bash immich
sudo usermod -aG sudo immichConfigure your firewall to allow necessary ports while maintaining security. Immich typically uses port 3000 for web access and requires database connectivity on port 5432.
Installation Method 1: Docker Installation (Recommended)
Docker and Docker Compose Setup
Docker installation provides the most reliable and maintainable approach for running Immich on Debian 13. This method isolates dependencies, simplifies updates, and ensures consistent behavior across different systems. Start by installing Docker from the official repository to get the latest stable version.
Add Docker’s official GPG key and repository:
sudo apt install ca-certificates gnupg lsb-release
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullInstall Docker Engine and Docker Compose:
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -yAdd your user to the docker group to run commands without sudo:
sudo usermod -aG docker $USER
newgrp dockerVerify the installation by checking Docker and Docker Compose versions:
docker --version
docker compose versionStart and enable Docker service to run automatically at boot:
sudo systemctl start docker
sudo systemctl enable dockerDownloading Immich Configuration Files
Create a dedicated directory for your Immich installation to organize configuration files and maintain clean system management:
mkdir ~/immich
cd ~/immichDownload the official docker-compose.yml file from Immich’s GitHub repository:
wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.ymlDownload the example environment file:
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.envCreate the necessary directory structure for media storage and application data:
mkdir -p ./library
mkdir -p ./postgres-dataThe library directory will store your uploaded photos and videos, while postgres-data contains the database files. Ensure these directories have appropriate permissions for the containers to access them properly.
Environment Configuration
Edit the .env file to customize your Immich installation settings:
nano .envConfigure essential environment variables for security and functionality:
# Database password - change this to a strong, unique password
DB_PASSWORD=your_secure_database_password
# Upload location - adjust the path as needed
UPLOAD_LOCATION=./library
# Database data location
DB_DATA_LOCATION=./postgres-data
# Immich version - pin to specific version for stability
IMMICH_VERSION=release
# Optional: External URL if accessing from outside localhost
PUBLIC_IMMICH_SERVER_URL=http://your-domain.com:3000For production environments, consider additional security configurations:
# JWT secret for session management
JWT_SECRET=your_jwt_secret_key
# Redis password for caching
REDIS_PASSWORD=your_redis_password
# PostgreSQL settings for performance
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_EFFECTIVE_CACHE_SIZE=1GBSet proper permissions on the environment file to protect sensitive information:
chmod 600 .envRunning Immich with Docker
Start your Immich installation using Docker Compose:
docker compose up -dThe -d flag runs containers in detached mode, allowing them to run in the background. Monitor the initialization process by viewing container logs:
docker compose logs -fVerify all services are running correctly:
docker compose psYou should see several containers running, including immich-server, immich-web, postgres, and redis. Wait for all containers to reach a healthy status before proceeding to the web interface.
Check service health and resource usage:
docker statsFor troubleshooting startup issues, examine individual container logs:
docker compose logs immich-server
docker compose logs postgresInitial Web Interface Setup
Access the Immich web interface by navigating to http://localhost:3000 in your web browser. If you’re accessing remotely, replace localhost with your server’s IP address or domain name.
Create the first administrator account by filling out the registration form. This account has full system privileges and manages other users. Choose a strong password and consider enabling two-factor authentication for enhanced security.
Configure basic system settings through the Administration panel:
- Set your timezone and language preferences
- Configure email settings for notifications
- Adjust thumbnail quality and storage settings
- Set up automatic backup retention policies
Install the Immich mobile app from your device’s app store and connect it using the server URL and your administrator credentials. The mobile app provides automatic photo backup and seamless integration with your self-hosted instance.
Installation Method 2: Snap Package Installation
Snap System Setup
Snap packages offer a convenient alternative for installing Immich without Docker complexity. This method provides automatic updates and simplified dependency management while maintaining application isolation. Begin by installing the snap daemon on your Debian 13 system.
Install snapd and enable the service:
sudo apt install snapd -y
sudo systemctl enable --now snapd.socketCreate the symbolic link for snap compatibility:
sudo ln -s /var/lib/snapd/snap /snapUpdate your PATH environment variable to include snap binaries:
echo 'export PATH=$PATH:/snap/bin' >> ~/.bashrc
source ~/.bashrcVerify snap installation and check available packages:
sudo snap list
snap find immichImmich Distribution Snap Installation
Install the Immich Distribution snap package from the Snap Store:
sudo snap install immich-distributionThe snap package includes all necessary dependencies and automatically configures the service. Monitor the installation progress and wait for completion before accessing the application.
Check the installed snap information and version:
snap info immich-distributionConfigure snap-specific permissions for media access:
sudo snap connect immich-distribution:removable-media
sudo snap connect immich-distribution:network-bindStart the Immich service through snap management:
sudo snap start immich-distributionVerify the service status and ensure proper initialization:
sudo snap services immich-distributionSnap Configuration and Access
Access your snap-installed Immich instance through the default web interface at http://localhost:3000. The snap package uses predefined port configurations that may differ from Docker installations.
Snap-specific configuration files are located in the snap data directories:
ls /var/snap/immich-distribution/current/For custom configurations, modify the appropriate files in the snap data directory. Remember that snap applications have limited file system access due to confinement restrictions.
Installation Method 3: Native Installation (Community Methods)
Community Native Installation Projects
Native installation methods provide direct system integration without containerization overhead. These community-driven projects offer alternatives for users who prefer traditional package management or have specific hardware constraints that make containers unsuitable.
The immich-native project provides scripts and documentation for installing Immich directly on various Linux distributions, including Debian 13. While not officially supported, these methods can offer better resource utilization and easier system integration.
Clone the community installation repository:
git clone https://github.com/community/immich-native.git
cd immich-nativeReview the installation scripts and requirements before proceeding. Native installations require manual dependency management and system configuration that containerized methods handle automatically.
Manual Native Installation Process
Install Node.js and npm for running the Immich web application:
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -yInstall PostgreSQL database server:
sudo apt install postgresql postgresql-contrib -y
sudo systemctl start postgresql
sudo systemctl enable postgresqlCreate a database user and database for Immich:
sudo -u postgres createuser --interactive --pwprompt immich
sudo -u postgres createdb -O immich immichClone the official Immich repository:
git clone https://github.com/immich-app/immich.git
cd immichInstall application dependencies and build the project:
npm ci
npm run buildConfigure environment variables in a .env file similar to the Docker setup, adjusting paths and connection strings for native installation.
Native Installation Considerations
Native installations require ongoing maintenance and manual updates. Security patches, dependency updates, and configuration changes need careful attention to avoid system instability or security vulnerabilities.
Consider the long-term maintenance burden before choosing native installation. Docker and snap methods provide easier update mechanisms and better isolation from system components. Reserve native installation for specialized environments where containerization is not feasible.
Post-Installation Configuration
Database Optimization
Optimize PostgreSQL performance for your Immich installation by adjusting configuration parameters based on your system resources and usage patterns. Edit the PostgreSQL configuration file to improve query performance and reduce resource consumption.
Locate and edit the PostgreSQL configuration:
sudo nano /etc/postgresql/14/main/postgresql.confApply performance optimizations:
shared_buffers = 256MB
effective_cache_size = 1GB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100Implement automated backup strategies for your Immich database:
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker exec postgres-container pg_dump -U immich immich > backup_immich_$DATE.sqlSchedule regular database maintenance tasks including vacuuming and analyzing tables to maintain optimal performance as your media library grows.
Media Storage Configuration
Configure proper directory permissions and ownership for media storage locations. Immich requires read and write access to process uploads, generate thumbnails, and manage your photo library.
Set appropriate permissions for the upload directory:
sudo chown -R 1000:1000 ./library
sudo chmod -R 755 ./libraryImplement storage monitoring to track disk usage and prevent storage exhaustion:
df -h /path/to/immich/library
du -sh /path/to/immich/library/*Configure automatic cleanup policies for temporary files and processed media to manage disk space efficiently. Consider implementing tiered storage strategies for older media files if storage space becomes constrained.
User Management and Access Control
Create additional user accounts through the Immich web interface to share your photo management system with family members or colleagues. Each user maintains separate libraries while administrators control global system settings.
Configure user permissions and storage quotas based on your requirements:
- Navigate to the Administration panel
- Select User Management
- Add new users with appropriate permissions
- Set storage quotas and feature access
Implement external authentication integration if your environment uses LDAP or single sign-on systems. This centralized authentication simplifies user management and improves security compliance.
Network and SSL Configuration
Set up a reverse proxy using Nginx to provide SSL termination and improve security for external access. This configuration enables HTTPS connections and professional domain integration.
Install and configure Nginx:
sudo apt install nginx -y
sudo nano /etc/nginx/sites-available/immichCreate a reverse proxy configuration:
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Enable the site and restart Nginx:
sudo ln -s /etc/nginx/sites-available/immich /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginxSecurity Hardening
System-Level Security
Implement comprehensive firewall rules to restrict access to necessary ports while blocking potential attack vectors. Configure UFW (Uncomplicated Firewall) for straightforward rule management.
Enable and configure the firewall:
sudo ufw enable
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 3000/tcp
sudo ufw allow 443/tcp
sudo ufw allow 80/tcpConfigure fail2ban to prevent brute force attacks on SSH and web services:
sudo apt install fail2ban -y
sudo nano /etc/fail2ban/jail.localImplement log monitoring and intrusion detection to identify suspicious activities. Regular security audits help maintain system integrity and identify potential vulnerabilities before they become problematic.
Application Security
Configure Immich-specific security settings including API key management, session timeouts, and access controls. Review and update default configurations to match your security requirements and compliance needs.
Enable two-factor authentication for all user accounts, especially administrative users. This additional security layer significantly reduces the risk of unauthorized access even if passwords are compromised.
Implement regular backup verification and testing procedures to ensure data recovery capabilities. Store backups in separate locations and test restoration procedures periodically to validate backup integrity.
Troubleshooting Common Issues
Installation Problems
Docker permission issues commonly occur when users lack proper group membership or service permissions. Resolve these by verifying group membership and restarting user sessions:
groups $USER
sudo usermod -aG docker $USER
newgrp dockerNetwork connectivity problems often stem from firewall restrictions or port conflicts. Check port availability and firewall rules:
sudo netstat -tlnp | grep :3000
sudo ufw statusDatabase connection failures typically indicate configuration errors or service startup issues. Examine container logs and verify environment variables:
docker compose logs postgres
docker compose exec postgres psql -U immich -d immich -c "\dt"Performance Issues
Memory and CPU optimization becomes crucial for systems with limited resources or large media libraries. Monitor resource usage and adjust container memory limits as needed:
docker stats
htopDatabase performance tuning involves adjusting PostgreSQL parameters based on system resources and usage patterns. Implement connection pooling and query optimization for improved responsiveness.
Storage I/O optimization includes using SSD storage for databases and frequently accessed files while implementing caching strategies for thumbnails and processed media.
Update and Maintenance Issues
Version compatibility problems may arise when mixing different Immich versions or updating dependencies independently. Maintain consistent versioning across all components and follow official upgrade procedures.
Database migration failures require careful attention to backup and recovery procedures. Always create complete backups before major updates and test migration procedures in development environments.
Configuration file conflicts can occur during updates or when mixing different installation methods. Maintain version control for configuration files and document custom modifications for future reference.
Performance Optimization and Monitoring
System Performance Tuning
Resource allocation optimization involves balancing CPU, memory, and storage resources based on your specific usage patterns and system capabilities. Monitor performance metrics to identify bottlenecks and adjust configurations accordingly.
Implement caching strategies using Redis for frequently accessed data and thumbnails. This reduces database load and improves response times for common operations like photo browsing and search queries.
Database indexing and query optimization ensure fast search results and smooth user experiences. Regular maintenance tasks including vacuuming and analyzing tables maintain optimal performance as your library grows.
Monitoring and Maintenance
Log analysis and monitoring tools provide insights into system performance and potential issues. Implement centralized logging solutions to track application behavior and identify trends over time.
Performance metrics and alerting systems notify administrators of resource constraints or service failures. Configure monitoring dashboards to visualize system health and usage patterns.
Automated backup verification ensures data protection and recovery capabilities. Schedule regular backup tests and maintain documented recovery procedures for various failure scenarios.
Congratulations! You have successfully installed Immich. Thanks for using this tutorial for installing Immich on your Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Immich website.
