feat: Add Immich app flake with docker-compose deployment
- Create Immich module as appflake in appflakes/immich/ - Module provides NixOS module for docker-compose deployment - Includes 5-container stack: * immich_server: Web API and interface * immich_microservices: Background jobs and ML processing * immich_postgres: PostgreSQL with pgvector * immich_redis: Redis cache * immich_typesense: Search engine - Configuration options for: * Domain and port customization * Data directory location * Database and API keys * Optional Watchtower auto-updates - Automatic systemd service integration - Comprehensive documentation in README.md - Named module 'immich-docker' to avoid conflicts with Nixpkgs module
This commit is contained in:
Julian Sutter
parent
7263c12bfc
commit
532e01cbf1
3 changed files with 626 additions and 0 deletions
356
appflakes/immich/README.md
Normal file
356
appflakes/immich/README.md
Normal file
|
|
@ -0,0 +1,356 @@
|
|||
# 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue