Supabase Docker 설정에서 pgsodium 권한 오류 해결하기
Supabase Docker 설정에서 pgsodium 권한 오류 해결하기
Supabase를 Docker로 자체 호스팅하면서 다음과 같은 오류 메시지를 만난 적이 있나요?
cat: /etc/postgresql-custom/pgsodium_root.key: Permission denied
FATAL: invalid secret key
이 글에서는 이 문제가 발생하는 원인과 해결 방법, 그리고 이러한 설정이 Supabase에서 어떤 역할을 하는지 자세히 알아보겠습니다.
목차
문제 상황
Supabase Docker 환경을 구성하거나 업데이트할 때, 다음과 같은 오류가 발생할 수 있습니다:
dependency failed to start: container supabase-db is unhealthy
cat: /etc/postgresql-custom/pgsodium_root.key: Permission denied
FATAL: invalid secret key
이 오류는 주로 Supabase의 데이터베이스 컨테이너가 pgsodium_root.key 파일에 접근할 수 없을 때 발생합니다. 이 파일은 PostgreSQL의 암호화 확장인 pgsodium이 사용하는 키 파일입니다.
내 Docker Compose 설정은 다음과 같았습니다:
# ... 다른 설정들 ...
db:
image: supabase/postgres:15.6.1.146
# ... 다른 설정들 ...
volumes:
# ... 다른 볼륨 설정들 ...
- db-config:/etc/postgresql-custom
# ... 다른 서비스들 ...
volumes:
db-config:
해결 방법
GitHub 이슈(#30834)에서 찾은 해결책은 매우 간단했습니다. Docker Compose 파일에서 pgsodium 관련 볼륨 마운트를 제거하는 것입니다:
Docker Compose 다시 시작:
docker compose down
docker compose up -d
기존에 생성된 볼륨이 있다면 삭제:
docker volume rm supabase_db-config
파일 하단의 volumes 정의에서도 관련 볼륨을 제거:
volumes:
db-config: # 이 줄을 주석 처리하거나 제거
db 서비스의 volumes 섹션에서 다음 줄을 주석 처리하거나 제거:
- db-config:/etc/postgresql-custom
이 간단한 변경으로 Supabase가 정상적으로 시작되었습니다!
pgsodium이란 무엇인가?
이 문제를 이해하기 위해서는 먼저 pgsodium이 무엇인지 알아야 합니다.
pgsodium은 PostgreSQL을 위한 현대적인 암호화 도구로, libsodium 라이브러리를 기반으로 합니다. 이 확장 기능은 다음과 같은 기능을 제공합니다:
- 데이터 암호화: 민감한 데이터를 안전하게 저장할 수 있게 해줍니다.
- 키 관리: 암호화 키를 안전하게 관리합니다.
- 서명 및 검증: 데이터의 무결성을 검증할 수 있습니다.
- 암호학적 해싱: 안전한 해시 함수를 제공합니다.
Supabase에서는 주로 Vault 기능(암호화된 열 관리)을 구현하는 데 pgsodium을 사용합니다.
왜 이 해결책이 작동하는가?
이 문제는 주로 권한(Permission) 문제에서 발생합니다. 해결 방법이 작동하는 이유를 분석해보면:
- 볼륨 마운트 제거:
/etc/postgresql-custom경로로의 볼륨 마운트를 제거함으로써, PostgreSQL은 내부적으로 기본 위치에 자체 키를 생성하게 됩니다. - 권한 문제 우회: Docker 볼륨의 권한 문제(일반적으로 소유자와 권한 설정 관련)를 우회합니다.
- 자동 키 생성: pgsodium 확장은 필요한 키 파일이 없을 경우, 자동으로 새 키를 생성합니다.
이 솔루션이 작동하는 이유는 기존의 손상된 또는 접근할 수 없는 볼륨 대신, PostgreSQL이 자체적으로 관리하는 경로에 새로운 키를 생성하도록 유도하기 때문입니다.
대안적 해결 방법들
GitHub 이슈에서 논의된 몇 가지 다른 해결 방법도 있습니다:
전체 재설정 방법:
docker compose down
sudo rm -rf volumes/db/data
docker volume rm supabase_db-config
docker compose up -d
이 방법은 모든 데이터를 삭제하고 처음부터 다시 시작합니다. 프로덕션 환경에서는 권장되지 않습니다.
권한 수정 방법:
chmod 0644 /var/lib/docker/volumes/[volume-name]_supabase-db-config/_data/pgsodium_root.key
이 방법은 볼륨을 유지하면서 키 파일의 권한만 수정합니다. 데이터 손실 없이 문제를 해결할 수 있습니다.
결론 및 교훈
이 문제를 해결하면서 배운 몇 가지 중요한 교훈이 있습니다:
- Docker 볼륨 권한 이해하기: Docker 볼륨의 권한 설정은 컨테이너의 정상 작동에 중요한 요소입니다.
- 암호화 확장 기능의 중요성: pgsodium과 같은 암호화 확장은 보안에 중요하지만, 적절히 구성되어야 합니다.
- 최소 변경의 원칙: 문제 해결 시 가능한 한 최소한의 변경으로 시작하는 것이 좋습니다. 이 경우, 전체 데이터를 삭제하는 대신 볼륨 마운트만 제거하는 것으로 충분했습니다.
- 커뮤니티 활용하기: GitHub 이슈와 같은 커뮤니티 리소스는 문제 해결에 큰 도움이 됩니다.
pgsodium 관련 볼륨을 제거한 후에도 Supabase의 기본 기능은 정상적으로 작동합니다. 다만, 암호화된 열(Encrypted Columns)이나 Vault 기능을 사용하려는 경우에는 추가 설정이 필요할 수 있습니다.
이 해결책은 개발 환경이나 암호화 기능이 필요 없는 경우에 적합합니다. 프로덕션 환경에서 암호화 기능이 필요하다면, 볼륨 권한을 올바르게 설정하는 방법을 고려해보세요.