Deploy Immich with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it ideal for running the multi-service Immich stack in production.

This guide walks you through deploying the complete Immich stack: the server, machine learning worker, PostgreSQL database, and Redis cache, all with persistent storage and automatic HTTPS.

Prerequisites

• A VPS with at least 4 vCPUs, 4 GB RAM, and 50 GB storage (more storage based on your photo library size)
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., photos.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:release
    restart: unless-stopped
    ports:
      - "2283:2283"
    environment:
      - DB_HOSTNAME=immich-db
      - DB_PORT=5432
      - DB_DATABASE_NAME=immich
      - DB_USERNAME=immich
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOSTNAME=immich-redis
      - REDIS_PORT=6379
      - UPLOAD_LOCATION=/usr/src/app/upload
      - IMMICH_MACHINE_LEARNING_URL=http://immich-ml:3003
      - TZ=${TZ:-UTC}
    volumes:
      - ../files/immich-upload:/usr/src/app/upload
      - ../files/immich-external:/usr/src/app/external
    depends_on:
      immich-db:
        condition: service_healthy
      immich-redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:2283/api/server/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

  immich-ml:
    image: ghcr.io/immich-app/immich-machine-learning:release
    restart: unless-stopped
    environment:
      - IMMICH_HOST=0.0.0.0
      - IMMICH_PORT=3003
    volumes:
      - ../files/immich-ml-cache:/cache
    healthcheck:
      test: ["CMD-SHELL", "python3 -c 'import urllib.request; urllib.request.urlopen(\"http://localhost:3003/ping\")' || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

  immich-db:
    image: tensorchord/pgvecto-rs:pg16-v0.2.0
    restart: unless-stopped
    environment:
      - POSTGRES_DB=immich
      - POSTGRES_USER=immich
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_INITDB_ARGS=--data-checksums
    volumes:
      - ../files/immich-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U immich -d immich"]
      interval: 10s
      timeout: 5s
      retries: 5

  immich-redis:
    image: redis:7-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: Immich requires PostgreSQL with the pgvecto.rs extension for vector search (used by smart search and face recognition). The tensorchord/pgvecto-rs image includes this extension pre-installed.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
DB_PASSWORD	PostgreSQL database password	a-strong-random-password
TZ	Server timezone	America/New_York

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. The database password must match between the immich-server and immich-db services — using a single ${DB_PASSWORD} variable ensures this.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/immich-upload — All uploaded photos and videos (this will be your largest volume)
• ../files/immich-external — Optional external library import directory
• ../files/immich-ml-cache — Machine learning model cache (downloads models on first run)
• ../files/immich-db-data — PostgreSQL database files with vector search indexes

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/immich) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features. For photo storage specifically, Immich also supports S3-compatible storage backends configured through its admin settings.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., photos.yourdomain.com)
3. Set the container port to 2283
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Immich server container. HTTPS is required for the mobile app to connect securely.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — all four containers (immich-server, immich-ml, immich-db, immich-redis) should start
3. Check the Logs tab for immich-server. Look for: Immich Server is listening on 0.0.0.0:2283
4. Open https://photos.yourdomain.com in your browser — you should see the Immich setup wizard
5. Create your admin account and complete the onboarding
6. Install the Immich mobile app (iOS / Android) and configure it with your server URL

Troubleshooting

Immich server can't connect to database Check that the immich-db container is healthy in Dokploy's logs. The PostgreSQL container may take 10-20 seconds to initialize on first launch. Verify DB_PASSWORD is set correctly in the environment variables — it must match between the server and database services.

Machine learning features not working (no face recognition or smart search) The immich-ml container downloads AI models on first startup, which can take several minutes depending on bandwidth. Check the ML container logs for download progress. Ensure the ../files/immich-ml-cache volume is writable and has sufficient space (roughly 2 GB for default models).

Photos upload but thumbnails are missing This usually indicates a permissions issue on the upload volume. Ensure the ../files/immich-upload directory is writable by the container. From your server shell, fix permissions: chmod -R 777 ../files/immich-upload (or set appropriate ownership).

Mobile app can't connect to server Verify your domain is accessible from outside your network. The mobile app requires HTTPS — ensure SSL is configured correctly in Dokploy. Test by opening https://photos.yourdomain.com/api/server/ping in a mobile browser — you should see {"res":"pong"}.

---

Learn more about Immich in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Immich.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.