Portfolio
Retour à la documentation
Infrastructure & Services 2026-04-28

Deploiement de l'API RustDesk via Docker sur Debian 13

Documentation technique pour l'installation du serveur d'API RustDesj Sur Debian 13.

Documentation Technique :

Table des matieres

  1. Prerequis
  2. Installation de Docker
  3. Verification de Docker
  4. Installation de Docker Compose
  5. Deploiement de l'API RustDesk
  6. Configuration
  7. Lancement
  8. Tests
  9. Exploitation
  10. Troubleshooting

1. Prerequis

1.1 Environnement de reference

| Element | Valeur | |------------------------|-----------------------------------------------| | Systeme d'exploitation | Debian 13 | | Adresse IP du serveur | 10.192.193.110 | | Services RustDesk | hbbs (21115, 21116) + hbbr (21117) | | Docker | Non installe | | Acces | root | | Exposition reseau | LAN uniquement (pas d'acces public) |

1.2 Verification de l'etat des services RustDesk existants

Toutes les commandes de cette section sont a executer en tant que root, depuis n'importe quel repertoire.

Verifier que hbbs et hbbr sont actifs :

systemctl status hbbs

systemctl status hbbr

Les deux services doivent afficher Active: active (running). Si l'un d'eux est stoppe, ne pas continuer et resoudre le probleme RustDesk en priorite.

Verifier les ports utilises par RustDesk :

ss -tlnp | grep -E '21115|21116|21117'

Resultat attendu : trois lignes avec les ports en etat LISTEN.

Verifier que le port 8080 (port par defaut de l'API) est libre :

ss -tlnp | grep 8080

Si la commande ne retourne rien, le port 8080 est disponible. Si une ligne s'affiche, le port est occupe : utiliser le port 8081 a la place (voir section 6.2).

1.3 Mise a jour du systeme

apt update && apt upgrade -y

Installer les dependances necessaires a l'ajout du depot Docker :

apt install -y ca-certificates curl gnupg lsb-release apt-transport-https

2. Installation de Docker

Toutes les commandes de cette section sont a executer en tant que root.

2.1 Ajouter la cle GPG officielle de Docker

install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

2.2 Ajouter le depot officiel Docker

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

2.3 Mettre a jour la liste des paquets et installer Docker

apt update

apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.4 Activer et demarrer le service Docker

systemctl enable docker

systemctl start docker

2.5 Gestion des permissions utilisateur Docker

Par defaut, seul root peut utiliser Docker. Si un utilisateur non-root doit gerer les conteneurs (par exemple un compte nomme adminsisr), l'ajouter au groupe docker :

usermod -aG docker adminsisr

Pour que ce changement soit pris en compte sans deconnexion, executer la commande suivante en tant que cet utilisateur (pas en tant que root) :

newgrp docker

Cette etape est facultative si tout est gere en root.

3. Verification de Docker

3.1 Verifier que le service Docker tourne

systemctl status docker

La sortie doit afficher Active: active (running).

3.2 Verifier la version installee

docker version

docker compose version

3.3 Tester l'installation avec un conteneur de test

docker run --rm hello-world

La sortie doit contenir la ligne : Hello from Docker!

Ce conteneur est temporaire (--rm) et se supprime automatiquement apres execution. Il ne laisse aucun residus.

3.4 Verifier l'absence de conflit reseau avec RustDesk

Docker utilise le sous-reseau 172.17.0.0/16 par defaut pour son bridge interne. Verifier qu'il n'entre pas en conflit avec le reseau local :

ip route

Si 172.17.0.0/16 est deja utilise dans l'infrastructure locale, il faudra definir un sous-reseau Docker personnalise dans le docker-compose.yml (voir section 6.3).

4. Installation de Docker Compose

Docker Compose est installe automatiquement avec le paquet docker-compose-plugin a l'etape 2.3. Il est integre en tant que sous-commande de Docker.

Verifier l'installation :

docker compose version

Resultat attendu (les numeros de version peuvent varier) :

Docker Compose version v2.x.x

La syntaxe utilisee dans toute cette documentation est docker compose (avec espace), et non docker-compose (avec tiret). La version avec tiret est l'ancienne version autonome, desormais obsolete. Ne pas l'utiliser.

5. Deploiement de l'API RustDesk

5.1 Creer le repertoire de travail

Toutes les operations de deploiement se font depuis le repertoire /opt/rustdesk-api. Ce repertoire contiendra les fichiers de configuration et les donnees persistantes.

mkdir -p /opt/rustdesk-api

cd /opt/rustdesk-api

5.2 Creer le fichier de configuration de l'API

Ce fichier server.yaml est le fichier de configuration principal de l'application. Il doit exister avant de lancer le conteneur.

nano /opt/rustdesk-api/server.yaml

Coller le contenu suivant :

signKey: "CHANGEMOICECLEsecrete32caracteres"
debugMode: false
db:
  driver: "sqlite"
  dsn: "./server.db"
  timeZone: "Europe/Paris"
  showSql: false
httpConfig:
  printRequestLog: false
  staticdir: "/app/dist"
  port: ":8080"
smtpConfig:
  host: "127.0.0.1"
  port: 1025
  username: ""
  password: ""
  encryption: "none"
  from: "rustdesk@localhost"
jobsConfig:
  deviceCheckJob:
    duration: 30

Enregistrer et quitter : Ctrl+O, Entree, Ctrl+X.

Remplacer la valeur de signKey par une chaine aleatoire de 32 caracteres minimum. Cette cle signe les tokens d'authentification. Elle ne doit jamais rester avec la valeur d'exemple. Pour en generer une :

openssl rand -base64 32

Copier la valeur affichee et la coller dans server.yaml a la place de CHANGEMOICECLEsecrete32caracteres, en conservant les guillemets.

5.3 Creer le fichier docker-compose.yml

nano /opt/rustdesk-api/docker-compose.yml

Coller le contenu suivant :

services:
  rustdesk-api:
    container_name: rustdesk-api-server-pro
    image: ghcr.io/lantongxue/rustdesk-api-server-pro:latest
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./server.yaml:/app/data/server.yaml
      - ./data:/app/data
    network_mode: host
    restart: unless-stopped

Enregistrer et quitter : Ctrl+O, Entree, Ctrl+X.

Explication des parametres :

  • network_mode: host : le conteneur partage directement la pile reseau de l'hote. Cela evite toute complexite de NAT et permet a l'API d'acceder aux services hbbs/hbbr via localhost. C'est l'option recommandee dans ce contexte purement interne.
  • restart: unless-stopped : le conteneur redemarrera automatiquement au boot du serveur et en cas de crash, sauf s'il est arrete manuellement avec docker compose down.
  • volumes : le repertoire ./data est monte pour persister la base de donnees SQLite entre les redemarrages du conteneur. Le fichier server.yaml est monte separement pour permettre sa modification sans reconstruire l'image.

5.4 Creer le repertoire de donnees persistantes

mkdir -p /opt/rustdesk-api/data

chmod 755 /opt/rustdesk-api/data

6. Configuration

6.1 Restriction d'acces reseau (acces LAN uniquement)

Avec network_mode: host, le port 8080 ecoute sur toutes les interfaces du serveur. Pour garantir que l'API n'est accessible que depuis le reseau interne 10.192.193.0/24, ajouter une regle iptables :

iptables -A INPUT -p tcp --dport 8080 ! -s 10.192.193.0/24 -j DROP

Rendre cette regle persistante au redemarrage :

apt install -y iptables-persistent

netfilter-persistent save

6.2 Adaptation si le port 8080 est deja utilise

Si le port 8080 est occupe (detecte a l'etape 1.2), modifier server.yaml :

nano /opt/rustdesk-api/server.yaml

Modifier uniquement la ligne du port :

  port: ":8081"

Enregistrer et quitter : Ctrl+O, Entree, Ctrl+X.

Adapter ensuite la regle iptables en remplacant 8080 par 8081 dans la commande de la section 6.1.

6.3 Verification de l'absence de conflit de ports avec RustDesk

Recapitulatif des ports utilises sur le serveur apres le deploiement :

| Service | Port(s) | Protocole | Gere par | |------------------|------------------|-----------|------------| | hbbs | 21115, 21116 | TCP/UDP | systemd | | hbbr | 21117 | TCP | systemd | | rustdesk-api | 8080 (ou 8081) | TCP | Docker |

Aucun conflit n'existe entre ces ports. Les services hbbs et hbbr ne sont pas modifies.

6.4 Connexion de l'API a l'infrastructure RustDesk existante

L'API RustDesk est une couche de gestion des utilisateurs et des sessions. Elle ne remplace pas hbbs ou hbbr et ne necessite aucune modification de leurs fichiers de configuration ni de leurs services systemd.

La connexion se fait cote client RustDesk. Sur chaque poste client, configurer les parametres du serveur comme suit :

  • Serveur ID : 10.192.193.110
  • Serveur relay : 10.192.193.110
  • Serveur API : http://10.192.193.110:8080

Ces parametres se trouvent dans le client RustDesk sous : Parametres > Reseau > Serveur ID/Relay > et dans le champ "API Server".

7. Lancement

Toutes les commandes de cette section sont a executer depuis /opt/rustdesk-api.

cd /opt/rustdesk-api

7.1 Telecharger l'image Docker

docker compose pull

Cette commande telecharge l'image ghcr.io/lantongxue/rustdesk-api-server-pro:latest depuis le registre GitHub. Cela peut prendre quelques minutes selon la bande passante disponible.

7.2 Demarrer le conteneur

docker compose up -d

L'option -d (detached) lance le conteneur en arriere-plan et rend la main au terminal.

7.3 Creer le compte administrateur

Cette etape est a effectuer une seule fois, juste apres le premier demarrage. Attendre 5 secondes apres docker compose up -d avant d'executer cette commande :

docker exec rustdesk-api-server-pro rustdesk-api-server-pro user add admin VotreMotDePasse --admin

Remplacer VotreMotDePasse par un mot de passe robuste. Ce compte est celui utilise pour se connecter a l'interface web de gestion.

7.4 Verifier que les services RustDesk sont toujours actifs

systemctl status hbbs

systemctl status hbbr

Les deux doivent toujours afficher Active: active (running). Le lancement de Docker et du conteneur ne doit pas avoir affecte ces services.

8. Tests

8.1 Verifier que le conteneur tourne

docker ps

Resultat attendu : une ligne avec rustdesk-api-server-pro et le statut Up.

docker compose ps

Affiche le statut specifique aux services definis dans le docker-compose.yml du repertoire courant.

8.2 Consulter les logs du conteneur

Afficher les logs en temps reel (quitter avec Ctrl+C) :

docker compose logs -f

Afficher uniquement les 50 dernieres lignes :

docker compose logs --tail=50

Verifier l'absence d'erreurs au demarrage dans ces logs. Les lignes normales indiquent que le serveur ecoute sur le port configure.

8.3 Tester la disponibilite de l'API depuis le serveur

curl -s http://127.0.0.1:8080/api/health-check

Une reponse JSON doit s'afficher. Si la commande reste bloquee ou retourne une erreur de connexion, consulter la section Troubleshooting.

8.4 Tester l'acces depuis le reseau interne

Executer depuis un autre poste du reseau interne (pas depuis le serveur lui-meme) :

curl -s http://10.192.193.110:8080/api/health-check

8.5 Verifier l'interface web d'administration

Depuis un navigateur sur le reseau interne, acceder a :

http://10.192.193.110:8080

La page de connexion de l'interface de gestion doit s'afficher. Se connecter avec le compte cree a l'etape 7.3 (exemple : admin / VotreMotDePasse).

8.6 Tester l'authentification via l'API

curl -s -X POST http://127.0.0.1:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"VotreMotDePasse"}'

Une reponse JSON contenant un token est attendue. Cela confirme que l'authentification fonctionne correctement.

8.7 Verifier l'absence de regression sur les services RustDesk

ss -tlnp | grep -E '21115|21116|21117'

Les trois ports doivent toujours etre en ecoute.

systemctl is-active hbbs hbbr

Les deux lignes doivent afficher active.

9. Exploitation

9.1 Demarrer le conteneur API

cd /opt/rustdesk-api
docker compose up -d

9.2 Arreter le conteneur API

cd /opt/rustdesk-api
docker compose down

docker compose down arrete et supprime le conteneur, mais conserve les donnees. Le repertoire ./data est un volume monte sur l'hote : les donnees ne sont pas perdues.

9.3 Redemarrer le conteneur

cd /opt/rustdesk-api
docker compose restart

9.4 Mettre a jour l'image Docker

cd /opt/rustdesk-api
docker compose pull
docker compose up -d

Docker Compose detecte que l'image a change et recrée le conteneur avec la nouvelle version. Les donnees sont preservees grace au volume.

Supprimer les anciennes images pour liberer de l'espace disque :

docker image prune -f

9.5 Verification de la persistance au redemarrage du serveur

Le parametre restart: unless-stopped garantit que le conteneur redemarrera automatiquement si le serveur reboot, a condition que Docker soit actif.

Verifier que Docker demarre au boot :

systemctl is-enabled docker

La reponse doit etre enabled. Si ce n'est pas le cas :

systemctl enable docker

Tester le comportement en simulant un redemarrage :

reboot

Apres redemarrage, verifier :

docker ps
systemctl is-active hbbs hbbr

9.6 Ajouter un utilisateur supplementaire

Utilisateur standard :

docker exec rustdesk-api-server-pro rustdesk-api-server-pro user add nomutilisateur MotDePasse

Utilisateur administrateur :

docker exec rustdesk-api-server-pro rustdesk-api-server-pro user add nomutilisateur MotDePasse --admin

9.7 Sauvegarder les donnees de l'API

Les donnees (base SQLite) sont dans /opt/rustdesk-api/data/. Sauvegarder ce repertoire :

cp -r /opt/rustdesk-api/data /root/backup-rustdesk-api-$(date +%Y%m%d)

Pour une sauvegarde propre, stopper le conteneur avant de copier la base de donnees :

cd /opt/rustdesk-api
docker compose down
cp -r /opt/rustdesk-api/data /root/backup-rustdesk-api-$(date +%Y%m%d)
docker compose up -d

9.8 Consulter l'espace disque utilise par Docker

docker system df

9.9 Rappel : gestion des services RustDesk (sans lien avec Docker)

Ces commandes concernent uniquement hbbs et hbbr, geres par systemd, independamment de Docker :

systemctl restart hbbs

systemctl restart hbbr

systemctl stop hbbs

systemctl stop hbbr

10. Troubleshooting

Probleme 1 : Le conteneur ne demarre pas

Symptome : docker compose up -d s'execute sans erreur visible mais docker ps ne montre pas le conteneur.

Diagnostic :

cd /opt/rustdesk-api
docker compose logs

docker ps -a

L'option -a affiche tous les conteneurs, y compris ceux a l'etat Exited.

Cause : le fichier server.yaml est mal forme

Verifier la syntaxe :

cat /opt/rustdesk-api/server.yaml

S'assurer que l'indentation utilise uniquement des espaces (jamais de tabulations) et que les guillemets sont bien fermes. Corriger le fichier puis relancer :

docker compose down
docker compose up -d

Cause : le port 8080 est deja utilise

ss -tlnp | grep 8080

Si le port est occupe, modifier server.yaml pour utiliser le port 8081 (voir section 6.2) puis relancer :

docker compose down
docker compose up -d

Probleme 2 : L'interface web n'est pas accessible depuis le LAN

Symptome : curl http://127.0.0.1:8080/api/health-check fonctionne depuis le serveur, mais le navigateur depuis un autre poste ne repond pas.

Verifier les regles iptables :

iptables -L INPUT -n --line-numbers

Identifier si une regle bloque le port 8080. Si une regle trop restrictive a ete ajoutee par erreur, la supprimer par son numero de ligne :

iptables -D INPUT <numero_de_ligne>

Verifier si ufw est actif et bloque le port :

ufw status

Si ufw est actif, autoriser le port depuis le reseau interne :

ufw allow from 10.192.193.0/24 to any port 8080

Probleme 3 : Les services hbbs ou hbbr se sont arretes apres l'installation de Docker

Symptome : systemctl status hbbs affiche inactive ou failed.

Docker modifie les regles iptables au demarrage, ce qui peut dans de rares cas perturber des services reseau existants.

Diagnostic :

journalctl -u hbbs -n 50

journalctl -u hbbr -n 50

Solution : redemarrer les services et verifier les regles de la chaine FORWARD :

systemctl restart hbbs
systemctl restart hbbr

iptables -L FORWARD -n

Docker ajoute des regles dans la chaine FORWARD. Elles ne doivent pas bloquer les connexions vers les ports 21115, 21116 et 21117. En cas de persistance du probleme, redemarrer Docker avant les services RustDesk :

systemctl restart docker
systemctl restart hbbs
systemctl restart hbbr

Probleme 4 : Erreur lors de la creation du compte administrateur

Symptome : docker exec retourne une erreur ou n'affiche rien.

Verifier que le conteneur est en cours d'execution :

docker ps | grep rustdesk-api

Si le conteneur n'apparait pas, le demarrer :

cd /opt/rustdesk-api
docker compose up -d

Attendre 5 secondes que l'application s'initialise, puis relancer :

docker exec rustdesk-api-server-pro rustdesk-api-server-pro user add admin VotreMotDePasse --admin

Probleme 5 : L'image Docker ne peut pas etre telechargee

Symptome : docker compose pull echoue avec une erreur reseau ou un timeout.

Verifier la connectivite depuis le serveur :

curl -I https://ghcr.io

Si le serveur n'a pas acces a Internet, proceder en mode deconnecte. Depuis une machine disposant d'un acces Internet :

docker pull ghcr.io/lantongxue/rustdesk-api-server-pro:latest

docker save ghcr.io/lantongxue/rustdesk-api-server-pro:latest -o rustdesk-api.tar

Transferer le fichier vers le serveur via scp :

scp rustdesk-api.tar root@10.192.193.110:/opt/rustdesk-api/

Sur le serveur, charger l'image :

docker load -i /opt/rustdesk-api/rustdesk-api.tar

Demarrer le conteneur normalement :

cd /opt/rustdesk-api
docker compose up -d

Probleme 6 : Le conteneur redemarrage en boucle

Symptome : docker ps montre le conteneur avec le statut Restarting et un compteur de redemarrage croissant.

Diagnostic :

cd /opt/rustdesk-api
docker compose logs --tail=100

Cause : erreur de syntaxe dans server.yaml

Corriger le fichier server.yaml, puis :

docker compose down
docker compose up -d

Cause : permissions incorrectes sur le repertoire data

chmod 755 /opt/rustdesk-api/data
chown root:root /opt/rustdesk-api/data

Puis :

docker compose down
docker compose up -d

Probleme 7 : Audit des ports ouverts par Docker

Pour verifier qu'aucun port inattendu n'est ouvert par Docker :

ss -tlnp | grep docker

docker network ls

docker network inspect bridge

Ces commandes permettent d'auditer les reseaux Docker et de confirmer que seul le port 8080 (ou 8081) est expose par le conteneur.