mike/rustdesk-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Change docker-compose.yml to build server from source and update documentation
build / build-linux-amd64 (push) Successful in 1m48s
Details

Browse Source
This commit is contained in:
Mike Müller
2026-05-06 20:28:39 +02:00
parent 8e5c0969ef
commit bc260b7d8f
4 changed files with 314 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+37
View File
@@ -0,0 +1,37 @@
# Copy to .env and edit. docker-compose reads it automatically.
# --- Required ----------------------------------------------------------------
# Public domain clients connect to. hbbs advertises this as the relay address.
RUSTDESK_DOMAIN=rd.gamecom.ch
# --- Bootstrap admin ---------------------------------------------------------
# Seeded into the users table on the FIRST startup only (when users is empty).
# Subsequent restarts ignore these — change the password via the admin UI.
# Without these set on first boot, you'll have no way to log in.
RUSTDESK_BOOTSTRAP_ADMIN_USERNAME=admin
RUSTDESK_BOOTSTRAP_ADMIN_PASSWORD=changeme
# --- Optional runtime --------------------------------------------------------
# Pre-shared key. "-" lets hbbs auto-generate on first run; "_" forces
# encrypted-only mode without an explicit key.
#RUSTDESK_KEY=-
# HTTP management API / admin UI port (pro-features). Set to 0 to disable.
#RUSTDESK_HTTP_PORT=21114
# Force relay for all sessions even on LAN.
#RUSTDESK_ALWAYS_USE_RELAY=Y
#RUST_LOG=info
# --- Optional build source ---------------------------------------------------
# Override the upstream repo / branch the image is built from.
#RUSTDESK_GIT_URL=https://gitea.cstudio.ch/mike/rustdesk-server.git
#RUSTDESK_GIT_BRANCH=pro-features
# --- Database connectivity ---------------------------------------------------
DATABASE_URL=sqlite://./db_v2.sqlite3
docker-compose.yml
+39 -11
View File
@@ -1,4 +1,15 @@
version: '3'
# RustDesk server (built from source on gitea.cstudio.ch)
#
# Configuration is driven by a sibling .env file — see .env.example.
# Override the build source with RUSTDESK_GIT_URL / RUSTDESK_GIT_BRANCH.
x-rustdesk-build: &rustdesk-build
context: .
dockerfile: docker/Dockerfile.source
args:
RUSTDESK_GIT_URL: ${RUSTDESK_GIT_URL:-https://gitea.cstudio.ch/mike/rustdesk-server.git}
RUSTDESK_GIT_BRANCH: ${RUSTDESK_GIT_BRANCH:-pro-features}
DATABASE_URL: ${DATABASE_URL:-}
networks:
rustdesk-net:
@@ -7,13 +18,25 @@ networks:
services:
hbbs:
container_name: hbbs
build: *rustdesk-build
image: rustdesk-server-pro:local
command: >
hbbs
-r ${RUSTDESK_DOMAIN:?set RUSTDESK_DOMAIN in .env, e.g. rd.gamecom.ch}:21117
-k ${RUSTDESK_KEY:--}
--http-port ${RUSTDESK_HTTP_PORT:-21114}
--admin-ui-dir /opt/rustdesk/admin_ui
--bootstrap-admin-username=${RUSTDESK_BOOTSTRAP_ADMIN_USERNAME:-}
--bootstrap-admin-password=${RUSTDESK_BOOTSTRAP_ADMIN_PASSWORD:-}
environment:
ALWAYS_USE_RELAY: ${RUSTDESK_ALWAYS_USE_RELAY:-N}
RUST_LOG: ${RUST_LOG:-info}
ports:
- 21115:21115
- 21116:21116
- 21116:21116/udp
- 21118:21118
image: rustdesk/rustdesk-server:latest
command: hbbs -r rustdesk.example.com:21117
- "${RUSTDESK_HTTP_PORT:-21114}:21114"
- "21115:21115"
- "21116:21116"
- "21116:21116/udp"
- "21118:21118"
volumes:
- ./data:/root
networks:
@@ -24,11 +47,16 @@ services:
hbbr:
container_name: hbbr
build: *rustdesk-build
image: rustdesk-server-pro:local
command: >
hbbr
-k ${RUSTDESK_KEY:--}
environment:
RUST_LOG: ${RUST_LOG:-info}
ports:
- 21117:21117
- 21119:21119
image: rustdesk/rustdesk-server:latest
command: hbbr
- "21117:21117"
- "21119:21119"
volumes:
- ./data:/root
networks:
docker/Dockerfile.source
+48
View File
@@ -0,0 +1,48 @@
# Multi-stage build: clones rustdesk-server from a Git remote and builds the
# hbbs / hbbr / rustdesk-utils binaries from source.
#
# Build args:
# RUSTDESK_GIT_URL Git URL to clone (default: gitea.cstudio.ch fork)
# RUSTDESK_GIT_BRANCH Branch / tag / ref to check out (default: pro-features)
# RUST_VERSION Rust toolchain image tag (default: 1-bookworm)
ARG RUST_VERSION=1-bookworm
FROM rust:${RUST_VERSION} AS builder
ARG RUSTDESK_GIT_URL=https://gitea.cstudio.ch/mike/rustdesk-server.git
ARG RUSTDESK_GIT_BRANCH=pro-features
# sqlx::query! macros verify SQL at compile time against the checked-in
# db_v2.sqlite3. Override only if you point cargo at a different DB.
ARG DATABASE_URL=
RUN apt-get update \
&& apt-get install -y --no-install-recommends git ca-certificates pkg-config cmake \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /src
RUN git clone --recurse-submodules --shallow-submodules \
--branch "${RUSTDESK_GIT_BRANCH}" --single-branch \
"${RUSTDESK_GIT_URL}" .
RUN if [ -n "${DATABASE_URL}" ]; then export DATABASE_URL="${DATABASE_URL}"; fi \
&& cargo build --release --bins
# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates tini \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /src/target/release/hbbs /usr/local/bin/hbbs
COPY --from=builder /src/target/release/hbbr /usr/local/bin/hbbr
COPY --from=builder /src/target/release/rustdesk-utils /usr/local/bin/rustdesk-utils
COPY --from=builder /src/admin_ui /opt/rustdesk/admin_ui
WORKDIR /root
EXPOSE 21114 21115 21116 21116/udp 21117 21118 21119
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["hbbs"]
docs/DOCKER.md
+190
View File
@@ -0,0 +1,190 @@
# RustDesk Server — Docker Compose Deployment
The repo ships a `docker-compose.yml` that **builds the server from source**
(this fork's `pro-features` branch) and runs `hbbs` + `hbbr` as two
containers. No prebuilt image is pulled — every `docker compose build`
clones the configured Git URL and runs `cargo build --release` inside the
build stage.
For the runtime flag reference (CLI options accepted by `hbbs` itself), see
[CONFIGURATION.md](CONFIGURATION.md). This document only covers the Compose
glue.
---
## Quick start
```bash
cp .env.example .env
# edit .env — at minimum set RUSTDESK_DOMAIN, and change
# RUSTDESK_BOOTSTRAP_ADMIN_PASSWORD before the first boot
docker compose up -d --build
```
The bootstrap admin (default `admin` / `changeme`) is seeded into the
`users` table on the **first** boot only — once the row exists, those
flags are ignored. If you boot with the default password and forget to
change it, rotate it via the admin UI; if you forget the password
entirely, delete `./data/db_v2.sqlite3` (loses all server-side state) or
edit the `users` row with `sqlite3` directly.
First build pulls the Rust toolchain image and compiles the workspace; expect
several minutes. Subsequent builds reuse the cargo cache layer unless the
Git ref or build args change.
After it boots:
| Endpoint | Port | Purpose |
|------------------------------------------|---------|------------------------------------------|
| `tcp://<domain>:21115` | 21115 | NAT test |
| `tcp+udp://<domain>:21116` | 21116 | ID / rendezvous (desktop clients) |
| `tcp://<domain>:21117` | 21117 | Relay (hbbr) |
| `ws://<domain>:21118` | 21118 | Browser-facing rendezvous WebSocket |
| `ws://<domain>:21119` | 21119 | Browser-facing relay WebSocket |
| `http://<domain>:21114/admin/` | 21114 | Admin dashboard (pro-features) |
| `http://<domain>:21114/api/*` | 21114 | Management API (pro-features) |
Persistent state — including the auto-generated `id_ed25519` keypair and the
SQLite database — lives in `./data/` (bind-mounted to `/root` in both
containers).
---
## Files
| File | Role |
|-----------------------------|---------------------------------------------------------------------------------------|
| `docker-compose.yml` | Two services (`hbbs`, `hbbr`) sharing one image built from `docker/Dockerfile.source`.|
| `docker/Dockerfile.source` | Multi-stage build: clones the repo, runs `cargo build --release`, copies binaries into a `debian:bookworm-slim` runtime. |
| `.env.example` | Documented template; copy to `.env`. |
| `data/` | Created on first run. Contains keypair + SQLite DB. **Back this up.** |
The legacy single-stage `docker/Dockerfile` (busybox + s6-overlay, expects
prebuilt binaries) and `docker-classic/Dockerfile` are unrelated to this
flow and unused by `docker-compose.yml`.
---
## Environment variables
These are read by `docker-compose.yml` from `.env`. Compose ships them
through to the container as command-line flags or `environment:` entries,
not as raw process env (with the exception of `RUST_LOG` and
`ALWAYS_USE_RELAY`, which `hbbs` reads from env directly).
### Runtime
| Variable | Default | Effect |
|--------------------------------|-----------------|-------------------------------------------------------------------------------------------------------|
| `RUSTDESK_DOMAIN` | **required** | Public hostname clients connect to. Passed as `hbbs -r ${RUSTDESK_DOMAIN}:21117`. |
| `RUSTDESK_BOOTSTRAP_ADMIN_USERNAME` | `admin` | Seeded as the initial admin on **first boot only** (when the `users` table is empty). Ignored on subsequent restarts. Empty disables the bootstrap. |
| `RUSTDESK_BOOTSTRAP_ADMIN_PASSWORD` | `changeme` | Same — bcrypt-hashed at insert. Change this in `.env` before the first `up`, or rotate via the admin UI immediately after. |
| `RUSTDESK_KEY` | `-` | Pre-shared key. `-` = auto-generate on first boot (written to `./data/id_ed25519{,.pub}`); `_` = encrypted-only with auto-key; or paste a base64 public key to pin it. Applied to **both** `hbbs` and `hbbr` via `-k`. |
| `RUSTDESK_HTTP_PORT` | `21114` | Pro-features admin API + dashboard port. Set to `0` to disable HTTP entirely. The host port published is the same value. |
| `RUSTDESK_ALWAYS_USE_RELAY` | `N` | Force every session through the relay even on LAN. Read from env by hbbs (any non-empty/non-`N` value enables). |
| `RUST_LOG` | `info` | Log filter. e.g. `debug`, `hbbs=debug,sqlx=warn`. |
### Build source
| Variable | Default | Effect |
|------------------------|---------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| `RUSTDESK_GIT_URL` | `https://gitea.cstudio.ch/mike/rustdesk-server.git` | Repo cloned inside the builder stage. |
| `RUSTDESK_GIT_BRANCH` | `pro-features` | Branch / tag / commit to check out (`--branch` so it must be a ref name, not a SHA). |
| `DATABASE_URL` | unset (uses the cloned repo's `.env`) | Overrides the `DATABASE_URL` sqlx reads at compile time. Rarely needed — see below. |
Build-arg changes only take effect when the image is rebuilt:
`docker compose build --no-cache hbbs` (or `up -d --build`).
---
## Why `DATABASE_URL` is a build-time concern
`hbbs` uses `sqlx::query!` macros, which verify SQL **at compile time** by
running the queries against a real SQLite database. The repo includes a
checked-in `db_v2.sqlite3` with the schema pre-applied, and a tracked `.env`
file pointing at it (`DATABASE_URL=sqlite://./db_v2.sqlite3`).
Cargo automatically reads `.env` from the project root, so `cargo build`
inside the builder stage Just Works without any explicit configuration.
You only need to set `DATABASE_URL` in the Compose `.env` if you fork the
schema or want to point the compile-time check at a different SQLite file.
At **runtime** the binary opens its own DB under `/root/` (your `./data/`
bind mount) — that path is not configurable via this variable.
---
## Adding extra `hbbs` flags
`docker-compose.yml` only wires the most common flags. To pass others
(SMTP, OIDC, recording dir, audit retention, …), edit the `command:`
block of the `hbbs` service. Example — enable SMTP and set the public
base URL needed for OIDC callbacks:
```yaml
command: >
hbbs
-r ${RUSTDESK_DOMAIN:?...}:21117
-k ${RUSTDESK_KEY:--}
--http-port ${RUSTDESK_HTTP_PORT:-21114}
--admin-ui-dir /opt/rustdesk/admin_ui
--bootstrap-admin-username=${RUSTDESK_BOOTSTRAP_ADMIN_USERNAME:-}
--bootstrap-admin-password=${RUSTDESK_BOOTSTRAP_ADMIN_PASSWORD:-}
--public-base-url https://${RUSTDESK_DOMAIN}:${RUSTDESK_HTTP_PORT:-21114}
--smtp-host ${SMTP_HOST}
--smtp-user ${SMTP_USER}
--smtp-pass ${SMTP_PASS}
--smtp-from ${SMTP_FROM}
```
Then add the matching variables to `.env`. The full flag list lives in
[CONFIGURATION.md](CONFIGURATION.md).
If you mount an `oidc.toml`, drop it into `./data/` and pass
`--oidc-config /root/oidc.toml`.
---
## Operational notes
**Upgrading.** Pull the latest commit on `pro-features` and rebuild:
```bash
docker compose build --pull --no-cache
docker compose up -d
```
The `--pull` refreshes the Rust toolchain base image; `--no-cache` forces a
fresh `git clone` (otherwise Docker will reuse the cached clone layer).
Alternatively, bump `RUSTDESK_GIT_BRANCH` to a tag and rebuild — the changed
build arg invalidates the clone layer automatically.
**Logs.** `docker compose logs -f hbbs` (or `hbbr`). Both containers run
the binary in the foreground.
**Persistence.** Everything that matters is in `./data/`:
`id_ed25519{,.pub}` (the server keypair — losing this invalidates every
existing client) and `db_v2.sqlite3` (users, address books, audit, etc.).
Back up the whole directory.
**TLS.** The server itself speaks plain HTTP on 21114 and plain WebSocket
on 21118 / 21119. Front it with nginx or Caddy for TLS — see the "TLS
deployment" section in `CONFIGURATION.md`. When you do, set
`--http-listen=127.0.0.1` and `--ws-listen=127.0.0.1` in the `command:`
block so the reverse proxy can claim the public ports.
**Building behind a proxy.** Pass `HTTP_PROXY` / `HTTPS_PROXY` build args
through Compose:
```yaml
build:
<<: *rustdesk-build
args:
HTTP_PROXY: http://proxy.internal:3128
HTTPS_PROXY: http://proxy.internal:3128
```
**Resource hint.** Cold compile takes ~3–5 GB of RAM for the linker step
(LTO + `codegen-units = 1`). On a small VPS, build the image on a beefier
machine, push to a registry, and pull from the VPS instead — set the
`image:` field to a registry tag and drop the `build:` block.