Immich Complete Ecosystem

Production-ready monitoring, backups, curation, and remote access for Immich

This project provides a complete, production-ready ecosystem around Immich, the self-hosted photo and video management solution. It adds essential features for running Immich in a family environment with 6+ users.

🎯 What This Provides

📊 Immich Server Manager

Disk Health Monitoring - SMART data collection every 5 minutes
Automated Backups - Daily PostgreSQL dumps with 30-day retention
Update Management - Automated minor updates with rollback capability
System Monitoring - CPU, RAM, disk I/O metrics with historical data
Alert System - Email/webhook notifications for critical issues
Web Dashboard - Real-time metrics and manual controls

📸 Photo Curator Assistant

AI Quality Scoring - Automatic photo quality assessment (local, no API costs)
Monthly Curation - Per-user reminders and curated albums
Duplicate Detection - Find and manage similar photos
Year-End Collaboration - Family photo book creation tools

🌐 Remote Access

Cloudflare Tunnel - Secure access from anywhere, no port forwarding
Automatic HTTPS - Built-in SSL certificates
DDoS Protection - Cloudflare's edge network protection

🔒 Security Hardening

fail2ban - Automatic brute force protection
UFW Firewall - Network access control
2FA Support - Two-factor authentication guidance
Security Monitoring - Continuous security status tracking

💰 Cost

Total: $10-15/year

Domain name: $10-15/year
Everything else: FREE (self-hosted)

⚡ Quick Start

Prerequisites

Ubuntu/Debian Linux
Immich already installed and running
Python 3.9+
Docker and Docker Compose
sudo access

Installation

# Clone the repository
git clone https://github.com/yourusername/immich-manager.git
cd immich-manager

# Run the installer
./install.sh

The installer will:

Check prerequisites
Install Server Manager (~10 minutes)
Install Photo Curator (~15 minutes)
Setup Remote Access (~15 minutes, requires domain)
Apply Security Hardening (~5 minutes)
Run comprehensive tests

📋 Detailed Installation

Phase 0: Prerequisites Check

./scripts/00-check-prerequisites.sh

Validates:

Operating system (Ubuntu/Debian)
Python 3.9+
Docker and Docker Compose
Immich installation
Disk space (10GB+ free)
Required ports (8080, 8081)

Phase 1: Server Manager

./scripts/10-install-server-manager.sh

Installs:

Python virtual environment
FastAPI application
SQLite database
systemd service
Web dashboard

Access: http://localhost:8080

Configuration: /opt/immich-server-manager/config/config.yaml

Phase 2: Photo Curator

./scripts/20-install-photo-curator.sh

Installs:

Photo curation engine
OpenCV and AI models
Web interface
systemd service

Access: http://localhost:8081

Configuration: /opt/photo-curator/config/config.yaml

Phase 3: Remote Access

./scripts/30-install-remote-access.sh

Requirements:

Domain name ($10-15/year from Porkbun, Namecheap, etc.)
Free Cloudflare account
Domain added to Cloudflare
Nameservers updated

Sets up:

Cloudflare Tunnel (cloudflared)
DNS records
Multi-service routing
Automatic reconnection

Access:

https://yourdomain.com → Immich
https://yourdomain.com/monitor/ → Server Manager
https://yourdomain.com/curator/ → Photo Curator

Phase 4: Security Hardening

./scripts/40-security-hardening.sh

Configures:

fail2ban with Immich monitoring
UFW firewall rules
Security monitoring scripts
Security checklist

Phase 5: Testing

./scripts/50-test-installation.sh

Tests all components and generates comprehensive report.

🔧 Configuration

Server Manager

Edit /opt/immich-server-manager/config/config.yaml:

immich:
  api_key: "your-api-key"  # Generate in Immich: Admin → API Keys

storage:
  data_drives:
    - "/dev/sda"
    - "/dev/sdb"

backup:
  enabled: true
  local_path: "/mnt/backups/immich"
  retention_days: 30

alerts:
  email:
    enabled: true
    smtp_host: "smtp.gmail.com"
    smtp_port: 587
    smtp_user: "your-email@gmail.com"
    smtp_password: "your-app-password"
    to:
      - "admin@yourdomain.com"

Test email alerts:

curl -X POST http://localhost:8080/api/test-alert

Photo Curator

Edit /opt/photo-curator/config/config.yaml:

immich:
  api_key: "your-api-key"  # Same as Server Manager

curation:
  monthly_target: 50  # Photos to curate per month
  reminder_day: 1     # Day of month for reminders

📊 Monitoring & Maintenance

Quick Health Check

./scripts/health-check.sh

Shows status of all services and recent backup.

View Dashboards

Server Manager: http://localhost:8080
- System metrics
- Disk health
- Backup status
- Alert history
Photo Curator: http://localhost:8081
- Photo quality scores
- Curation progress
- User activity

Service Management

# View logs
sudo journalctl -u immich-server-manager -f
sudo journalctl -u photo-curator -f
sudo journalctl -u cloudflared -f

# Restart services
sudo systemctl restart immich-server-manager
sudo systemctl restart photo-curator
sudo systemctl restart cloudflared

# Check status
sudo systemctl status immich-server-manager

Manual Backup

curl -X POST http://localhost:8080/api/backup/now

Security Monitoring

/opt/immich-ecosystem/scripts/security-monitor.sh

Shows:

fail2ban bans
Recent login attempts
Firewall status
Service health

🔒 Security Best Practices

Essential Steps

Enable 2FA for all users (CRITICAL!)
- Login to Immich → Admin → Users
- Enable 2FA for each user
- Users must set up authenticator app on next login
Use strong passwords
- Minimum 16 characters
- Use a password manager
Regular updates
```
sudo apt update && sudo apt upgrade
```
Monitor alerts
- Check email alerts regularly
- Review security logs weekly
Test backups
- Verify backups are running
- Test restore procedure quarterly

Security Checklist

See /opt/immich-ecosystem/security-checklist.txt for complete checklist.

🔄 Backup & Restore

Backup

Backups run automatically at 2 AM daily (configurable).

Backup location: /mnt/backups/immich/

Manual backup:

curl -X POST http://localhost:8080/api/backup/now

Restore

# List available backups
ls -lh /mnt/backups/immich/

# Restore database (example)
BACKUP_FILE="/mnt/backups/immich/immich_db_20240101_020000.sql.gz"
gunzip -c $BACKUP_FILE | docker exec -i immich_postgres psql -U postgres immich

🚨 Troubleshooting

Server Manager won't start

# Check logs
sudo journalctl -u immich-server-manager -n 50

# Verify configuration
cat /opt/immich-server-manager/config/config.yaml

# Test manually
cd /opt/immich-server-manager
source venv/bin/activate
python -m src.main

Photo Curator errors

# Check OpenCV installation
cd /opt/photo-curator
source venv/bin/activate
python -c "import cv2; print(cv2.__version__)"

# Reinstall if needed
pip install --force-reinstall opencv-python

Remote access not working

# Check tunnel status
sudo systemctl status cloudflared

# Check tunnel logs
sudo journalctl -u cloudflared -n 100

# Test DNS
dig yourdomain.com

# Verify local services are running
curl http://localhost:2283/api/server-info

Port already in use

# Find what's using the port
sudo lsof -i :8080

# Change port in config
nano /opt/immich-server-manager/config/config.yaml
# Then restart: sudo systemctl restart immich-server-manager

Disk health monitoring not working

# Install smartmontools
sudo apt install smartmontools

# Test manually
sudo smartctl -a /dev/sda

# Check if drives are detected
lsblk

📁 Project Structure

immich-manager/
├── install.sh                  # Master installation script
├── README.md                   # This file
│
├── scripts/
│   ├── lib/
│   │   └── state-manager.sh   # Installation state tracking
│   ├── systemd/                # Service files
│   ├── 00-check-prerequisites.sh
│   ├── 10-install-server-manager.sh
│   ├── 20-install-photo-curator.sh
│   ├── 30-install-remote-access.sh
│   ├── 40-security-hardening.sh
│   ├── 50-test-installation.sh
│   └── health-check.sh
│
├── server-manager/
│   ├── src/                    # Python application
│   ├── config/                 # Configuration templates
│   ├── static/                 # Web dashboard
│   └── requirements.txt
│
└── photo-curator/
    ├── src/                    # Python application
    ├── config/                 # Configuration templates
    ├── static/                 # Web interface
    └── requirements.txt

🔗 API Documentation

Server Manager API

Base URL: http://localhost:8080

GET /health - Health check
GET /api/status - System status
GET /api/disks - Disk health
GET /api/metrics?hours=24 - System metrics
GET /api/backups - Backup history
POST /api/backup/now - Trigger backup
GET /api/alerts - Get alerts
POST /api/test-alert - Send test alert

Photo Curator API

Base URL: http://localhost:8081

GET /health - Health check
GET /api/status - Curator status
GET /api/users - List users
GET /api/photos/{user_id}/monthly - Monthly photos
POST /api/curate/{user_id} - Curate photos

Full API docs: http://localhost:8080/docs and http://localhost:8081/docs

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Immich - The amazing self-hosted photo management solution
Cloudflare - Free tunneling and DDoS protection
FastAPI - Modern Python web framework

📞 Support

Issues: Open an issue on GitHub
Immich Discord: https://discord.immich.app
Immich Docs: https://immich.app/docs

🗺️ Roadmap

Mobile app for Photo Curator
Advanced AI features (face recognition, scene detection)
Multi-site backup support (S3, Backblaze)
Email digest reports
Telegram/Discord bot integration
Photo book export to Shutterfly/Mixbook
Prometheus/Grafana integration

📊 Stats

Installation time: 30-60 minutes
Disk space required: ~500MB (without photos)
Memory usage: ~200MB (combined services)
CPU usage: <5% idle, ~20% during backups
Supported users: 6-20+ (tested with families)

Made with ❤️ for the Immich community

Star ⭐ this repo if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
health-monitor		health-monitor
migration-tools		migration-tools
photo-curator		photo-curator
scripts		scripts
server-manager		server-manager
.gitignore		.gitignore
API.md		API.md
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
SETUP.md		SETUP.md
claude.md		claude.md
install.sh		install.sh

License

nfeuer/immich-manager

Folders and files

Latest commit

History

Repository files navigation