Skip to content

Upgrading to 1.5

Jump to bottom
marcpope edited this page Aug 10, 2026 · 1 revision

Upgrading to 1.5

1.5 puts the ID server and the relay inside the CortenDesk image. One container now runs the console, hbbs and hbbr. Your separate hbbs/hbbr containers go away, and the wiring between them — the public key, the ID and relay addresses, the WebSocket bridge — becomes automatic.

You do not have to consolidate. Keeping your own servers is one environment variable and takes two minutes. Read that section and stop there if that is what you want.

Nothing about your data changes. Devices, users, address books, logs, settings, the server key pair and the peer database all carry over exactly. No client needs reconfiguring — same key, same ports, same addresses.

Before you start

  1. Read the release notes.
  2. Know where your hbbs data directory is — the one holding id_ed25519, id_ed25519.pub and db_v2.sqlite3. In the compose from RustDesk server in Docker it is ./data, mounted at /root. If you are not sure: 
    docker inspect hbbs --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}'
  3. Back it up. It is a few small files and it is the thing you cannot regenerate: 
    sudo cp -a /path/to/rustdesk/data /path/to/rustdesk/data.backup-$(date +%F)
    Losing id_ed25519 locks every existing client out of connecting — there is no migration and no way to accept both an old and a new key.

Take a database backup as well if you normally would; 1.5 runs migrations on first start like any other release.

Consolidating (the recommended path)

Say you are running something like this today — the console in one compose project, hbbs/hbbr in another:

# ~/rustdesk/docker-compose.yml   (going away)
services:
  hbbs:
    image: rustdesk/rustdesk-server:latest
    command: hbbs -r rd.example.com:21117
    ports: ["21115:21115", "21116:21116", "21116:21116/udp", "21118:21118"]
    volumes: ["./data:/root"]
  hbbr:
    image: rustdesk/rustdesk-server:latest
    command: hbbr -k _
    ports: ["21117:21117", "21119:21119"]
    volumes: ["./data:/root"]

1. Stop the old servers

They hold the ports the console is about to want.

cd ~/rustdesk
docker compose down

Devices go offline here and stay offline until step 3. Nothing is lost — they re-register within a heartbeat once the new container is up.

2. Point the console at the same data directory

In your CortenDesk compose, add the hbbs ports, mount the old data directory at /data/rustdesk, and drop the three settings the image now works out for itself:

services:
  cortendesk:
    image: ghcr.io/marcpope/cortendesk:1.5.0
    environment:
      APP_URL: https://rd.example.com     # must be the address CLIENTS reach
      # CORTENDESK_ID_SERVER      — derived from APP_URL, remove it
      # CORTENDESK_RELAY_SERVER   — derived from APP_URL, remove it
      # CORTENDESK_PUBLIC_KEY     — read from the key pair, remove it
      DB_CONNECTION: mysql
      # ...the rest of your existing settings, unchanged...
    ports:
      - "8080:8080"
      - "21115:21115"
      - "21116:21116"
      - "21116:21116/udp"
      - "21117:21117"
    volumes:
      - cortendesk-data:/data
      - /home/you/rustdesk/data:/data/rustdesk    # <- the old hbbs data

Use the absolute path to the directory you identified above. Leaving the three settings in place is harmless — an explicit value always wins — but removing them is the point of the exercise.

APP_URL now does the work of all three: the ID server becomes <APP_URL host>:21116, the relay <APP_URL host>:21117, and the public key is read out of the mounted key pair. If your console is reached at a different address than your clients use for signalling, keep CORTENDESK_ID_SERVER and CORTENDESK_RELAY_SERVER set explicitly.

3. Start it

docker compose up -d
docker compose logs -f cortendesk

You are looking for four lines:

[cortendesk] ready — console on :8080, ID server on :21116, relay on :21117
[cortendesk] server 1.0.0, key GG2jFmQYGsG...=
INFO [src/common.rs:121] Private key comes from id_ed25519
INFO [src/rendezvous_server.rs] Key: GG2jFmQYGsG...=

Private key comes from id_ed25519 is the one that matters. It means your existing key was adopted. If you instead see generated the server key pair, the old data directory is not mounted where the container expects it — stop, fix the volume line, and start again before any client tries to connect.

The Key: line must equal what your clients have in their Key field and what cat /path/to/rustdesk/data/id_ed25519.pub prints. All three are the same string or nothing connects.

4. Check it

  • Devices come back online in the console within a minute.
  • Connect to one from a signed-in client. This is the case that was broken against the open-source server; see Troubleshooting.
  • The in-browser web client opens a session.

5. Tidy up

Once you are happy, delete the old compose project. Keep the data directory backup for a while — it is your rollback.

Simplifications you can now make

The WebSocket bridge is internal. /ws/id and /ws/relay are proxied to hbbs and hbbr over loopback inside the container, so a reverse proxy in front only has to forward port 8080. If you built an nginx stream block or published 21118/21119 to make the web client work, you can remove it.

Ports 21118 and 21119 no longer need publishing unless something outside the container talks to them directly.

RUSTDESK_WS_HOST is no longer needed and should be removed.

Keeping your own hbbs/hbbr

Set one variable and nothing else changes:

environment:
  CORTENDESK_EMBEDDED_SERVER: "false"
  CORTENDESK_ID_SERVER: hbbs.example.com:21116
  CORTENDESK_RELAY_SERVER: hbbs.example.com:21117
  CORTENDESK_PUBLIC_KEY: "<contents of id_ed25519.pub>"

The bundled hbbs and hbbr never start, the console behaves exactly as it did in 1.1.x, and you do not need to publish any of the 2111x ports on the console container.

Worth knowing what you give up: the open-source hbbs cannot complete the signalling key exchange that clients 1.4.1 and newer start when signed in, so connections from signed-in clients fail with Failed to secure tcp. If that is what you are running, either consolidate or switch those containers to CortenDesk Server, which is the same hbbs and hbbr this image bundles.

Rolling back

1.5 adds migrations but does not remove or rewrite anything 1.1.x reads, so the data is compatible in both directions. To go back:

# console
docker compose down
# put your 1.1.x image tag and the three env settings back, then
docker compose up -d

# servers
cd ~/rustdesk && docker compose up -d

Point the old hbbs/hbbr at the same data directory and they pick the key pair straight back up. Nothing in that directory is written in a format the older servers cannot read.

Upgrading from very old versions

Coming from 0.9.x or earlier, upgrade to the latest 1.1.x first, confirm the console is healthy, and then do this page. Each release migrates from the one before it, and stepping through avoids debugging two changes at once.

If something goes wrong

Devices never come back online. UDP 21116 is not published or not open. Check the ports: list has "21116:21116/udp" as well as the TCP line, then the host firewall and the cloud security group.

Devices online, connections fail immediately. Key mismatch — the container generated a new key instead of adopting yours. Confirm the log says Private key comes from id_ed25519, and compare the Key: line against id_ed25519.pub.

Sessions hang at "connecting". The relay address handed to clients is not reachable by them. It comes from APP_URL now: an internal hostname or localhost there produces exactly this. The container warns about it at startup.

Ports already in use. The old hbbs/hbbr containers are still running. docker ps and stop them.

More in Troubleshooting.

Clone this wiki locally