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:

```nix
{ 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:

```nix
{
  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

```nix
{ 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

```bash
# 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

```bash
# 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

```nix
{ 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

```bash
# 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

```bash
# 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:

```nix
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:

```nix
# 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:

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

## Resources

- [Immich Official Website](https://immich.app)
- [Immich Documentation](https://immich.app/docs)
- [Immich GitHub](https://github.com/immich-app/immich)
- [Docker Compose Reference](https://docs.docker.com/compose/)

## Support

For Immich-specific issues, refer to:
- [Immich GitHub Issues](https://github.com/immich-app/immich/issues)
- [Immich Discord Community](https://discord.gg/DSbk7SPrCj)

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:

```nix
# 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).