---
title: "Déploiement d'Apache Guacamole via Docker sur Debian 12 (Bookworm)"
description:
tags: []
date: 2026-03-11 00:27
lastmod: 2026-03-11 01:19
type:
  - article
category:
  - "[[Guide]]"
status: brouillon
---

# Déploiement d'Apache Guacamole via Docker sur Debian 12 (Bookworm)

L'installation d'Apache Guacamole peut vite devenir un enfer de dépendances (Java, Tomcat, extensions JDBC). Le passage par Docker simplifie tout, à condition de bien gérer la persistance des données et l'initialisation de la base PostgreSQL.

## 1. La Philosophie du Stack

Nous utilisons un trio de conteneurs isolés :

- **Guacamole Client** : L'interface Web (Java/Tomcat).
    
- **Guacd** : Le moteur natif (proxy RDP/SSH/VNC).
    
- **PostgreSQL** : Le cerveau (stockage des utilisateurs et connexions).
    

## 2. Préparation du terrain

On commence par structurer notre projet sur l'hôte :

```Bash
mkdir ~/guacamole-docker && cd ~/guacamole-docker
mkdir -p guacamole-home data init
```

## 3. Le Docker-Compose "Gagnant"

Le secret d'une installation qui ne casse pas lors des mises à jour réside dans l'utilisation d'un fichier `guacamole.properties` externe.

`nano docker-compose.yml`

```YAML
services:
  # Moteur de protocoles
  guacd:
    image: guacamole/guacd
    container_name: guacd
    restart: always

  # Base de données
  postgres:
    image: postgres:15
    container_name: guac-postgres
    restart: always
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: TonMotDePasseFort
    volumes:
      - ./data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d

  # Interface Web
  guacamole:
    image: guacamole/guacamole
    container_name: guacamole
    restart: always
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRESQL_HOSTNAME: postgres
      POSTGRESQL_DATABASE: guacamole_db
      POSTGRESQL_USER: guacamole_user
      POSTGRESQL_PASSWORD: TonMotDePasseFort
    volumes:
      - ./guacamole-home/guacamole.properties:/etc/guacamole/guacamole.properties
    depends_on:
      - guacd
      - postgres
```

## 4. Initialisation de la Base de Données

C’est l'étape où 90% des installations échouent. Il faut générer le schéma SQL officiel de Guacamole et le donner à manger à Postgres.

```Bash
# Générer le script SQL
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > ./init/01_initdb.sql

# Lancer les conteneurs (Postgres va lire le dossier ./init)
docker-compose up -d
```

## 5. Configuration Fine (`guacamole.properties`)

Pour éviter que Java n'ignore vos variables d'environnement, créez ce fichier :

`nano guacamole-home/guacamole.properties`

```Properties
postgresql-hostname: postgres
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: TonMotDePasseFort
# Optionnel : priorité à la DB
extension-priority: postgresql
```

## 6. Le "Cheat Code" pour le premier accès

Si `guacadmin` / `guacadmin` vous renvoie un "Identifiant incorrect" (souvent dû à un souci de hachage lors de l'init), créez un admin de secours directement en SQL :

```Bash
docker exec -i guac-postgres psql -U guacamole_user -d guacamole_db -c "INSERT INTO guacamole_entity (name, type) VALUES ('admin_devops', 'USER');"
docker exec -i guac-postgres psql -U guacamole_user -d guacamole_db -c "INSERT INTO guacamole_user (entity_id, password_hash, password_salt, password_date) SELECT entity_id, decode('8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918', 'hex'), NULL, CURRENT_TIMESTAMP FROM guacamole_entity WHERE name = 'admin_devops';"
docker exec -i guac-postgres psql -U guacamole_user -d guacamole_db -c "INSERT INTO guacamole_system_permission (entity_id, permission) SELECT entity_id, permission::guacamole_system_permission_type FROM guacamole_entity, (VALUES ('CREATE_CONNECTION'), ('CREATE_USER'), ('ADMINISTER')) AS p (permission) WHERE name = 'admin_devops';"
```

_Identifiants : `admin_devops` / `admin`_

---

## 🛠 Tips de DevOps :

- **Logs** : Utilisez `docker logs -f guacamole` pour voir les extensions se charger. Vous devez voir `PostgreSQL Authentication loaded`.
    
- **Sécurité** : Une fois connecté, créez votre utilisateur final et **supprimez** les comptes par défaut ou de secours.
    
- **HTTPS** : Ne laissez jamais Guacamole en HTTP (8080). Posez un **Nginx Proxy Manager** ou un **Traefik** devant pour gérer le SSL.