nixos/appflakes/immich/README.md

Immich NixOS Module

Self-hosted photo and video backup solution packaged as a NixOS module.

About Immich

Immich is a high-performance self-hosted photo and video backup solution. This module deploys Immich using Docker Compose with automatic service management.

Key Features:

• Automatic backup from mobile devices
• AI-powered face recognition
• Smart search with object and location detection
• Sharing albums with family and friends
• Timeline and map views
• Duplicate detection
• Video transcoding and playback

Usage

Basic Configuration

Add this module to your NixOS configuration:

{ config, pkgs, ... }:
{
  imports = [
    # Import the Immich Docker Compose module
    (builtins.getFlake "path:/path/to/appflakes/immich").nixosModules.immich-docker
  ];

  services.immich-docker = {
    enable = true;
    domain = "immich.example.com";
    port = 2283;
    dataDir = "/mnt/userdata/immich";
  };
}

With Flake Inputs

If using flakes, add Immich as an input:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    immich = {
      url = "path:./appflakes/immich";
    };
  };

  outputs = { self, nixpkgs, immich, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      modules = [
        immich.nixosModules.immich-docker
        ./configuration.nix
      ];
    };
  };
}

Example for Warp Server

{ config, ... }:

{
  imports = [
    (builtins.getFlake "path:${self}/appflakes/immich").nixosModules.immich-docker
  ];

  services.immich-docker = {
    enable = true;
    domain = "warp.example.com";
    port = 2283;
    dataDir = "/mnt/userdata/immich";
    dbPassword = "your-secure-password-here";
    typesenseApiKey = "your-typesense-key-here";
    enableWatchtower = true;
  };
}

Configuration Options

services.immich-docker.enable (boolean)

Default: false

Enable the Immich Docker Compose service.

services.immich-docker.domain (string)

Default: "immich.local"

The domain name for the Immich web interface.

services.immich-docker.port (port)

Default: 2283

The port number for the Immich web interface.

services.immich-docker.dataDir (path)

Default: "/mnt/userdata/immich"

Directory where Immich will store all data including:

• Uploaded photos and videos
• Processed images
• Database files
• Search indexes

services.immich-docker.dbPassword (string)

Default: "immich"

PostgreSQL database password. Change this in production!

services.immich-docker.typesenseApiKey (string)

Default: "immich-typesense-secret-key-change-this"

API key for the Typesense search engine. Change this in production!

services.immich-docker.enableWatchtower (boolean)

Default: false

Enable automatic container updates via Watchtower. When enabled, Watchtower will update containers when new versions are available.

Deployment

Automatic Deployment

The NixOS module handles everything automatically:

1. Creates required directories
2. Generates docker-compose configuration
3. Configures systemd service
4. Starts all containers on boot

Manual Service Management

# Start Immich
sudo systemctl start docker-compose-immich

# Stop Immich
sudo systemctl stop docker-compose-immich

# Restart Immich
sudo systemctl restart docker-compose-immich

# Check status
sudo systemctl status docker-compose-immich

# View logs
sudo journalctl -u docker-compose-immich -f

Container Management

# View all Immich containers
docker ps | grep immich

# View logs for specific service
docker logs immich_server

# Execute commands in container
docker exec -it immich_server bash

Architecture

This module deploys Immich as a Docker Compose stack with the following containers:

• immich_server: Web API and interface
• immich_microservices: Background jobs and machine learning
• immich_postgres: PostgreSQL database with pgvector
• immich_redis: Redis cache
• immich_typesense: Search engine

The stack is managed by systemd and starts automatically on boot.

Access

Once deployed, access Immich at:

• Web Interface: http://your-domain:port (default: http://localhost:2283)
• Mobile App: Configure using your domain and port

Storage Requirements

Plan for significant storage based on your photo/video collection:

• High-res photos: 5-15 MB per photo
• Processed versions: 2-5 MB additional per photo
• Thumbnails: ~500 KB per photo
• 4K videos: 100-500 MB per minute
• Database: ~100-500 MB for 10,000 photos

Recommended:

• Start with at least 100GB for small collections
• 500GB+ for growing collections
• 1TB+ for serious photographers

Security Recommendations

1. Change Default Passwords: Update dbPassword and typesenseApiKey in your NixOS configuration
2. Reverse Proxy: Use Nginx with SSL/TLS for production
3. Firewall: Restrict access to port 2283
4. Backups: Regularly backup the dataDir
5. Updates: Keep Immich containers updated (enable Watchtower or update the image tag in the module)
6. Network: Consider VPN access for remote management

Backup Strategy

Automated Backup Example

{ config, pkgs, ... }:

{
  services.immich-docker.enable = true;
  
  # Example: Regular backups using restic
  services.restic.backups.immich = {
    paths = [ "/mnt/userdata/immich" ];
    repository = "s3:backup-bucket/immich";
    passwordFile = "/etc/restic/password";
    timerConfig = {
      OnCalendar = "daily";
      Persistent = true;
    };
  };
}

Important Backup Locations

Ensure these are included in backups:

• ${dataDir}/upload/ - Original photos and videos
• ${dataDir}/postgres/ - Database
• ${dataDir}/typesense/ - Search indexes

Troubleshooting

Service Won't Start

# Check service logs
sudo journalctl -u docker-compose-immich -n 100

# Check Docker status
sudo systemctl status docker

# Verify directories exist
ls -la /mnt/userdata/immich

Database Connection Issues

# Check PostgreSQL container
docker logs immich_postgres

# Test database connectivity
docker exec -it immich_postgres psql -U immich -d immich

Performance Issues

• Ensure adequate CPU (4+ cores recommended)
• Allocate sufficient RAM (8GB+ recommended)
• Monitor Docker resource usage
• Check storage space: df -h /mnt/userdata

Port Already In Use

If port 2283 is already in use, change the port:

services.immich.port = 8080;  # Use alternative port

Migration

From Manual Docker Compose

1. Stop existing containers
2. Backup current data directory
3. Update NixOS configuration to use this module
4. Set dataDir to your current data directory
5. Apply new configuration
6. Start service: sudo systemctl start docker-compose-immich

Version Updates

Manual Updates

Update the Immich version by modifying the image tag in the flake:

# In flake.nix, change:
image: ghcr.io/immich-app/immich-server:v1.122.2

# To:
image: ghcr.io/immich-app/immich-server:v1.123.0

Then rebuild the NixOS configuration.

Automatic Updates

Enable Watchtower for automatic updates:

services.immich = {
  enable = true;
  enableWatchtower = true;  # Enables automatic container updates
};

Resources

• Immich Official Website
• Immich Documentation
• Immich GitHub
• Docker Compose Reference

Support

For Immich-specific issues, refer to:

• Immich GitHub Issues
• Immich Discord Community

For NixOS module issues, check:

• Module configuration and syntax
• Docker integration
• Systemd service logs

Version Updates

To update Immich to a newer version, modify the image tag in the flake:

# In appflakes/immich/flake.nix, change:
image: ghcr.io/immich-app/immich-server:v1.122.2

# To:
image: ghcr.io/immich-app/immich-server:v1.123.0

Then rebuild your NixOS configuration.

License

This NixOS module follows the same license as the Immich project (AGPL-3.0).