↓ Skip to main content
mi-homes.org

Immich

Table of Contents

Immich is a self-hosted photo and video backup solution. This setup supports reusable template-based deployments for multiple instances.

Required variables
#

  • INSTANCE_NAME: Unique identifier for this instance
  • NAMESPACE: Kubernetes namespace
  • DOMAIN_NAME: Domain name for ingress
  • NFS_SERVER_IP: IP address of the NFS server
  • NFS_BASE_PATH: Base path on NFS server
  • DB_NAME: PostgreSQL database name (typically immich)
  • DB_PASSWORD: PostgreSQL database password
  • JWT_SECRET: JWT secret for authentication

Deploying a new instance
#

  1. Create required NFS directories under ${NFS_BASE_PATH}:

    • library/
    • ml-cache/
    • photos/
    • redis/

    postgres/ is not required when PostgreSQL uses local-path storage.

  2. Create instance configuration directory:

mkdir -p immich/instances/<instance-name>
  1. Create immich/instances/<instance-name>/instance.env:
INSTANCE_NAME=<instance-name>
NAMESPACE=immich-<instance-name>
DOMAIN_NAME=<your-domain>
NFS_SERVER_IP=<nfs-server-ip>
NFS_BASE_PATH=/volume2/immich/<nfs-path>
DB_NAME=immich
DB_PASSWORD=
JWT_SECRET=
  1. Deploy:
cd immich
./deploy-instance.sh <instance-name>

The deployment script validates variables, generates manifests, creates namespace and secrets, applies PVCs, deploys PostgreSQL, and deploys Immich via Helm.

Upgrading
#

cd immich
./deploy-instance.sh <instance-name>

Removal
#

  1. Uninstall Helm release:
helm -n <namespace> uninstall <instance-name>
  1. Remove PVCs:
kubectl -n <namespace> delete pvc --all
  1. Optionally delete namespace:
kubectl delete namespace <namespace>

Cloudflare Tunnel for Immich
#

Setup
#

  1. Create a Cloudflare tunnel in Zero Trust.
  2. Configure a public hostname:
    • Subdomain: immich
    • Domain: your domain
    • Type: HTTP
    • URL: immich-server.immich.svc.cluster.local:2283
  3. Deploy tunnel in Kubernetes:
kubectl apply -f cloudflare/namespace.yaml
cp cloudflare/secret.yaml.template cloudflare/secret.yaml
kubectl apply -f cloudflare/secret.yaml
kubectl apply -f cloudflare/deployment.yaml
  1. Verify:
kubectl -n cloudflare-tunnel get pods
kubectl -n cloudflare-tunnel logs -f deployment/cloudflared
  1. Test DNS and endpoint:
dig immich.yourdomain.com
nslookup immich.yourdomain.com