Installation
Get Noodle Gallery running with Docker Compose in under five minutes. Compatible with any existing Immich setup.
Migrating from upstream Immich
Already running Immich? Switching is easy — just swap two image names in your docker-compose.yml and you're done.
The current version is v4.
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} image: ghcr.io/open-noodle/gallery-server:${IMMICH_VERSION:-release} image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release} image: ghcr.io/open-noodle/gallery-ml:${IMMICH_VERSION:-release} Then pull the new images and restart:
docker compose pull && docker compose up -dYour data, database, and configuration are fully compatible — no migration steps needed.
docker exec -t your-db-container pg_dumpall -U postgres > backup.sql Requirements
docker compose (v2 plugin) Download the configuration files
Create a directory for Noodle Gallery and download the Docker Compose file and environment template.
mkdir ./noodle-gallery
cd ./noodle-gallery
wget -O docker-compose.yml https://github.com/open-noodle/gallery/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/open-noodle/gallery/releases/latest/download/example.envexample.env to .env. Configure environment
Open the .env file and configure your settings. The essential options are at the top — S3 storage is optional.
# ── Core Settings ──────────────────────────────────────────────
# Where your photos and videos are stored
UPLOAD_LOCATION=./library
# Where PostgreSQL stores its data (must be local disk, not a network share)
DB_DATA_LOCATION=./postgres
# Timezone: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TZ=Etc/UTC
# Container image tag — "release" for latest, "v4" for latest v4.x, or pin e.g. "v4.0.1"
IMMICH_VERSION=release
# IMPORTANT: change this to a random password (A-Za-z0-9 only)
DB_PASSWORD=change-me-to-something-random
# These defaults rarely need changing
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
# ── S3-Compatible Storage (optional) ──────────────────────────
# Uncomment to store uploads in S3 instead of local disk.
# Works with AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, etc.
# IMMICH_STORAGE_BACKEND=s3
# IMMICH_S3_BUCKET=my-gallery-bucket
# IMMICH_S3_REGION=us-east-1
# IMMICH_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
# IMMICH_S3_ACCESS_KEY_ID=
# IMMICH_S3_SECRET_ACCESS_KEY=
# IMMICH_S3_SERVE_MODE=redirect
# IMMICH_S3_PRESIGNED_URL_EXPIRY=3600Variable reference
UPLOAD_LOCATION Path for uploaded media. Use an absolute path in production. DB_DATA_LOCATION Path for PostgreSQL data. Must be a local disk — network shares are not supported. DB_PASSWORD Database password. Only A-Za-z0-9 characters. Change before first run. IMMICH_VERSION Container tag. release = latest, v4 = latest v4.x, or pin to a specific version. IMMICH_STORAGE_BACKEND Set to s3 to store new uploads in S3. Default: disk. Existing disk files continue working. IMMICH_S3_BUCKET S3 bucket name. Required when using S3 storage. IMMICH_S3_ENDPOINT Custom endpoint for non-AWS services (MinIO, R2, B2). Omit for AWS S3. IMMICH_S3_SERVE_MODE redirect returns presigned URLs (faster). proxy streams through the server. Default: redirect. Start the containers
From your noodle-gallery directory, run:
docker compose up -dThis pulls the container images, creates the database, and starts all services. The first run downloads ~2 GB of images and may take a few minutes.
docker compose (with a space), not docker-compose (with a hyphen). The standalone docker-compose binary is deprecated. Access the web UI
Open http://your-server-ip:2283 in your browser. You'll be prompted to create the first admin account.
http://localhost:2283 The mobile app (Android & iOS) connects to the same URL. Download it from the Play Store or App Store and point it to your server.
GPU acceleration optional
For faster machine learning inference (face detection, CLIP, pet detection), use a GPU-accelerated ML image:
# In docker-compose.yml, change the ML image tag:
image: ghcr.io/open-noodle/gallery-ml:${IMMICH_VERSION:-release}-cuda
Available tags: -cuda (NVIDIA), -rocm (AMD), -openvino (Intel).
Upgrading
To update to the latest version:
docker compose pull
docker compose up -dDatabase migrations run automatically on startup. Always back up your database before major version upgrades.