Guacamole: 원격 통합 관리 도구 설치 및 설정 가이드

 

Apache Guacamole은 HTML5 기반의 클라이언트리스 원격 데스크톱 게이트웨이입니다. 다양한 원격 프로토콜(RDP, VNC, SSH 등)을 지원하며, 웹 브라우저만으로 원격 시스템에 접속할 수 있습니다. 이 가이드에서는 Docker Compose를 활용한 Guacamole 설치부터 Windows PC로 원격 접속, 그리고 Nginx Proxy Manager를 통한 HTTPS 설정까지 다루겠습니다.

 

1. Guacamole 소개

 

1.1 주요 특징

• HTML5 기반 웹 인터페이스로 별도 클라이언트 설치 불필요
• 다양한 원격 프로토콜 지원 (RDP, VNC, SSH)
• 웹 브라우저를 통한 통합 원격 접속 환경 제공
• 크로스 플랫폼 지원 (데스크톱, 모바일)

 

1.2 활용 장점

• 방화벽이나 네트워크 제한으로 일반 RDP 포트가 차단된 환경에서도 웹(HTTP/HTTPS)을 통한 접속 가능
• 중앙화된 원격 접속 관리
• 사용자별 권한 관리 및 접속 이력 관리
• 모든 디바이스에서 동일한 사용자 경험 제공

 

2. 설치 준비

 

2.1 시스템 요구사항

• Docker와 Docker Compose가 설치된 서버
• Portainer가 구성된 Docker 관리 환경
• 적당한 시스템 리소스 (최소 권장: 2CPU, 4GB RAM)

 

2.2 아키텍처 구성요소

• guacd (Guacamole 프록시 데몬)
• PostgreSQL (사용자 및 연결 정보 저장)
• Guacamole 웹 애플리케이션
• Nginx Proxy Manager (HTTPS 프록시)

 

 

 

3. Docker Compose 작성

 

github에 쉽게 사용할 수 있도록 관리중인 저장소가 있습니다.

 

https://github.com/boschkundendienst/guacamole-docker-compose

GitHub - boschkundendienst/guacamole-docker-compose: Guacamole with docker-compose using PostgreSQL, nginx with SSL (self-signed

 

3.1 Docker Compose 파일 준비

 

synology container 설치 가능한 시리즈를 사용할 경우 간편하게 synology에 설치도 가능합니다.

 

# 저장소 clone
git clone https://github.com/boschkundendienst/guacamole-docker-compose.git

# DB 스크립트 생성
cd guacamole-docker-compose
./prepare.sh

 

 

# docker compose yaml 파일 수정

networks:
  guacnetwork_compose:
    driver: bridge

# services
services:
  # guacd
  guacd:
    container_name: guacd_compose
    image: guacamole/guacd
    networks:
      - guacnetwork_compose
    restart: always
    volumes:
    - ./drive:/drive:rw
    - ./record:/record:rw
  # postgres
  postgres:
    container_name: postgres_guacamole_compose
    environment:
      PGDATA: /var/lib/postgresql/data/guacamole
      POSTGRES_DB: guacamole_db
      POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
      POSTGRES_USER: guacamole_user
    image: postgres:15.2-alpine
    networks:
      - guacnetwork_compose
    restart: always
    volumes:
    - ./init:/docker-entrypoint-initdb.d:z
    - ./data:/var/lib/postgresql/data:Z

  # guacamole
  guacamole:
    container_name: guacamole_compose
    depends_on:
    - guacd
    - postgres
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_HOSTNAME: postgres
      POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
      POSTGRES_USER: guacamole_user
    image: guacamole/guacamole
    networks:
      - guacnetwork_compose
    volumes:
      - ./record:/record:rw
    ports:
## enable next line if not using nginx
    - 8080:8080/tcp # Guacamole is on :8080/guacamole, not /.
## enable next line when using nginx
    # - 8080/tcp
    restart: always

########### optional ##############
  # # nginx
  # nginx:
  #  container_name: nginx_guacamole_compose
  #  restart: always
  #  image: nginx:latest
  #  volumes:
  #  - ./nginx/templates:/etc/nginx/templates:ro
  #  - ./nginx/ssl/self.cert:/etc/nginx/ssl/self.cert:ro
  #  - ./nginx/ssl/self-ssl.key:/etc/nginx/ssl/self-ssl.key:ro
  #  ports:
  #  - 8443:443
  #  networks:
  #    - guacnetwork_compose
####################################################################################

 

3.2 컨테이너 실행

docker-compose up -d

 

Portainer를 이용할 경우 stack으로 컨테이너 생성 이후 볼륨 경로로 이동하여 삭제 후 새로 init이 필요할 수 있습니다.

 

 

 

4. Guacamole 연결 구성

4.1 접속 및 계정 비밀번호 변경

http://<서버IP>:8080/guacamole 접속

 

4.2 OTP 설정

환경변수에 TOTP_ENABLED: 'true’ 추가

 

 

컨테이너 재시작 → 로그인 후 QR 코드 를 이용해 authy, google otp 같은 앱으로 2 단계 인증을 설정할 수 있습니다.

 

 

 

4.3 윈도우 PC 연결 구성

윈도우 PC에 원격 연결을 위한 설정이 선행 후 아래 설정

1. 기본 계정으로 로그인 (guacadmin/guacadmin)
2. Settings > Connections > New Connection
3. 연결 설정:
   • Name: 원하는 연결 이름
   • Protocol: RDP
   • Parameters:
     • Network > Hostname: Windows 서버 IP
     • Authentication > Username: Windows 계정
     • Authentication > Password: 계정 비밀번호

인증서 관련 오류가 발생할 경우 서버 인증서 무시 체크 후 접속할 수 있습니다.

 

 

 

브라우저를 통해 윈도우 PC 에 RDP로 접근할 수 있게 됩니다.

 

 

5. HTTPS 보안 설정

5.1 Nginx Proxy Manager 구성

1. Portainer에서 Nginx Proxy Manager 스택 배포
2. Admin UI(http://<서버IP>:81) 접속
3. Proxy Hosts > Add Proxy Host
   • Domain: guacamole.yourdomain.com
   • Scheme: http
   • Forward Hostname: guacamole 컨테이너 IP
   • Forward Port: 8080
   • SSL 설정 활성화 및 Let's Encrypt 인증서 발급

 

 

 

 

마치며

Guacamole은 웹 기반의 통합 원격 관리 도구로서, 특히 네트워크 제약이 있는 환경에서 유용합니다.

Docker Compose를 이용할 경우 간편하게 설치가 가능합니다. Nginx Proxy Manager를 이용해 reverse proxy 설정과 ssl 인증서를 적용하여 https로 외부에서도 안전하고 효율적인 원격 관리 환경을 구축할 수 있습니다. 필요에 따라 다양한 프로토콜과 추가 기능을 활용하여 관리 효율성을 더욱 높일 수 있습니다.