RustDesk Server Deployment (Debian 13 + Ansible + Semaphore)

This directory contains Ansible playbooks and a Docker Compose template to deploy the RustDesk remote support server (open-source or Pro) on Debian 13 using Docker. The setup supports both components: hbbs (signal / rendezvous) and hbbr (relay).

Contents

• 01-DockerInstall.yml – Installs the latest Docker Engine, CLI, containerd, and Compose plugin on Debian 13.
• 02-RustDeskInstall.yml – Deploys RustDesk Server (Pro or Open Source) via Docker Compose.
• rustdesk-compose.yml.j2 – Jinja2 template rendered into docker-compose.yml describing the hbbs and hbbr services.
• README.md – Documentation (this file).

Prerequisites

1. Target hosts are running Debian 13 with network access to Docker's official repository.
2. SSH access with privilege escalation (sudo) for Ansible.
3. Ansible controller (Semaphore or CLI) has these playbooks and (optionally) a RustDesk Pro license file.
4. Firewall or security groups allow required ports.

Inventory Example

[rustdesk_hosts]
rustdesk1.example.com
rustdesk2.example.com

Adjust hostnames/IPs as needed.

Variables (from 02-RustDeskInstall.yml)

Variable	Purpose	Default
rustdesk_pro	Enable Pro (license file mounted)	true
rustdesk_version	Docker image tag (latest or pinned)	latest
rustdesk_base_dir	Base directory for data & compose file	/opt/rustdesk
rustdesk_data_dir	Persistent data directory	<base>/data
rustdesk_license_file_src	Relative path to license file on controller	files/rustdesk.lic
rustdesk_license_file_dest	Path on target host	<base>/rustdesk.lic
rustdesk_image_open	Open source image name	rustdesk/rustdesk-server
rustdesk_image_pro	Pro image name	rustdesk/rustdesk-server-pro
rustdesk_ports_hbbs	Port mappings for hbbs	See playbook
rustdesk_ports_hbbr	Port mappings for hbbr	See playbook

To deploy open-source edition set: rustdesk_pro: false.

Required Ports

Open these (adjust if you change mappings):

• 21115/tcp, 21116/tcp, 21116/udp – hbbs signaling & NAT traversal
• 21118/tcp – file transfer
• 21117/tcp – hbbr relay
• 21119/tcp – web client / reverse proxy / relay

Running with Ansible CLI

ansible-playbook -i inventory 01-DockerInstall.yml
ansible-playbook -i inventory 02-RustDeskInstall.yml -e rustdesk_pro=true

For open source: -e rustdesk_pro=false.

Using Semaphore

1. Create a project and attach your Git repository containing these files.
2. Add environment / inventory for your rustdesk_hosts group.
3. Create a template/job for 01-DockerInstall.yml (run once per new host).
4. Create a template/job for 02-RustDeskInstall.yml with optional extra vars.
5. Upload the license file to the repository path files/rustdesk.lic or use a Semaphore vault + pre-task to place it.
6. Run the RustDesk deployment job and monitor logs; containers should appear with docker ps.

License (Pro Edition)

Place your Pro license at files/rustdesk.lic on the controller. The playbook copies it to the target path and mounts it into both containers. If absent, deployment still proceeds (license-dependent features disabled). Set rustdesk_pro: false if you do not have a license.

Customization Examples

• Pin version: -e rustdesk_version=1.1.13
• Change base directory: -e rustdesk_base_dir=/srv/rustdesk
• Override ports: define rustdesk_ports_hbbs / rustdesk_ports_hbbr via extra vars or a vars file.

Updating

To update to the newest image tag:

ansible-playbook -i inventory 02-RustDeskInstall.yml -e rustdesk_version=latest

The play pulls the image and recreates containers if needed.

Uninstall

Manual example:

docker compose -f /opt/rustdesk/docker-compose.yml down
rm -rf /opt/rustdesk

You can convert this into an Ansible play (task using file: state=absent).

Troubleshooting

Symptom	Action
Ports not reachable	Verify firewall/iptables and Docker published port list.
License not applied	Ensure files/rustdesk.lic exists and rustdesk_pro: true. Check container logs.
Containers restart loop	Run docker logs rustdesk-hbbs / rustdesk-hbbr for errors (e.g., port conflicts).
Version mismatch	Pin rustdesk_version to a known working tag.

Security Notes

• Restrict SSH access; use Ansible vault for any sensitive overrides.
• Consider enabling TLS termination / reverse proxy in front of RustDesk (not covered here).
• Keep Docker Engine updated (rerun 01-DockerInstall.yml periodically or enable unattended upgrades).

Next Steps

• Add role structure (split into roles/docker and roles/rustdesk).
• Integrate health checks or monitoring (Prometheus node exporter, container metrics).
• Add automated syntax check pipeline.

---

Generated on: 2025-11-07