docker

Guacamole 설치(Docker)

Chanmin Kang

14 Jul 2025 • 6 min read

오픈소스 원격 데스크탑 게이트웨이 Guacamole

Apache Guacamole는 RDP, VNC, SSH 프로토콜을 지원하는 cilentless 원격 데스크탑 게이트웨이입니다.

Guacamole를 Docker-compose를 사용해 설치 해 보겠습니다.

설치 환경:
Ubuntu24.04 / Docker version 24.0.2 / Docker Compose version v2.35.1
docker, docker-compose 설치는 여기로

docker-compose.yml 작성

Guacamole는 실질적인 데몬 guacd, 웹 어플리케이션 guacamole, 데이터베이스 mysql 총 세 컨테이너로 구성됩니다.

services:
  guacd:
    image: guacamole/guacd:latest
    restart: unless-stopped

  guacamole:
    #Web application
    image: guacamole/guacamole:latest
    depends_on:
      - guacd
      - mysql

    ports:
      - [Your_Port]:8080 #사용하고자 하는 포트

    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: mysql
      MYSQL_DATABASE: db_guacamole
      MYSQL_USERNAME: user_guacamole
      MYSQL_PASSWORD: "SOME_USER_PASSWORD" #비밀번호 설정

      #Reverse Proxy
      #REMOTE_IP_VALVE_ENABLED: "true"
      #PROXY_ALLOWED_IPS_REGEX: "192\\.168\\.0\\.###" #reverse proxy주소
      
      #WEBAPP_CONTEXT: "ROOT" #/(root)주소로 접속
      
      #Two-factor Authentication
      #TOTP_ENABLED: "true"

  mysql:
    image: mysql:8.0
    restart: unless-stopped

    environment:
      MYSQL_ROOT_PASSWORD: "SOME_ROOT_PASSWORD" #비밀번호 설정
      MYSQL_DATABASE: db_guacamole           #위 guacamole서비스 DATABASE 동일
      MYSQL_USER: user_guacamole             #위 guacamole서비스 USERNAME 동일
      MYSQL_PASSWORD: "SOME_USER_PASSWORD"   #위 guacamole서비스 비밀번호 동일

    volumes:
      - ./data:/var/lib/mysql

nano 편집기 열기

sudo nano docker-compose.yml

사용할 포트, USERNAME, PASSWORD를 알맞게 수정합니다.

reverse proxy를 사용한다면 로그상에 실제 접속 주소가 아닌 reverse proxy 서버 주소가 남습니다. Reverse Proxy 아래 부분의 주석을 해제하고 서버 주소를 넣으면 http헤더를 읽어 실제 접속 주소가 로그에 남습니다.

guacamole는 http://[ip주소]:[포트 번호]/guacamole로 접속할 수 있습니다. WEBAPP_CONTEXT:를 사용해 접속할 path를 지정할 수 있습니다.
ROOT사용시 http://[ip주소]:[포트 번호]로 접속할 수 있습니다.

docker-compose.yml 저장

사용할 환경에 맞게 수정 후 ctrl + x -> Enter로 저장합니다.

Database 초기 설정

Database에 guacamole를 사용하기 위한 초기 설정을 해주어야합니다.
공식 이미지에 포함된 스크립트를 통해 sql 파일을 생성합니다.

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

현재 디렉토리에initdb.sql파일이 생성 되고, 이를 mysql에 전달 해 데이터베이스 스키마와 초기 데이터를 생성하겠습니다.

mysql 컨테이너 생성

docker-compose up -d mysql

mysql 컨테이너에 초기 데이터 생성

docker-compose exec -T mysql mysql -u'user_guacamole' -p'SOME_USER_PASSWORD' 'db_guacamole' < initdb.sql

Guacamole 접속

준비가 다 끝났으므로 전체 프로젝트를 up하겠습니다.

docker-compose up -d

별 이상이 없다면 http://[ip주소]:[포트 번호]/guacamole로 접속할 수 있습니다.

만약 접속이 안되거나 이상이 있는 경우

로그 확인
docker-compose logs -f

더 자세한 로그가 필요하다면

docker-compose down
guacamole 컨테이너 environment에LOG_LEVEL: debug 추가
docker-compose up 후 docker-compose logs -f
확인한 로그로 구글링 해보기

계정 생성

초기 아이디 / 비밀번호는guacadmin / guacadmin입니다.

로그인 후 우 상단 사용자 모양 -> 세팅에 들어가서 사용자 -> 기본 아이디인 guacadmin을 클릭합니다.

하단의 복제를 클릭하고 사용할 아이디 / 비밀번호를 입력 후 저장하여 새로운 계정을 생성합니다. 로그아웃 하여 새로 생성한 계정으로 로그인 한 뒤 기본계정(guacadmin)을 삭제합니다.

세션 연결하기(Windows RDP)

세팅 -> 연결 -> 새 연결 로 들어갑니다.

프로토콜을 RDP로 설정하고 필요한 설정을 해줍니다.
호스트 이름은 연결 할 PC의 ip, RDP 기본 포트는 3389입니다.
사용자 이름 / 패스워드는 윈도우에서 사용하는 계정 / 비밀번호 입니다.
서버 인증서 무시를 체크하고 저장합니다.

이후 홈의 모든연결에서 연결 해 볼수 있습니다.
Ctrl + Alt + Shift로 간단한 설정창도 열 수 있습니다.

연결하는 PC에서 RDP설정을 건들이지 않더라고 나름 쓸만 하지만
하드웨어 가속 등을 사용하면 훨씬 부드럽게 사용 가능합니다.

세션 연결하기(SSH)

세팅 -> 연결 -> 새 연결

마찬가지로 필요한 설정을 해줍니다.
이전 포스팅에서 설명한 Private / Public Key 방식으로도 연결 가능합니다.

마치며..

Guacamole는 원격접속 게이트웨이로 강력한 오픈소스 프로젝트 입니다.
자체 로그인기능이 있지만 보안을 위해서 외부에 오픈하려면 2FA OTP기능을 활성화 하고 사용할 것을 추천합니다.

Reference:
Apache Guacamole 공식 홈페이지