본문으로 건너뛰기

Guacamole 대작전 - PostgreSQL & Docker

등록일: 2026-05-04 ​

본 문서는 MariaDB 기반의 Guacamole을 PostgreSQL 18로 전환하고, Docker 환경에서의 권한 및 로케일 문제를 해결하는 정공법을 기술함.

1. PostgreSQL 18 Docker 설정 (Serverzz 전용)​

PostgreSQL 18 버전은 데이터 저장 구조가 변경되었으며, 한국어 로케일(ko_KR.UTF-8)을 지원하기 위해 컨테이너 기동 시 추가 작업이 필요함. 특히 apt-get 작업 후 발생하는 파일 권한 문제를 해결하기 위해 chown 명령어를 반드시 포함해야 함.

docker-compose.yml​

services:
  postgres:
    image: postgres:18
    container_name: postgres
    restart: unless-stopped
    command: >
      bash -c "apt-get update && apt-get install -y locales 
      && sed -i 's/^# ko_KR.UTF-8 UTF-8/ko_KR.UTF-8 UTF-8/' /etc/locale.gen 
      && locale-gen 
      && chown -R 999:999 /var/lib/postgresql 
      && exec docker-entrypoint.sh postgres"
    environment:
      - POSTGRES_USER=sleepzz
      - POSTGRES_PASSWORD="PASSWORD_HERE"
      - TZ=Asia/Seoul
      - LANG=ko_KR.UTF-8
      - LC_ALL=ko_KR.UTF-8
    volumes:
      - /shared/data001/postgres:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - serverzz-net

networks:
  serverzz-net:
    name: serverzz-net
    external: true

2. DB 초기화 및 스키마 준비​

Guacamole은 DB 엔진 전환 시 초기 스키마(Table 구조)를 수동으로 삽입해야 함.

2.1 스키마 추출 (initdb.sql)​

# --postgresql 옵션을 사용하여 SQL 파일 추출
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql

2.2 DB 생성 및 스키마 주입​

# 1. Guacamole 전용 DB 생성 (관리자 유저 사용)
docker exec -it postgres createdb -U sleepzz dbguacp1

# 2. 추출한 SQL 파일을 해당 DB에 주입
cat initdb.sql | docker exec -i postgres psql -U sleepzz -d dbguacp1

3. Guacamole 서비스 구성​

2026년 5월 4일 기준, Guacamole Docker 환경에서 PostgreSQL 연동 시 문서상 예시처럼 POSTGRES_ 접두사를 사용하면 연결이 되지 않았고, 실제 동작한 값은 POSTGRESQL_ 접두사였음. 따라서 아래처럼 POSTGRESQL_HOSTNAME, POSTGRESQL_PORT, POSTGRESQL_DATABASE, POSTGRESQL_USER, POSTGRESQL_PASSWORD 형식으로 설정해야 함.

guacamole.env​

# GUACAMOLE_HOME=/config

# PostgreSQL Database info
POSTGRESQL_HOSTNAME=postgres
POSTGRESQL_PORT=5432
POSTGRESQL_DATABASE=dbguacp1
POSTGRESQL_USER=guac_app
POSTGRESQL_PASSWORD="PASSWORD_HERE"

# guacd info
GUACD_HOSTNAME=guacd

비밀번호에 특수문자가 들어가는 경우 실제 .env 값은 반드시 큰따옴표로 감싸서 넣는 것을 권장함.

docker-compose.yml (Guacamole)​

services:
  guacd:
    image: guacamole/guacd
    container_name: guacd
    restart: unless-stopped
    networks:
      - serverzz-net

  guacamole:
    image: guacamole/guacamole
    container_name: guacamole
    restart: unless-stopped
    env_file:
      - ./guacamole.env
    ports:
      - "8081:8080"
    volumes:
      - /data001/guacamole/config:/config
    networks:
      - serverzz-net
    depends_on:
      - guacd

networks:
  serverzz-net:
    name: serverzz-net
    external: true

4. 트러블슈팅​

  • 권한 거부 (Permission Denied): global/pg_filenode.map 등의 에러 발생 시, 호스트에서 sudo chown -R 999:999 /shared/data001/postgres를 실행하거나 Postgres 컴포즈의 command 섹션에 chown 명령어가 포함되어 있는지 확인함.
  • 로케일 에러: 복구 시 ko_KR.UTF-8 관련 에러가 발생하면 컨테이너 내부에서 locale -a를 실행하여 한국어 팩이 생성되었는지 확인 필요함.
  • 비밀번호 특수문자: 환경변수 값에 ) 등이 포함될 경우 반드시 큰따옴표(" ")로 감싸야 함.
  • PostgreSQL 환경변수명 주의: 2026년 5월 4일 기준 실제 동작 확인 결과, 공식 문서에서 본 POSTGRES_ 계열 대신 POSTGRESQL_ 계열로 맞춰야 Guacamole 컨테이너가 PostgreSQL 설정을 정상 인식했음. 연결이 안 되면 .env 파일의 접두사를 가장 먼저 점검하면 됨.