Installation

BetterDesk supports Linux (bare-metal), Windows (PowerShell), and Docker as primary install paths. FreeBSD is Tier 3 / community (manual build + example rc.d; no betterdesk.sh). Default Linux paths are /opt/betterdesk (Go server) and /opt/BetterDeskConsole (web panel); the installer still detects legacy /opt/rustdesk installs.

Requirements

Linux

Ubuntu 20.04+ / Debian 11+ / CentOS 8+ / AlmaLinux 8+
1 CPU core, 512 MB RAM minimum (2 cores, 2 GB recommended)
Root access (sudo)
Firewall: follow a profile from CONNECTION_PORTS.md (profile B is the recommended one). Do not expose the panel (5000) to the internet. Quick minimum for clients: 21116 TCP+UDP and 21117 TCP WAN, Client API on 443 or 21114 over TLS.
Node.js 22+ (auto-installed by script; installer targets Node.js 22 LTS while the Node.js 24 native cleanup-hook regression is resolved)
Existing bare-metal installations running Node.js 24.19.x should switch the console runtime to Node.js 22.x before restarting the service; the installer does not force-downgrade an existing Node installation.

Windows

Windows 10/11 or Windows Server 2019+
PowerShell 5.1+ (run as Administrator)
NSSM (auto-installed by script)
Firewall: same profiles as Linux — see CONNECTION_PORTS.md. The panel port stays local.

Docker

Docker Engine 20.10+ with Docker Compose v2
512 MB RAM minimum

FreeBSD (experimental / community)

FreeBSD 13+ (amd64); root or doas/sudo
pkg packages: git, go, node, npm, python3, ca_root_nss
Open ports (e.g. via pf): follow a profile from CONNECTION_PORTS.md; at minimum 21116 TCP+UDP and 21117 TCP.
No official installer or release binaries — see FreeBSD (experimental) below and contrib/freebsd/

Linux Installation

Interactive Mode

git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
sudo ./betterdesk.sh

The interactive menu offers:

Option	Description
1	New installation (full setup from scratch)
2	Update existing installation
3	Repair (auto-fix common issues)
4	Validate installation correctness
5	Create backup
6	Reset admin password
7	Build binaries from source
8	Run diagnostics
9	Uninstall
C	Configure SSL/TLS certificates
M	Migrate databases (SQLite ↔ PostgreSQL)

Automatic Mode

sudo ./betterdesk.sh --auto

Non-interactive install with default settings. Useful for CI/CD or scripted deployments.

Options

# Skip SHA256 binary verification
sudo ./betterdesk.sh --skip-verify

# Custom API port (default 21121 compatibility proxy, Go API on 21114)
API_PORT=21130 sudo ./betterdesk.sh --auto

# Custom relay servers (overrides auto-detected IP)
RELAY_SERVERS=YOUR.PUBLIC.IP sudo ./betterdesk.sh --auto

Installation Path

After installation, files are located at:

Path	Description
`/opt/betterdesk/`	Go server binary, keys, database
`/opt/BetterDeskConsole/`	Node.js web console
`/etc/systemd/system/betterdesk-server.service`	Go server systemd service
`/etc/systemd/system/betterdesk-console.service`	Node.js systemd service

Verify Installation

sudo systemctl status betterdesk-server
sudo systemctl status betterdesk-console

# Check logs
journalctl -u betterdesk-server -f
journalctl -u betterdesk-console -f

Windows Installation

Interactive Mode

Open PowerShell as Administrator:

git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
.\betterdesk.ps1

Automatic Mode

.\betterdesk.ps1 -Auto

Options

# Skip SHA256 verification
.\betterdesk.ps1 -SkipVerify

# Custom RustDesk Client API port (default 21121; Go admin API is GO_API_PORT=21114)
$env:API_PORT = "21121"
.\betterdesk.ps1 -Auto

Installation Path

Path	Description
`C:\BetterDesk\`	Go server binary, keys, database
`C:\BetterDeskConsole\`	Node.js web console

Services are registered via NSSM and can be managed from services.msc.

Docker Installation

Quick Start (Pre-built Images)

All-in-one image (server + relay + web console in one container) — recommended:

curl -fsSL https://raw.githubusercontent.com/UNITRONIX/BetterDesk/main/docker-compose.quick.single.yml -o docker-compose.yml
docker compose pull && docker compose up -d
docker compose exec betterdesk betterdesk-show-admin-credentials

Open http://your-server:5000 (plain HTTP, not HTTPS) and log in with the password printed above.

Legacy two-container layout

curl -fsSL https://raw.githubusercontent.com/UNITRONIX/BetterDesk/main/docker-compose.quick.yml -o docker-compose.yml
docker compose pull && docker compose up -d
docker compose exec console betterdesk-show-admin-credentials

Split layout uses API port 21114; the all-in-one container uses 21121.

Build Locally

git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk
docker compose up -d --build

Interactive Docker Script

./betterdesk-docker.sh

See Docker for detailed Docker documentation.

FreeBSD (experimental)

FreeBSD is Tier 3 (community). There is no betterdesk.sh path (that installer assumes Linux + systemd). Build the Go server and Node panel from source, then optionally install the example rc.d scripts from the repository.

Quick outline

pkg install -y git go node npm python3 ca_root_nss

git clone https://github.com/UNITRONIX/BetterDesk.git
cd BetterDesk/betterdesk-server
CGO_ENABLED=0 go build -o betterdesk-server .
install -d /usr/local/betterdesk
install -m 755 betterdesk-server /usr/local/betterdesk/
# Place id_ed25519 / id_ed25519.pub under /usr/local/betterdesk

# Panel: copy web-nodejs → /usr/local/BetterDeskConsole, then:
cd /usr/local/BetterDeskConsole
npm ci --omit=dev
# Configure .env (RUSTDESK_DIR=/usr/local/betterdesk, etc.)

install -m 755 /path/to/BetterDesk/contrib/freebsd/rc.d/betterdesk_server \
  /usr/local/etc/rc.d/betterdesk_server
install -m 755 /path/to/BetterDesk/contrib/freebsd/rc.d/betterdesk_console \
  /usr/local/etc/rc.d/betterdesk_console

sysrc betterdesk_server_enable=YES
sysrc betterdesk_server_relay=YOUR.PUBLIC.IP
sysrc betterdesk_console_enable=YES
service betterdesk_server start
service betterdesk_console start

Full notes, path defaults, and limits (no panel updater FreeBSD binaries): see contrib/freebsd/README.md in the repo. Pull requests improving FreeBSD packaging are welcome (#310).

PostgreSQL Setup

By default, BetterDesk uses SQLite. To use PostgreSQL:

During Installation

When prompted for database type, choose PostgreSQL and provide the connection DSN:

postgres://user:password@host:5432/betterdesk?sslmode=disable

For a native Linux installation with a local PostgreSQL server, you can select PostgreSQL non-interactively:

sudo ./betterdesk.sh --auto --postgresql

The installer creates the BetterDesk role and database, then configures narrowly scoped pg_hba.conf rules for 127.0.0.1/32 and ::1/128 using scram-sha-256. It reloads PostgreSQL before testing the same TCP/password connection used by BetterDesk. Remote PostgreSQL hosts are not modified; their authentication policy remains operator-managed.

Migrate Existing Data

# Interactive
sudo ./betterdesk.sh
# Choose option M — Migrate databases

# Or use the migration tool directly
./tools/migrate/migrate-linux-amd64 -mode sqlite2pg \
  -src /opt/betterdesk/db_v2.sqlite3 \
  -dst "postgres://user:pass@localhost:5432/betterdesk"

See Migration for more details.

After Installation

Open http://your-server:5000 in a browser
Log in with the admin credentials displayed during installation
Configure your Client Setup to connect to your server
Optionally configure TLS/SSL certificates for encrypted connections

Upgrading

From Previous BetterDesk Version

# Linux
sudo ./betterdesk.sh
# Choose option 2 — Update

# Windows
.\betterdesk.ps1
# Choose option 2 — Update

The update process preserves:

Database files (db_v2.sqlite3; legacy auth.db if still in use)
PostgreSQL configuration
SSL certificates
API keys
Admin credentials

From RustDesk OSS Server

If you are migrating from the original RustDesk OSS server (hbbs+hbbr), the installer detects the legacy Rust server and recommends a fresh install. See Migration for data migration steps.

Uninstalling

# Linux
sudo ./betterdesk.sh
# Choose option 9 — Uninstall

# Windows
.\betterdesk.ps1
# Choose option 9 — Uninstall

This removes all services, binaries, and optionally data files.

Check it worked

# Linux services
sudo systemctl status betterdesk-server betterdesk-console
curl -s http://localhost:21114/api/health
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/

Expect health JSON and HTTP 200 (or a login redirect) from the panel. Then Client Setup.

Installation

Installation

Requirements

Linux

Windows

Docker

FreeBSD (experimental / community)

Linux Installation

Interactive Mode

Automatic Mode

Options

Installation Path

Verify Installation

Windows Installation

Interactive Mode

Automatic Mode

Options

Installation Path

Docker Installation

Quick Start (Pre-built Images)

Build Locally

Interactive Docker Script

FreeBSD (experimental)

Quick outline

PostgreSQL Setup

During Installation

Migrate Existing Data

After Installation

Upgrading

From Previous BetterDesk Version

From RustDesk OSS Server

Uninstalling

Check it worked

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Start

Console

Ops

Help

Advanced

Clone this wiki locally