How to Self-Host Immich and Access It Securely

Understand the Immich and Localtonet architecture

A reliable deployment separates the photo application from the remote-access layer. Immich runs as a group of containers on a host you control. Those containers provide the web application, API, database, cache, and machine-learning functions required by the current Docker Compose deployment. Your configured storage holds original assets, generated media, application data, and database data.

Localtonet does not install Immich, replace its database, or manage Immich users. Our platform begins with a working local endpoint. The Localtonet client establishes an outbound connection to a selected Localtonet relay server and forwards requests from a public HTTPS address to the configured local IP address and port.

The official Immich Docker Compose instructions currently publish the server on port 2283. A typical local endpoint is therefore http://localhost:2283 on the host or http://192.168.1.50:2283 from another device on the same LAN. Replace the example address with the actual address of your server. If you modify the Compose port mapping or place another proxy in front of Immich, use the resulting endpoint instead of assuming port 2283.

Check the host, Docker, architecture, and storage prerequisites

Immich is more demanding than a simple static gallery. Upload processing, thumbnail generation, video transcoding, PostgreSQL, and machine-learning workloads all affect the host. Confirm the following requirements before downloading the Compose files.

Hardware and operating system

Immich recommends a 64-bit Linux or Unix-like operating system such as Ubuntu or Debian. A full virtual machine is also supported as a deployment model. Docker inside an LXC container is not recommended, although advanced users may be able to make it work. If an LXC deployment causes problems, the Immich project recommends moving to a supported virtual-machine deployment.

The minimum memory requirement is 6 GB of RAM, with 8 GB recommended. The minimum CPU allocation is two cores, with four cores recommended. Systems with only 4 GB of RAM may run Immich with machine-learning features disabled, but that is below the normal minimum for a smooth experience, especially during asset uploads.

Immich supports amd64 and arm64. Starting with Immich v3, the machine-learning container on amd64 requires the x86-64-v2 microarchitecture level or newer. Most CPUs released since approximately 2012 support it, but virtual machines can hide or downgrade the exposed CPU model. Verify that the VM exposes a compatible microarchitecture. Immich v2.7.5 was the final x86-64-v1-compatible release, but that release is no longer supported and requires a matching server version, so it is not an appropriate basis for a new deployment.

Install Docker with the Compose plugin

Immich requires Docker and the modern Docker Compose plugin. On Linux, use Docker Engine installed through the current Docker instructions for your distribution. Docker Desktop is available for Windows and macOS but is not recommended for Linux servers.

Verify both Docker and Compose before proceeding:

docker --version
docker compose version

The second command must contain a space. The old standalone docker-compose command is deprecated and is not supported by current Immich installations.

Plan media and database storage separately

The standard environment file uses UPLOAD_LOCATION for Immich-managed media and DB_DATA_LOCATION for PostgreSQL data. These locations have different operational requirements even when they reside on the same server.

Use a Unix-compatible filesystem with working user and group ownership and permissions. Plan additional space beyond the original photo and video collection. Immich estimates that generated thumbnails and transcoded video increase library size by an average of approximately 10 to 20 percent. Imports, database backups, logs, and temporary processing can require additional headroom, so do not size the filesystem exactly to the current source library.

PostgreSQL database files are typically about 1 to 3 GB. Place DB_DATA_LOCATION on local SSD storage where possible. Never place the active PostgreSQL data directory on NFS, SMB, or another network share. If Docker memory limits are applied, PostgreSQL requires at least 2 GB of RAM.

For a Windows deployment that needs a Docker volume for PostgreSQL, change the database location in .env:

DB_DATA_LOCATION=pgdata

Then add the named volume to the bottom-level volumes section in docker-compose.yml. Preserve the existing model-cache entry:

volumes:
  model-cache:
  pgdata:

Do not confuse this database volume with the media library. A named PostgreSQL volume solves a database filesystem compatibility problem, but uploaded photos and videos still need their own durable, monitored, and backed-up location.

Prepare a capacity and recovery plan

Record the capacity of every filesystem involved in the deployment. Decide how alerts will be generated before any filesystem fills. A full database filesystem can interrupt application operations, while a full upload filesystem can cause failed or incomplete imports.

Immich recommends a 3-2-1 backup plan for precious photos and videos: maintain three copies, on two different storage types or failure domains, with one copy off-site. Synchronization alone is not a complete backup because deletion or corruption can be synchronized too. At least one copy should retain historical versions or snapshots.

Install Immich with the official Docker Compose workflow

The supported Compose workflow downloads a release-provided docker-compose.yml and example environment file. Run the following commands from a normal administrative account with permission to use Docker. The directory name is only an example, but keep the downloaded files together.

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

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
TZ=Etc/UTC
IMMICH_VERSION=release
DB_PASSWORD=replace_with_a_unique_private_value
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

docker compose up -d

Restrict access to the environment file because it contains the database password:

chmod 600 .env

That permission command is appropriate on Unix-like filesystems. It does not replace proper host access controls, encrypted backups, or a secrets-management process.

Understand the important environment values

Verify container health, local access, uploads, and persistence

Do not expose the installation immediately after the first page load. Establish a local baseline that covers every essential path: container status, logs, authentication, storage writes, restart behavior, and retrieval.

Check container status

cd ./immich-app
docker compose ps

Review every service shown by the release-provided Compose file. A container that repeatedly restarts, remains unhealthy, or exits requires investigation even if part of the web interface loads.

Inspect recent logs across the stack:

docker compose logs --tail=200

Follow logs while reproducing a problem:

docker compose logs -f

Press Ctrl+C to stop following logs. This stops the log display, not the containers. Look for database connection failures, migration errors, incompatible CPU instructions, storage permission errors, repeated restarts, and out-of-space messages.

Open the default local endpoint

On the Immich host, open:

http://localhost:2283

From another LAN device, replace the hostname with the server's private address:

http://192.168.1.50:2283

The second address is only an example. Use the actual address of your Immich host. If you customized the published port in docker-compose.yml, use that configured port instead.

Complete account setup before exposure

Finish the first-run administrator registration and confirm that login works. Use a unique password. Create ordinary user accounts for routine access rather than sharing the administrator account. Do not make the application publicly reachable while initial registration is still open or temporary credentials are in use.

Upload and retrieve a non-sensitive test asset

Upload one small, non-sensitive photo through the web interface. Confirm that it appears in the timeline, opens at full size, and produces the expected thumbnail. If you plan to upload videos, repeat the test with a short non-sensitive video and allow processing to complete.

This checks more than the browser connection. It exercises database writes, media storage, background jobs, thumbnail generation, and retrieval. Review the logs if processing remains pending or the full asset cannot be opened.

Restart the stack and verify persistence

docker compose restart
docker compose ps

After the services return, sign in again and confirm that the uploaded test asset still exists. Restarting is an important test because an incorrectly mounted directory can appear to work until a container is recreated.

You can also perform a full controlled stop and start:

docker compose down
docker compose up -d
docker compose ps

Do not add -v to docker compose down during routine operation. Removing volumes can destroy data stored in Docker-managed volumes.

Test from the future Localtonet client device

Open the Immich local endpoint from the exact machine that will run the Localtonet client. If the client will run on the Immich host, test http://localhost:2283. If it will run on another LAN machine, test the server's private IP address and port from that machine.

Publish Immich with a Localtonet HTTP tunnel

Immich is a web application, so use a Localtonet HTTP tunnel for this workflow. Our client can run directly on the Immich host or on another device that can reach the Immich server over the LAN. The tunnel is available only while that selected device is connected and the tunnel is running.

Random Sub Domain, Custom Sub Domain, and Custom Domain Process Types all serve the configured local content at a public HTTPS address. Exact custom-domain DNS requirements can change, so confirm the current dashboard and documentation before editing DNS.

For the current product setup sequence, see the Localtonet HTTP tunnel documentation.

Validate Immich reverse-proxy and mobile-client behavior

A public browser may load the login page even when a proxy path is incomplete. Immich uses more than one route and may maintain long-running or upgraded connections. Validate the whole application rather than treating the first HTML response as proof of compatibility.

Forward the root application, not only an API path

Immich reverse-proxy guidance requires the complete root location to be proxied. Do not construct a route that forwards only /api. The web interface, API, discovery paths, assets, and other routes need the same public origin.

Preserve the public host and request scheme

A conventional reverse proxy in front of Immich should preserve the original host and communicate the client address and public scheme using the appropriate forwarded headers. The commonly required set includes:

• Host
• X-Real-IP
• X-Forwarded-For
• X-Forwarded-Proto

Immich should understand that the public request used HTTPS even though the local target commonly uses HTTP on port 2283. If redirects point to a private hostname, use the wrong scheme, or return to a LAN address, review the public URL and forwarded-header behavior before changing user credentials.

Confirm upgraded and long-running connections

Reverse proxies used with Immich should support WebSocket upgrades where required by the current release. They also need timeouts long enough for uploads and other long-running operations. A login page that works while progress updates, uploads, or interactive actions fail can indicate that these behaviors are not passing through the public route correctly.

Localtonet tunnel options and behavior can vary by current product configuration. Test the real workflow through the assigned URL. If a feature fails only through the tunnel, compare it with the current Immich reverse-proxy requirements and the current Localtonet HTTP tunnel documentation rather than adding unverified headers or options.

Test realistic upload sizes

Start with a small non-sensitive asset. Then test a representative photo and, if relevant, a representative video. Large uploads can expose request-size limits, proxy timeouts, unstable client connectivity, insufficient temporary space, or a full upload filesystem that a simple page request will not reveal.

Do not claim success based only on the HTTP status of the initial upload. Confirm that the asset appears, processing finishes, the original can be opened, and the item remains available after a restart.

Use the public root URL in the mobile app

When the Immich mobile application requests a server endpoint, enter the assigned Localtonet HTTPS root URL exactly as shown. Do not append a guessed /api suffix. Test the same URL in the phone's browser outside the LAN before configuring mobile backup.

If the installed Immich version provides an external-domain or public-URL setting, configure it with the stable public origin you intend to use and follow that release's administration guidance. Interface names can change, so do not guess a field that is absent from your version. After changing an external URL, retest login, sharing, OAuth callbacks if enabled, and the mobile client.

Secure the photo library before regular remote use

Personal media can expose faces, documents, locations, homes, routines, and relationships. Protect the deployment as sensitive infrastructure. Security depends on the host, Docker, Immich accounts, integrations, backups, and tunnel lifecycle working together.

Separate every credential type

The Immich administrator password, ordinary user passwords, PostgreSQL password, Immich API keys, OAuth credentials, and Localtonet device token serve different purposes. Never reuse one secret for another role.

If a credential may have been exposed, use the supported control for that credential type to revoke, remove, replace, or reissue it. Removing an Immich API key does not disconnect a Localtonet device. Stopping a tunnel does not change an Immich password. Changing the database password requires coordinated application configuration and should not be performed casually.

Use least privilege inside Immich

Reserve the administrator account for maintenance. Give each regular user an individual account and remove accounts that are no longer needed. Review API keys, OAuth integrations, shared albums, partner sharing, public links, and read-only galleries separately.

Keep the host private

Publish the Immich web endpoint, not Docker management sockets, PostgreSQL, shell access, storage protocols, or the host administration interface. Do not create additional tunnels for internal services merely because they are available on the same machine.

Control tunnel availability

For occasional access, stop the tunnel when it is not required. For an always-available family deployment, monitor the Immich stack, Localtonet client, tunnel state, storage capacity, and backup results. Delete obsolete tunnel configurations so it remains clear which routes are authorized.

Upgrade, back up, restore, and monitor Immich

Self-hosting continues after installation. Maintain a runbook containing the installation directory, deployed Immich version, Compose-file source, local endpoint, storage locations, backup destinations, restore procedure, Localtonet client device, and tunnel owner. Keep raw secrets in a protected secrets system rather than the general runbook.

Upgrade through the same Compose deployment

Read the release notes before every upgrade, especially for major versions. Review changes to the Compose file, environment variables, database extensions, hardware requirements, and migration behavior. Back up the database and media before changing the deployment.

For an ordinary update where the current release instructions do not require file changes, pull the configured images and recreate the services:

cd ./immich-app
docker compose pull
docker compose up -d
docker compose ps

Do not blindly overwrite a customized .env or docker-compose.yml. Compare the current release files with your deployment and apply required changes deliberately. After the upgrade, inspect logs and test local login, an existing asset, a small upload, processing, and remote access in that order.

Record the previous working version and retain the pre-upgrade backup until the new version has been verified. Database migrations can make a simple image-tag downgrade unsafe. A rollback may require restoring both the version-matched database backup and the matching application configuration rather than merely starting an older container image.

Back up the database and media as separate recovery components

Immich's database contains users, albums, asset records, metadata, sharing state, and other application information. The uploaded files contain the irreplaceable photo and video content. A database backup does not contain the original media. A media-only copy does not preserve the complete application state.

Current Immich deployments provide database-backup functionality, with database backups stored under the configured upload hierarchy in a backups location. Confirm that the expected database backup files are being created and copied to an independent backup destination. Keeping a database dump inside the same upload disk is useful for organization but does not protect against failure of that disk.

Back up the complete data required by your installed release, including:

• The original uploaded and library-managed photos and videos.
• Current database backup files created through the supported Immich backup process.
• The protected .env file or an equivalent secure record of required values.
• The release-compatible docker-compose.yml and a record of the Immich version.
• Any external-library paths and the configuration needed to mount them consistently.

Generated thumbnails and transcoded media account for part of the estimated 10 to 20 percent storage overhead. Some generated data may be reproducible from originals, but regeneration can be expensive and release behavior can change. Follow the backup scope recommended for the installed Immich version rather than deleting generated directories based on assumptions.

Perform a practical restore test

A restore test should use an isolated host, virtual machine, or disposable environment with enough capacity for a representative copy. Do not test by overwriting the only production installation.

1. Record the Immich version, Compose file, and environment values associated with the backup.
2. Provision a compatible Docker host that meets the same architecture and filesystem requirements.
3. Restore the media hierarchy to the paths expected by the recovery configuration.
4. Follow the database restore procedure for that exact Immich release and database backup format.
5. Start the restored stack and inspect docker compose ps and the logs for migration or storage errors.
6. Sign in with a restored account and verify albums, sharing state, metadata, and several assets from different dates.
7. Download or open original files, not only thumbnails, to prove that the media backup is present.
8. Upload a new disposable test asset, restart the stack, and confirm that it persists.
9. Record the restore duration, missing information, manual corrections, and tested backup date.

Restoration commands can change with the bundled PostgreSQL image and Immich release. Use the version-matched Immich backup and restore procedure for the destructive database-import stage. The operational test above defines what success means and prevents a database import message from being mistaken for complete recovery.

Monitor storage and service health

Track free space for the upload location, PostgreSQL location, Docker storage, operating-system filesystem, and backup destination. Review repeated container restarts, failed background jobs, processing backlogs, permission errors, and unusual growth.

Useful routine checks include:

docker compose ps
docker compose logs --tail=200
df -h

Run them from the deployment directory where applicable. Also verify that the Localtonet client remains connected and the tunnel is running after planned host restarts if continuous remote access is intended.

Troubleshoot the deployment from the inside outward

The Immich page does not open on the host

Run docker compose ps and inspect docker compose logs --tail=200. Confirm that the containers are not repeatedly restarting. Check that port 2283 was not customized or already occupied. Verify available memory and disk space.

On amd64, an illegal-instruction failure in the machine-learning container can indicate that the physical CPU or virtual CPU does not expose x86-64-v2. A database startup failure can indicate incompatible storage, incorrect permissions, a network-mounted database path, or insufficient memory.

The page loads, but uploads or processing fail

Follow the logs while uploading a small test asset:

docker compose logs -f

Check the upload filesystem for free space and write permissions. Confirm that the configured storage is mounted where expected. If generated media fails, check processing services and CPU compatibility. Do not begin a large import until a small photo and video complete successfully.

Immich works on the host but not from the Localtonet client device

Test http://<immich-lan-address>:2283 from the client device. Do not use localhost when the client runs on another machine because that refers to the client machine itself. Confirm that the server listens on the expected interface and that local network segmentation permits the connection.

Another option is to run the Localtonet client on the Immich host if that operating environment is supported by the current Localtonet client. This avoids a separate LAN hop but does not remove the need to keep both services running.

The tunnel exists, but the public URL does not work

Confirm the selected Localtonet device is connected. Verify that the tunnel has been started because creating it is not enough. Recheck the target IP address and port from the client device. With the standard deployment and a client on the Immich host, the target is normally local port 2283. A customized deployment must use its customized value.

The login page appears, but actions fail remotely

Repeat the same action locally. If it fails locally, investigate Immich or storage. If it fails only through the public URL, inspect browser network errors and Immich logs while reproducing it. Test asset viewing, upload, progress updates, and any long-running operations separately.

Review the reverse-proxy requirements: the root application must be forwarded, the public host and scheme must remain coherent, upgraded connections must work where required, and upload limits or timeouts must not interrupt the request.

The mobile application cannot connect

Open the exact Localtonet public URL in the phone's browser with Wi-Fi disabled, subject to your mobile data policy. If the browser cannot load it, troubleshoot the tunnel first. If the browser succeeds, enter the root HTTPS URL in the mobile application without adding a guessed API path.

Confirm that the account can sign in through the web interface and that the server is not redirecting to a private hostname. Test a single non-sensitive mobile upload before enabling automatic backup for a large library.

Remote access stops after a reboot

Check each layer in order:

1. Confirm Docker is running.
2. Run docker compose ps and confirm the Immich services started.
3. Open the local Immich endpoint.
4. Open it from the Localtonet client device if that is a separate machine.
5. Confirm the Localtonet client is connected.
6. Confirm the tunnel is running.
7. Test the public URL from an external network.

Media disappears after a restart

Stop new uploads and inspect the configured UPLOAD_LOCATION. Confirm that the intended disk or mount is present before starting the stack. An application can write into an empty mount-point directory when an external disk is absent, creating the appearance of two libraries after the disk returns.

Do not move or delete either copy until you understand which path was active and have a verified backup. Also confirm that PostgreSQL is using the expected DB_DATA_LOCATION.

Frequently asked questions