BetterDesk/docs/wiki/Docker.md

Docker Deployment

BetterDesk offers multiple Docker deployment options.

---

Quick Start (Pre-built Images)

The fastest way to get started — no build required:

curl -fsSL https://raw.githubusercontent.com/UNITRONIX/BetterDesk/main/docker-compose.quick.yml \
  -o docker-compose.yml
docker compose up -d

Default access:

• Web Console: http://localhost:5000
• Default admin: admin / check container logs for password

# View generated admin password
docker compose logs console | grep "Admin password"

---

Deployment Options

Option 1: Multi-Container (Recommended for Production)

Separate containers for each service:

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

docker-compose.yml runs 3 containers:

• betterdesk-server — Go server (signal + relay + API)
• betterdesk-console — Node.js web console
• Shared volume for database and keys

Option 2: Single Container

All services in one container (simpler, good for testing):

docker compose -f docker-compose.single.yml up -d --build

Uses supervisord to run Go server + Node.js console in a single container.

⚠️ Note: In single-container mode, SIGNAL_PORT=21116 is set explicitly to prevent conflict with PORT=5000 (used by Node.js).

Option 3: Interactive Docker Script

./betterdesk-docker.sh

Interactive menu with:

• New installation
• Update
• Migrate from existing RustDesk Docker
• Database migration (SQLite ↔ PostgreSQL)

---

Ports

Expose the following ports in your Docker configuration:

ports:
  - "21114:21114"   # Go API
  - "21115:21115"   # NAT test
  - "21116:21116"   # Signal (TCP)
  - "21116:21116/udp"  # Signal (UDP)
  - "21117:21117"   # Relay
  - "21118:21118"   # WS Signal
  - "21119:21119"   # WS Relay
  - "21121:21121"   # Client API (Node.js)
  - "5000:5000"     # Web Console

---

Volumes

Data Persistence

volumes:
  betterdesk-data:
    driver: local

Persist these paths:

• /data/ — Database files, keys, API key
• /opt/BetterDeskConsole/data/ — Console database, auth

Important Files in Volume

File	Description
id_ed25519	Server private key
id_ed25519.pub	Server public key
db_v2.sqlite3	Go server database
.api_key	API authentication key
auth.db	Console user database

⚠️ Never delete id_ed25519 — all connected clients use this key. Regenerating it requires reconfiguring every client.

---

PostgreSQL with Docker

Add PostgreSQL Container

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: betterdesk
      POSTGRES_PASSWORD: your-secure-password
      POSTGRES_DB: betterdesk
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U betterdesk"]
      interval: 5s
      timeout: 5s
      retries: 5

  server:
    # ... existing config ...
    environment:
      DB_URL: postgres://betterdesk:your-secure-password@postgres:5432/betterdesk?sslmode=disable
    depends_on:
      postgres:
        condition: service_healthy

  console:
    # ... existing config ...
    environment:
      DB_TYPE: postgresql
      DATABASE_URL: postgres://betterdesk:your-secure-password@postgres:5432/betterdesk?sslmode=disable

volumes:
  postgres-data:

---

Environment Variables

Go Server Container

Variable	Default	Description
SIGNAL_PORT	21116	Signal server port
RELAY_PORT	21117	Relay server port
DB_URL	db_v2.sqlite3	Database path or PostgreSQL DSN
RELAY_SERVERS	auto-detected	Relay server addresses
API_KEY	auto-generated	API authentication key
CDAP_ENABLED	N	Enable CDAP gateway

Node.js Console Container

Variable	Default	Description
PORT	5000	Web console port
BETTERDESK_API_URL	http://server:21114/api	Go API URL
API_KEY	from file	API key
DB_TYPE	sqlite	Database type
DATABASE_URL	(empty)	PostgreSQL DSN
SESSION_SECRET	auto-generated	Session encryption key

---

Building Images

Build All Images

docker compose build

Build Individual Images

# Go server
docker build -f Dockerfile.server -t betterdesk-server .

# Node.js console
docker build -f Dockerfile.console -t betterdesk-console .

# Single container (all-in-one)
docker build -t betterdesk .

---

Monitoring

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f server
docker compose logs -f console

Health Check

# Server health
curl http://localhost:21114/api/health

# Console health
curl http://localhost:5000

Container Status

docker compose ps

---

Migration from RustDesk Docker

If you have an existing RustDesk Docker deployment:

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

The migration:

1. Stops existing RustDesk containers
2. Copies db_v2.sqlite3 and id_ed25519 keys
3. Starts BetterDesk containers
4. Verifies data migration

See Migration for more details.

---

Troubleshooting

GHCR "denied" Error

If pre-built images from ghcr.io are not available:

# Option 1: Build locally
docker compose up -d --build

# Option 2: Authenticate with GitHub
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

DNS Resolution Failures During Build

Docker build on some hosts (AlmaLinux, CentOS) may fail DNS resolution. The Dockerfiles include retry logic for apk add commands. If issues persist:

# Add DNS to Docker daemon
echo '{"dns": ["8.8.8.8", "8.8.4.4"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

SELinux Volume Mount Issues

On RHEL/CentOS with SELinux:

# Option 1: Named volumes (recommended)
# Already used in docker-compose.yml

# Option 2: :z flag for bind mounts
volumes:
  - ./data:/data:z

# Option 3: Set context
sudo chcon -Rt svirt_sandbox_file_t ./data

Port 5000 Conflict (Single Container)

If both Go server and Node.js try to bind port 5000, ensure SIGNAL_PORT=21116 is set in the Go server environment. This is set automatically in supervisord.conf and entrypoint.sh.

---

See also

• Installation — bare-metal alternative
• Panel Updates — GHCR image updates
• GHCR package readme