diff --git a/cloud/README.md b/cloud/README.md index 33be6d6..cac07ed 100644 --- a/cloud/README.md +++ b/cloud/README.md @@ -36,4 +36,4 @@ docker exec nextcloud-aio-mastercontainer grep password /mnt/docker-aio-config/d ``` ## Immich -Work in progress. +Self-hosted Google Photos alternative with mobile backup, facial recognition, and automatic organization. See the full setup guide in the [immich](https://github.com/TechHutTV/homelab/tree/main/cloud/immich) directory. diff --git a/cloud/immich/.env b/cloud/immich/.env new file mode 100644 index 0000000..2b8a946 --- /dev/null +++ b/cloud/immich/.env @@ -0,0 +1,26 @@ +# Immich Environment Variables +# Documentation: https://docs.immich.app/install/environment-variables + +# The location where your uploaded files are stored +UPLOAD_LOCATION=./library + +# The location where your database files are stored +# Network shares are NOT supported for the database +DB_DATA_LOCATION=./postgres + +# Timezone - Change to your timezone +# https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List +TZ=America/New_York + +# The Immich version to use. You can pin this to a specific version like "v2.1.0" +IMMICH_VERSION=v2 + +# Connection secret for postgres. You should change it to a random password +# Please use only the characters `A-Za-z0-9`, without special characters or spaces +DB_PASSWORD=postgres + +################################################################################### +# The values below this line do not need to be changed +################################################################################### +DB_USERNAME=postgres +DB_DATABASE_NAME=immich diff --git a/cloud/immich/README.md b/cloud/immich/README.md new file mode 100644 index 0000000..f4abc7f --- /dev/null +++ b/cloud/immich/README.md @@ -0,0 +1,111 @@ +# Immich - Self-Hosted Photo and Video Backup + +Immich is a self-hosted alternative to Google Photos with a focus on privacy and control. It keeps your photos and videos on your own hardware with support for RAW files, facial recognition, and automatic organization. The mobile app for both [Android](https://play.google.com/store/apps/details?id=app.immich) and [iOS](https://apps.apple.com/app/immich/id1613945652) includes built-in photo backup support. + +> [!NOTE] +> Most of the steps below are from their [official docs](https://docs.immich.app/install/docker-compose). Please check those out as well. + +## Prerequisites +1. A server running Docker. Checkout our [docker guide](https://techhut.tv/7-docker-basics-for-beginners/) to get this going. +2. Recommended 6GB of RAM and 4 core CPU. ([learn more](https://immich.app/docs/install/requirements)) +3. Enough storage for your media. Your needed amount will depend on your photography habits and current media collection. + +## Setup + +### Prepare Your Environment +Create directories for Immich data. You may want to change the `library` location to a network drive or another location if your root file system has less storage than you may need. Checkout this example of [mounting drives](https://techhut.tv/auto-mount-drives-in-linux-fstab/) in Linux. +```bash +mkdir -p ~/docker/immich +``` + +Navigate to the directory and download the `compose.yaml` and `.env` files from this repo. +```bash +cd ~/docker/immich +wget https://github.com/TechHutTV/homelab/raw/refs/heads/main/cloud/immich/compose.yaml && wget https://github.com/TechHutTV/homelab/raw/refs/heads/main/cloud/immich/.env +``` + +### Configure the .env File +```bash +nano .env +``` + +**Mandatory Changes:** +- `DB_PASSWORD` — Change to a random strong password. Use only `A-Za-z0-9` to avoid issues with Docker parsing. +- `TZ` — Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). +- `UPLOAD_LOCATION` — Verify or change the path where your photos will be stored. +- `DB_DATA_LOCATION` — Path for the PostgreSQL database. Network shares are **not** supported here. + +### Deploy the Stack +```bash +docker compose up -d +``` +Wait a few minutes for all containers to initialize. Check logs if any containers fail to start. +```bash +docker logs immich_server +``` + +### Access Immich +1. Open `http://your-server-ip:2283` in your browser +2. Create an admin account (first user becomes admin) +3. Configure settings: + - **Storage Template** — Configure to make your library [human readable](https://immich.app/docs/install/post-install). + - **Machine Learning** — Enable facial recognition if using the ML container. + +## Mobile App Setup +1. Install Immich from the [App Store](https://apps.apple.com/app/immich/id1613945652) or [Play Store](https://play.google.com/store/apps/details?id=app.immich) +2. Connect to your server: + - Server URL: `http://your-server-ip:2283` + - Use your admin credentials +3. Enable auto-backup in the app settings + +## Remote Access +- **[NetBird](https://netbird.io/) (Recommended)** — A zero-trust networking solution using WireGuard. Access Immich securely from anywhere without exposing ports. Follow our [NetBird setup guide](https://techhut.tv/self-host-netbird-pocketid) to get started. +- **Reverse Proxy** — Setup NGINX Proxy Manager for domain-based access ([video guide](https://www.youtube.com/watch?v=79e6KBYcVmQ)). Forward `photos.yourdomain.com` to `http://immich-server:2283`. + +## Optional Configuration + +### Hardware Transcoding +Uncomment the `devices` section in the `immich-server` service in `compose.yaml` to enable Intel QuickSync for video transcoding. [Learn more](https://immich.app/docs/features/hardware-transcoding/#single-compose-file). + +### Hardware-Accelerated Machine Learning +Uncomment and adjust the `immich-machine-learning` section in `compose.yaml`. [Learn more](https://immich.app/docs/features/ml-hardware-acceleration). + +### External Libraries +You can add existing photo directories as [external libraries](https://immich.app/docs/features/libraries/). + +### Disable Machine Learning +If you don't need facial recognition or smart search, remove the entire `immich-machine-learning` service from `compose.yaml`. + +## Storage Templates + +Storage templates let you automatically sort photos into folders based on metadata like date, camera model, or custom tags. This makes your library human-readable and easier to back up. + +Example template: +``` +{{y}}/{{MMMM}}-{{DD}}/{{filename}} +``` +Generates: `2024/July-15/IMG_1234.jpg` + +Go to **Settings** > **Storage Template** in the Immich web UI to configure this. You can apply templates to new uploads and re-run them on existing libraries. + +## Backup Strategy +- Regularly back up your database directory (`DB_DATA_LOCATION`) +- Use an external backup tool or service to keep a copy of your photo library offsite + +## Troubleshooting + +**Port Conflicts** — Ensure port 2283 is available on your host. + +**Permission Errors** — Verify volume permissions with `ls -l` on your upload and database directories. + +**ML Container Failing** — Try disabling GPU support or allocate more RAM. + +**Reset Admin Password:** +```bash +docker exec immich_server npm run reset-admin-password +``` + +## Maintenance +- Re-deploy with updated image tags to update. Follow [Immich releases](https://github.com/immich-app/immich/releases). +- Monitor your `UPLOAD_LOCATION` directory for storage growth. +- Set retention policies in the Immich web UI as needed. diff --git a/cloud/immich/compose.yaml b/cloud/immich/compose.yaml new file mode 100644 index 0000000..be658d5 --- /dev/null +++ b/cloud/immich/compose.yaml @@ -0,0 +1,74 @@ +############################################################################# +# Immich - Self-Hosted Photo and Video Backup +# https://immich.app +# +# Make a '.env' file in the same directory as this file. +# Adjust any settings as needed, especially DB_PASSWORD and volume paths. +# https://github.com/TechHutTV/homelab/tree/main/cloud/immich#setup +############################################################################# + +services: + immich-server: + container_name: immich_server + image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} + volumes: + - ${UPLOAD_LOCATION}:/data + - /etc/localtime:/etc/localtime:ro + env_file: + - .env + ports: + - 2283:2283 + depends_on: + - redis + - database + restart: always + healthcheck: + disable: false + # Hardware Transcoding (Intel) - uncomment if needed + # devices: + # - /dev/dri:/dev/dri + + immich-machine-learning: + container_name: immich_machine_learning + image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release} + volumes: + - model-cache:/cache + env_file: + - .env + restart: always + healthcheck: + disable: false + # Hardware-Accelerated ML (Intel OpenVINO) - uncomment and change image tag if needed + # image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-openvino + # device_cgroup_rules: + # - 'c 189:* rmw' + # devices: + # - /dev/dri:/dev/dri + # volumes: + # - /dev/bus/usb:/dev/bus/usb + # - model-cache:/cache + + redis: + container_name: immich_redis + image: docker.io/valkey/valkey:9-alpine + healthcheck: + test: redis-cli ping || exit 1 + restart: always + + database: + container_name: immich_postgres + image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 + environment: + POSTGRES_PASSWORD: ${DB_PASSWORD} + POSTGRES_USER: ${DB_USERNAME} + POSTGRES_DB: ${DB_DATABASE_NAME} + POSTGRES_INITDB_ARGS: '--data-checksums' + volumes: + - ${DB_DATA_LOCATION}:/var/lib/postgresql/data + shm_size: 128mb + restart: always + healthcheck: + disable: false + +volumes: + model-cache: