Upgrading from v1 to v2

This guide helps migrate from TSDProxy v1 to v2.

Tip

If you are on v2 and want to upgrade to v3 with the recommended Services mode, see Upgrading from v2 to v3.

Before You Upgrade

Back up /config/ directory
Read the changelog
Plan for downtime — proxies will restart

Step 1: Update Image

services:
  tsdproxy:
    image: almeidapaulopt/tsdproxy:2

Add extra_hosts if missing:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Step 2: Migrate Config

Rename files: to lists: in tsdproxy.yaml.

Update list files from v1 format to v2 multi-port format:

# v1
nas1:
  url: https://192.168.1.2:5001

# v2
nas1:
  ports:
    443/https:
      targets:
        - https://192.168.1.2:5001

Step 3: Migrate Docker Labels

V1	V2
`tsdproxy.container_port: 8080`	`tsdproxy.port.1: "443/https:8080/http"`
`tsdproxy.scheme: https`	`tsdproxy.port.1: "443/https:443/https"`
`tsdproxy.tlsvalidate: false`	`tsdproxy.port.1: "443/https:80/http, no_tlsvalidate"`
`tsdproxy.funnel: true`	`tsdproxy.port.1: "443/https:80/http, tailscale_funnel"`

Step 4: Restart & Verify

docker compose pull && docker compose up -d

Check Dashboard at http://<IP>:8080.

Post-Upgrade: v2.2.0 Breaking Changes

If you are upgrading to v2.2.0 or later, review these breaking changes:

Dashboard bind address

The default http.hostname changed from 0.0.0.0 to 127.0.0.1. If you expose the dashboard externally (Docker port mapping, reverse proxy), add to your config:

http:
  hostname: 0.0.0.0

See Server Configuration for details.

Dashboard authentication

All dashboard and API endpoints now require authentication. If you access the dashboard via Docker port mapping (not through a Tailscale proxy), enable localhost access:

adminAllowLocalhost: true

Then configure an admins list or apiKey and disable localhost access. See Admin Allowlist for full instructions.

See the changelog for the complete list of changes.

Rolling Back

docker compose down
# Restore config backup
# Change image tag back to almeidapaulopt/tsdproxy:1
docker compose up -d

Last updated on June 1, 2026

Upgrading Upgrading from v2 to v3