Migration - UNITRONIX/BetterDesk GitHub Wiki

Migration Guide

BetterDesk provides migration tools for moving between databases and from legacy RustDesk deployments.

Migration Modes

The migration tool supports 5 modes:

Mode Source Target Description
rust2go RustDesk Rust db_v2.sqlite3 BetterDesk Go SQLite Migrate from original RustDesk server
sqlite2pg BetterDesk Go SQLite PostgreSQL Move to PostgreSQL for production
pg2sqlite PostgreSQL BetterDesk Go SQLite Reverse migration for backup/testing
nodejs2go Node.js console SQLite BetterDesk Go SQLite Merge Node.js console data
backup Any SQLite SQLite copy Create timestamped backup

Using the ALL-IN-ONE Script

The simplest way to migrate:

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

# Windows
.\betterdesk.ps1
# Choose option M — Migrate databases

The script:

  1. Detects current database configuration
  2. Offers available migration paths
  3. Creates automatic backup before migration
  4. Runs the migration tool
  5. Updates .env and service files
  6. Restarts services

Using the Migration Tool Directly

Binary Location

# Linux
./betterdesk-server/tools/migrate/migrate-linux-amd64

# Or compile from source
cd betterdesk-server/tools/migrate
go build -o migrate .

Command Line

./migrate -mode <mode> -src <source> -dst <destination> [options]

Examples

RustDesk → BetterDesk Go

./migrate -mode rust2go \
  -src /path/to/rustdesk/db_v2.sqlite3 \
  -dst /opt/rustdesk/db_v2.sqlite3

This handles schema differences:

  • peer table → peers table
  • Column name mapping
  • UUID generation for entries without UUIDs

SQLite → PostgreSQL

./migrate -mode sqlite2pg \
  -src /opt/rustdesk/db_v2.sqlite3 \
  -dst "postgres://betterdesk:password@localhost:5432/betterdesk?sslmode=disable"

Migrated data:

  • All peers with status, tags, notes
  • Users with roles and TOTP config
  • API keys
  • Server config
  • Audit log entries
  • Address books
  • Access policies

PostgreSQL → SQLite

./migrate -mode pg2sqlite \
  -src "postgres://betterdesk:password@localhost:5432/betterdesk" \
  -dst /opt/rustdesk/db_v2.sqlite3

Useful for creating portable backups or moving to a smaller deployment.

Node.js Console → Go Server

./migrate -mode nodejs2go \
  -src /opt/BetterDeskConsole/data/auth.db \
  -dst /opt/rustdesk/db_v2.sqlite3 \
  -node-auth /opt/BetterDeskConsole/data/auth.db

Merges:

  • peer table → peers
  • users table → users
  • Folder assignments
  • Tags

Data Preservation

The migration tool preserves:

Data rust2go sqlite2pg pg2sqlite nodejs2go
Peers ✅ ✅ ✅ ✅
Ed25519 keys ✅ ✅ ✅ N/A
UUIDs ✅ (generated) ✅ ✅ ✅ (generated)
ID history ✅ ✅ ✅ N/A
Bans ✅ ✅ ✅ N/A
Tags ✅ ✅ ✅ ✅
Notes N/A ✅ ✅ ✅
Users N/A ✅ ✅ ✅
API keys N/A ✅ ✅ N/A
Audit log N/A ✅ ✅ N/A
Address books N/A ✅ ✅ N/A
Access policies N/A ✅ ✅ N/A

Docker Migration

Migrate from RustDesk Docker

./betterdesk-docker.sh
# Choose option M — Migrate from RustDesk Docker

The script:

  1. Detects existing RustDesk containers and volumes
  2. Copies db_v2.sqlite3 and id_ed25519 from old volumes
  3. Runs rust2go migration
  4. Creates BetterDesk containers with migrated data

Migrate Docker to PostgreSQL

./betterdesk-docker.sh
# Choose option P — Migrate to PostgreSQL

Adds a PostgreSQL container, runs sqlite2pg migration, and updates services.

Upgrading from RustDesk Rust Server

If you're running the original RustDesk hbbs+hbbr:

Step 1: Stop Old Services

sudo systemctl stop rustdesksignal rustdeskrelay
# or
sudo systemctl stop hbbs hbbr

Step 2: Install BetterDesk

sudo ./betterdesk.sh
# Choose option 1 — New installation

Step 3: Migrate Data

sudo ./betterdesk.sh
# Choose option M — Migrate databases
# Select "Rust → Go" migration

Step 4: Verify

# Check device count
curl http://localhost:21114/api/server/stats

# Verify in web console
open http://localhost:5000

Step 5: Clean Up

# Remove old services (the installer does this automatically)
sudo systemctl disable rustdesksignal rustdeskrelay
sudo rm /etc/systemd/system/rustdesk*.service

Backup Before Migration

Always create a backup before migrating:

# Using the installer
sudo ./betterdesk.sh
# Choose option 5 — Backup

# Manual backup
cp /opt/rustdesk/db_v2.sqlite3 /opt/rustdesk/db_v2.sqlite3.backup
cp /opt/BetterDeskConsole/data/auth.db /opt/BetterDeskConsole/data/auth.db.backup

Troubleshooting Migration

"Migration tool not found"

# If Go is installed, compile from source
cd betterdesk-server/tools/migrate
go build -o migrate .

"Outdated migration binary"

The installer checks if the binary supports the -mode flag. If not:

# Rebuild
cd betterdesk-server/tools/migrate
go build -o migrate .

PostgreSQL connection refused

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql "postgres://betterdesk:password@localhost:5432/betterdesk"

# Check firewall
sudo ufw allow 5432/tcp

Duplicate key errors

If migrating to a database that already has data, the migration tool uses INSERT OR IGNORE (SQLite) or ON CONFLICT DO NOTHING (PostgreSQL) to skip duplicates.

⚠️ **GitHub.com Fallback** ⚠️