How to Self-Host Immich and Access Your Photo Library from Anywhere

Understand the deployment before installing it

Immich is a self-hosted photo and video management application with web and mobile clients. The mobile applications can upload selected device albums to your server, while the web interface provides library browsing and administration. Features such as thumbnail generation, metadata extraction, search, face processing, and video processing are handled by services and background jobs within the deployment.

Self-hosting changes who operates the storage and application. It does not eliminate the need for security, backups, monitoring, or sufficient capacity. Your server remains responsible for storing the originals and application data, and publishing the login page creates an internet-reachable application that must be maintained accordingly.

The resulting request path is:

Phone or browser
        |
        v
Public Localtonet HTTPS address
        |
        v
Selected Localtonet relay
        |
        v
Outbound Localtonet client on the server
        |
        v
127.0.0.1:2283
        |
        v
Immich server
   |        |        |
   v        v        v
PostgreSQL  Job queue  Machine-learning service
        |
        v
Photo and video storage

Prerequisites and capacity planning

This tutorial uses a dedicated or always-on Ubuntu host. Other operating systems can run Docker, but their Docker installation and storage behavior differ. The Ubuntu-specific repository commands below must not be copied to Debian or another distribution. If you use a different operating system, install a currently supported Docker Engine and Docker Compose plugin using that operating system's official Docker instructions, then resume at the Immich installation section.

Immich updates its documented requirements as the application evolves. Before provisioning hardware, compare your system with the current Immich requirements documentation. Do not treat old blog estimates as permanent minimums. In particular, machine-learning jobs, video transcoding, large imports, and concurrent mobile uploads can require substantially more resources than an idle server.

You will need an Ubuntu account with administrative access, a persistent directory for the deployment, a current Docker Engine with the Compose plugin, and a Localtonet device token for the machine that will run the tunnel. You should also decide where the media library and database will live before uploading a large collection.

Install Immich with the official Docker Compose release

Install Docker Engine on Ubuntu

The following commands intentionally configure Docker's Ubuntu repository. They are not Debian instructions. Review Docker's current Ubuntu installation documentation if your Ubuntu release, package state, or security policy requires a different installation path.

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Confirm that Docker and the Compose plugin are available:

sudo docker version
sudo docker compose version
sudo docker run --rm hello-world

You can continue using sudo docker. If you add a user to the docker group, understand that membership grants privileges comparable to root access on the host. Make that change only for trusted administrative users.

Download the Compose and environment files from a release

Use the files attached to an Immich release rather than copying an old Compose definition from a tutorial. This avoids hardcoding container image tags and service definitions that may no longer match one another.

mkdir -p ~/immich-app
cd ~/immich-app

wget -O docker-compose.yml \
  https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

wget -O .env \
  https://github.com/immich-app/immich/releases/latest/download/example.env

The latest URL resolves to the current release when you download the files. It does not guarantee that a future release will be compatible with an old environment file or an old database state. Keep a copy of the exact Compose file used for each controlled deployment and read the release notes before updating.

Configure persistent locations and secrets

Open the downloaded environment file:

nano ~/immich-app/.env

Preserve the variable names and comments supplied by the current release. Configure the upload location, database data location, timezone, database password, and version value according to that file and the current Immich environment-variable reference. Do not add variables copied from old tutorials unless they are present in the current reference.

This guide deliberately does not instruct you to add IMMICH_SERVER_URL. Its availability and effect must be established from the environment-variable reference for the release you deploy. A public tunnel URL does not, by itself, justify adding an undocumented environment variable.

Restrict casual access to the environment file and create the configured directories if the release instructions require host paths:

chmod 600 ~/immich-app/.env

Absolute host paths are easier to identify during recovery, but the right locations depend on your storage layout. If you use a mounted data disk, confirm that it is mounted before Docker starts. Otherwise, Docker may write into an empty mount-point directory on the root filesystem, causing unexpected disk exhaustion.

Start and inspect the deployment

cd ~/immich-app
sudo docker compose up -d
sudo docker compose ps

Do not rely on copied example output or a fixed startup delay. Container names, health states, and startup time can change by release and hardware. Wait for the services to become ready, then inspect logs if any service restarts, exits, or remains unhealthy:

sudo docker compose logs --tail=200
sudo docker compose ps

For a continuously updating view during initial startup, use:

sudo docker compose logs -f

Press Ctrl+C to leave the log view. This does not stop containers started in detached mode.

Verify Immich on the local host

Test the published port from the server itself before introducing a public tunnel:

curl -I http://127.0.0.1:2283/

An HTTP response confirms that something is listening and responding. It does not validate every background service, login flow, upload, or processing job. Open http://127.0.0.1:2283 in a browser on the host, or use the server's LAN address and port from a trusted device if the Docker port binding permits LAN access.

Complete Immich's current first-run flow and create the initial administrator account. Use a strong, unique password stored in a password manager. After signing in, inspect the administration interface, confirm that expected services and jobs are healthy, and upload a non-sensitive test image before importing an entire library.

Prepare Immich for safe public exposure

A tunnel removes the need to accept unsolicited inbound connections at your router, but it still creates a public route to the configured application. Anyone who discovers the public address can attempt to load the login page, test credentials, or probe the exposed web service. Treat this as internet exposure, not as a private LAN deployment.

Protect the host as well as the application. Apply Ubuntu security updates, restrict SSH administration, remove unused services, keep Docker and its plugins current, and limit interactive access to trusted administrators. Avoid storing personal photos in world-readable directories. Confirm that backup destinations are protected from other users and that credentials are not included in diagnostic bundles.

If the deployment is used by a household or organization subject to contractual, legal, or regulatory obligations, review whether routing public photo traffic through a selected third-party relay is acceptable for that use case. This article does not claim that a standard tunnel configuration satisfies any particular compliance framework.

Expose Immich through a Localtonet HTTP tunnel

With Localtonet, the client on your Immich host establishes an outbound connection to one of our relay servers. You do not need inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel provides a public HTTPS address that forwards to the local Immich server.

HTTP tunnel Process Type can be Random Sub Domain, Custom Sub Domain, or Custom Domain. All three serve the target at a public HTTPS address. Availability can vary by plan, client version, or current dashboard configuration, so do not assume that a specific subdomain, custom domain, or relay region will be available. Obtain current choices directly from the dashboard.

The target configuration for a same-host deployment is concise:

Test the public address in a private browser window while signed out. The login page may be visible, but personal assets and administrative functions must not be available without authentication. Also confirm that the address stops forwarding when you intentionally stop the tunnel. This validates the expected lifecycle and helps you understand how to shut down access during maintenance.

Configure and verify mobile photo backup

Install the current Immich mobile application through the official application store for your platform. Use your assigned Localtonet HTTPS address as the server address after the public tunnel has been verified. Sign in with a non-administrator Immich account for normal mobile use unless administration from the phone is specifically required.

The exact permission names and background-execution controls differ between iOS and Android releases. Grant Immich access only to the photo collections you intend to back up. If you select limited photo access, newly captured photos may not become available to the app automatically unless the operating system selection is updated.

For the first import, use a small representative set that includes a photo and, if relevant, a video. Verify the resulting assets from another device. Large historical imports are easier to diagnose when the base connection, authentication, permissions, storage, and background jobs have already been tested.

Back up and restore Immich safely

An Immich recovery requires more than a copy of the PostgreSQL data directory or a folder full of originals. Protect the database metadata and every filesystem location required by the deployed release. Database metadata connects users, albums, assets, generated files, and application state. Filesystem data contains the media and other files used by the application. A valid recovery needs a compatible set.

Database restore syntax is sensitive to the PostgreSQL image, extensions, initialization state, and Immich release. Do not pipe a complete cluster dump into an already initialized production database and call that a fresh restore. Existing roles, schemas, extensions, and migrations can conflict, and a successful shell exit does not prove that the library is consistent.

Use the current Immich backup and restore procedure that corresponds to the release you actually run. The safe recovery sequence is:

Routine operations, updates, acceleration, and troubleshooting

Monitor storage, service health, and logs

Photo servers tend to grow continuously. Monitor both the media filesystem and the filesystem containing Docker and PostgreSQL. Storage exhaustion can interrupt uploads, prevent database writes, break migrations, and leave background jobs failing.

df -h
df -i
cd ~/immich-app
sudo docker compose ps
sudo docker compose logs --tail=200

df -h checks byte capacity, while df -i checks inode consumption. Both can cause a filesystem to appear unusable. Review logs after updates, large imports, model changes, or repeated mobile failures. In the Immich administration interface, inspect background-job status and failed work rather than assuming that a visible upload has completed all processing.

Use controlled updates

Do not automatically pull a new release into an untested photo server. Read the current Immich release notes, identify breaking changes or migration requirements, verify a recent backup, and preserve the currently deployed Compose file and version information.

cd ~/immich-app

sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=200

Run those commands only after reviewing the release and updating the release-provided files when required by Immich. Pulling images alone does not update a Compose definition that has changed. After the update, test local login, asset browsing, a small upload, background jobs, and the public tunnel.

If an update fails, stop and collect logs before making destructive changes. A rollback may require the previous Compose file, previous container images, and a database restore because database migrations are not necessarily reversible by selecting an older image. Do not assume that changing a version value alone safely reverses an update.

Keep the Localtonet client persistent

Remote access depends on three layers remaining available: Immich, Docker, and the Localtonet client with its tunnel started. Configure the Localtonet application to start according to the supported startup behavior of the installed client version, then verify that behavior after a controlled reboot. Do not invent a service unit or command from an unrelated client release.

After rebooting the host, check:

• the storage volumes are mounted before Immich starts;
• the Immich containers are running and healthy;
• http://127.0.0.1:2283 responds locally;
• the correct Localtonet device is connected;
• the tunnel is running, not merely created;
• the public address works from outside the LAN;
• a test mobile upload completes.

Treat hardware acceleration as an optional, device-specific project

The base deployment uses the release's default processing path. Hardware acceleration requires more than adding a single Compose line. A supported configuration can require host GPU drivers, device permissions, container runtime support, release-matched auxiliary Compose files, a supported acceleration backend, and separate configuration for video transcoding and machine learning.

Do not assume that an auxiliary file was downloaded merely because you downloaded docker-compose.yml and example.env. Obtain any required acceleration files from the same Immich release and follow the current hardware transcoding documentation and machine-learning acceleration documentation. Support varies by operating system, processor, GPU, driver, architecture, and release.

Verify acceleration through service logs and a controlled processing job. Watch host CPU and accelerator utilization, inspect errors, and confirm that output files remain playable. Keep the prior working configuration so that you can return to CPU processing if the accelerated path fails.

Diagnose failures by layer

If you add another reverse proxy in front of Immich, test forwarded headers, request timeouts, connection upgrades, and upload behavior according to Immich's current reverse-proxy documentation. Do not copy configuration directives from a different proxy product. In the Localtonet workflow described here, point the HTTP tunnel directly at the Immich server unless your architecture has a specific, tested reason to add another local proxy.

Frequently asked questions