Immich with Cloudflare

Overview

Self-hosting Immich doesn't have to be complicated. This guide offers a simple, step-by-step way to deploy Immich using Portainer, and secure it with Cloudflare Tunnel.

Ready? Let's go.

1. Preparation

You only need two things before we start: - Portainer installed and configured. - Cloudflare account with Zero-Trust portal set up.

2. Download Files

We need two essential configuration files. You can securely download them directly from our GitHub repository:

• Download: docker-compose-portainer.yml
• Download: .env

3. Installation in Portainer

Open your Portainer dashboard and follow these steps:

1. Navigate to Stacks and click + Add stack.
2. Name the stack: immich.
3. Select Upload as the build method.
4. Upload the docker-compose-portainer.yml file you downloaded.
5. Scroll down to Environment variables.
6. Click Load variables from .env file.
7. Upload the .env file you downloaded.

If done correctly, you should instantly see your environment variables load into the UI.

Configure Your Environment

Before deploying, make sure you adjust these key variables to match your system:

• UPLOAD_LOCATION: The path storing your photos (e.g., /mnt/appdata/immich/uploads).
• DB_DATA_LOCATION: Database path. Best on an SSD (e.g., /opt/appdata/immich/database).
• TZ: Your timezone (e.g., Europe/London).
• DB_PASSWORD: A secure 32-character password.

Once everything looks good, click Deploy the stack.

[!NOTE] Please be patient. Portainer is now pulling all required Docker images in the background. This can take 10–15 minutes the very first time.

4. Initial Setup

Once Portainer shows all containers as "Healthy":

1. Open a browser and visit your server's IP address on port 2283: http://YOUR_SERVER_IP:2283
2. Complete the Setup Wizard (admin account, theme, language).
3. We highly recommend turning on Enable Version check and Enable Map features.
4. Click Finish.

Congratulations! You have deployed Immich.

5. Remote Access (Cloudflare)

To access your photos securely from anywhere in the world without exposing your router:

1. Go to your Cloudflare Zero Trust Dashboard.
2. Navigate to Networks > Connectors.
3. Next to your tunnel, click the three dots and choose Configure.
4. Go to Public applications routes and click Add a published application.

Fill it out exactly like this: - Subdomain: photos (or immich) - Domain: yourdomain.com - Service: HTTP - URL: 127.0.0.1:2283

Click Save. Wait 60 seconds, and you can now securely access Immich at https://photos.yourdomain.com.

6. Mobile App Integration

Connect your phone to instantly and automatically back up your camera roll.

1. Download Immich for iOS or Android.
2. Look for the Server Endpoint URL input box.
3. Type in your new Cloudflare URL exactly like this: https://photos.yourdomain.com/api (Make sure to include /api).
4. Log in with your admin account.
5. Tap the Cloud icon (top right) → Select folders → choose DCIM/Screenshots → Enable Backup.

Your photos will now sync automatically whenever connected to Wi-Fi. It's truly set-and-forget.

7. How to Update Immich

Updates are safe and easy. Whenever a new version is released:

1. Stop: In Portainer, go to Stacks → immich → select all containers → Stop.
2. Backup: In your server's terminal, duplicate your database folder: bash cd /opt/appdata/immich/database sudo cp -r ./database ./database.bak
3. Verify: Review the Immich Release Notes for breaking changes.
4. Update: In Portainer Stacks → immich → Editor → click Update the stack. Make sure to enable "Re-pull image and redeploy", then confirm.

Once all containers return to healthy, you are all set!