How to Configure SSH Credentials for Immich Docker or VM Setup

Immich is one of the most enjoyable self-hosted photo and video backup platforms because it feels polished while still giving you control over your storage. Whether you run it in Docker on a home server or inside a virtual machine, SSH access is often the quiet foundation that makes everything easier: maintenance, updates, backups, file transfers, troubleshooting, and automation.

TLDR: Configure SSH using key-based authentication, not passwords, and store your private key securely on your client machine. Add the public key to the Immich server user’s ~/.ssh/authorized_keys file, then test login before disabling password authentication. For Docker, SSH usually connects to the host running Immich; for a VM, it connects directly to the virtual machine. Keep permissions strict, use a dedicated user, and avoid exposing SSH carelessly to the internet.

Why SSH Matters in an Immich Setup

Immich itself does not require SSH to function. The web interface, mobile apps, database, machine learning container, and storage volumes can all work without you ever typing ssh. However, SSH becomes essential the moment you want to manage the server like a real self-hosted system.

With SSH credentials configured properly, you can:

• Deploy or update Immich using Docker Compose commands.
• Copy configuration files between your workstation and server.
• Create automated backups of upload folders, database dumps, and environment files.
• Inspect logs when something breaks after an update.
• Securely transfer files using scp, sftp, or rsync.
• Run maintenance scripts without needing physical access to the machine.

Think of SSH as the maintenance doorway into your Immich house. The goal is to make that doorway strong, convenient, and difficult for strangers to force open.

Image not found in postmeta

Docker Host vs VM: Where Does SSH Go?

Before creating credentials, identify what you are actually connecting to. In a typical Docker setup, Immich runs as containers on a host machine. You do not normally SSH into the Immich container itself. Instead, you SSH into the host, then run commands such as:

cd /opt/immich
docker compose ps
docker compose logs -f
docker compose pull
docker compose up -d

In a VM setup, the virtual machine behaves like a normal Linux server. You SSH into the VM’s IP address, and from there you manage Immich, Docker, storage mounts, backups, and firewall rules.

The distinction matters because credentials belong to the operating system account you will log into. For Docker, that account is on the Docker host. For a VM, that account is inside the VM.

Step 1: Choose or Create a Dedicated User

It is tempting to SSH as root, especially on a small home server. Resist that temptation. A dedicated user is safer and cleaner. You might create a user named immichadmin, deploy, or simply use your existing admin account.

On the server, create a user with:

sudo adduser immichadmin

Then add the user to the groups needed to manage Docker:

sudo usermod -aG docker immichadmin

If the user needs administrative privileges, add it to the sudo group:

sudo usermod -aG sudo immichadmin

After changing group membership, log out and back in. Group changes often do not apply to an existing session.

Security note: Membership in the docker group is powerful. A user who can control Docker can often gain root-level access indirectly. Only grant this to users you trust.

Step 2: Generate an SSH Key Pair

SSH keys come in pairs: a private key that stays on your computer, and a public key that goes on the server. The private key is your identity. Never place it on random servers, never paste it into chat, and never store it in your Immich upload folder.

On your client machine, generate a modern key:

ssh-keygen -t ed25519 -C "immich server access"

When prompted, choose a file location. The default is usually fine:

~/.ssh/id_ed25519

You should also set a passphrase. A passphrase protects the private key if your laptop or desktop is compromised. It is a small inconvenience that adds a meaningful layer of security.

If you manage multiple servers, use a descriptive key name:

ssh-keygen -t ed25519 -f ~/.ssh/immich_server_ed25519 -C "immich admin key"

Step 3: Install the Public Key on the Server

If password SSH is temporarily enabled, the easiest method is ssh-copy-id:

ssh-copy-id -i ~/.ssh/immich_server_ed25519.pub immichadmin@SERVER_IP

Replace SERVER_IP with the IP address of your Docker host or VM. For example:

ssh-copy-id -i ~/.ssh/immich_server_ed25519.pub immichadmin@192.168.1.50

If ssh-copy-id is unavailable, copy the public key manually. On your client, display it:

cat ~/.ssh/immich_server_ed25519.pub

On the server, create the SSH directory and authorized key file:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Paste the public key into authorized_keys, save the file, and exit.

Step 4: Test SSH Login

Before changing security settings, test your key-based login:

ssh -i ~/.ssh/immich_server_ed25519 immichadmin@192.168.1.50

If everything is correct, you should log in without entering the server account password. If you set a passphrase on the key, you may be asked for that instead.

Once connected, confirm Docker access if you are using Immich with Docker:

docker ps

If you receive a permissions error, check whether the user is in the docker group:

groups

You may need to log out and back in, or reboot the VM or host.

Step 5: Create a Convenient SSH Config Entry

Typing a full SSH command every time gets old quickly. Your local SSH config file lets you create a friendly shortcut.

Edit or create:

nano ~/.ssh/config

Add:

Host immich
    HostName 192.168.1.50
    User immichadmin
    IdentityFile ~/.ssh/immich_server_ed25519
    IdentitiesOnly yes

Now you can connect with:

ssh immich

This also makes file transfers cleaner:

scp docker-compose.yml immich:/opt/immich/
rsync -av ./backup-script.sh immich:/home/immichadmin/scripts/

If your server changes IP addresses often, assign it a static DHCP lease in your router or use a local DNS name such as immich.local.

Step 6: Secure the SSH Server

After confirming key login works, harden your SSH server. Open the SSH daemon configuration:

sudo nano /etc/ssh/sshd_config

Recommended settings include:

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

Then restart SSH:

sudo systemctl restart ssh

Important: Keep your current SSH session open while testing a second login in a new terminal. If you made a mistake, the existing session can save you from being locked out.

You may also consider changing the SSH port, but do not treat that as real security. It reduces noise from automated scans, but strong keys, disabled passwords, firewall rules, and updates matter more.

Using SSH with Immich Docker Compose

Most Immich Docker installations live in a directory such as /opt/immich or /home/user/immich. After SSH login, common management commands include:

cd /opt/immich
docker compose ps
docker compose logs -f immich-server
docker compose pull
docker compose up -d

SSH credentials also make backups much smoother. For example, you can use rsync to pull a copy of your Immich library to another machine:

rsync -av --progress immich:/path/to/immich/library/ ./immich-library-backup/

For database backups, you will typically run a PostgreSQL dump from the server, then copy the resulting file elsewhere. Your exact command depends on your Immich Compose file and database container name, but the workflow is the same: SSH in, create the backup, transfer it securely.

Using SSH with a VM-Based Immich Installation

In a VM setup, SSH configuration is nearly identical, but networking deserves extra attention. Make sure the VM has an IP address reachable from your client machine. In your hypervisor, this usually means choosing bridged networking or setting up a proper port forward from the host to the guest.

If you use NAT networking, you may need a rule like:

• Host port 2222
• Guest IP 10.0.2.15
• Guest port 22

Then connect with:

ssh -p 2222 immichadmin@HOST_IP

For long-term use, put the port in your SSH config:

Host immich-vm
    HostName 192.168.1.20
    Port 2222
    User immichadmin
    IdentityFile ~/.ssh/immich_server_ed25519

Common Problems and Fixes

• Permission denied publickey: Check that the public key is in the correct user’s authorized_keys file.
• Key ignored by server: Fix permissions with chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys.
• Wrong private key used: Specify the key with -i or define it in ~/.ssh/config.
• Docker permission denied: Add the SSH user to the docker group, then start a new session.
• Cannot reach VM: Check VM network mode, firewall rules, and whether the SSH service is running.

Final Security Best Practices

A good Immich setup protects not only the application, but also the memories stored inside it. SSH is part of that protection. Use unique keys for important servers, keep private keys backed up in a secure password manager or encrypted storage, and remove old keys when devices are retired.

If SSH must be reachable over the internet, use extra caution. Prefer a VPN such as WireGuard or Tailscale instead of exposing port 22 directly. If you do expose SSH, use a firewall, disable passwords, consider tools like fail2ban, and keep the server updated.

Configured well, SSH becomes boring in the best possible way: reliable, secure, and always there when you need it. For Immich, that means easier updates, safer backups, faster troubleshooting, and more confidence that your self-hosted photo library is under your control.