Expose Immich with Docker

Immich's official docker-compose.yml runs the API as immich-server on port 2283 on the compose project's default network. Add the Kepeink agent to the same compose project (same file or a docker-compose.override.yml next to it) and point the tunnel at http://immich-server:2283.

1. Create the tunnel

Create a proxy tunnel targeting http://immich-server:2283 (or create it headlessly via the API — see quickstart on manage):

curl -fsS -X POST https://manage.kepeink.hu/api/v1/tunnels \
  -H "Authorization: Bearer $KEPEINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"http://immich-server:2283","backend_mode":"proxy"}'
# → { tunnel_id, sni, public_url, agent_token: "kpt_…" }  ← save kpt_… now, shown once

The target http://immich-server:2283 resolves inside the Docker network — the agent container reaches Immich by service DNS name, not localhost.

Need a service on the host instead? Use http://host.docker.internal:<port> and add extra_hosts: ["host.docker.internal:host-gateway"] to the agent service. Never use http://localhost:<port> inside the agent container for a different container — that is the agent itself.

2. Wire the agent into the same compose file

docker-compose.yml (or docker-compose.override.yml):

services:
  kepeink-agent:
    image: registry.kepeink.hu/agent:2
    restart: unless-stopped
    environment:
      KEPEINK_AGENT_TOKEN: ${KEPEINK_AGENT_TOKEN}

.env next to the compose file (same file that holds DB_PASSWORD/UPLOAD_LOCATION):

KEPEINK_AGENT_TOKEN=kpt_xxxxxxxx

Being in the same compose file puts the agent on the same network automatically — no networks: block needed. If your Immich runs in a *different* compose project, attach explicitly:

services:
  kepeink-agent:
    image: registry.kepeink.hu/agent:2
    restart: unless-stopped
    environment:
      KEPEINK_AGENT_TOKEN: ${KEPEINK_AGENT_TOKEN}
    networks:
      - immich_default
networks:
  immich_default:
    external: true

3. Bring it up and verify

docker compose up -d kepeink-agent
docker compose logs -f kepeink-agent   # expect: session up
curl -fsS https://<your-sni>/api/server/ping  # → { res: "pong" } when the tunnel is live

Open https://<your-sni>/ (from the tunnel response or the dashboard) — Immich is now reachable from the internet with no port forwarding. On your LAN you can keep using http://<host>:2283 directly to avoid spending traffic credit.

4. Optional hardening before you share it

• Create the Immich admin first. Before the first public request, open http://<host>:2283 on the LAN and create the admin account — whoever loads the page first claims isAdmin.
• Add a custom domain (Add a custom domain) so shares live at photos.example.com instead of the *.rproxy.*.xyz hostname.
• Turn on end-to-end TLS so the Let's Encrypt private key is generated and held on the Pi/box itself — Kepeink only relays ciphertext.
• Count credit. Every upload/view from off-LAN counts against prepaid bytes (dashboard → billing). LAN access does not.