(부록) Hostinger VPS 컨테이너에서 gws 인증하기

영상이 재생되지 않으면 여기서 영상을 내려받아 보세요.

gws auth login은 브라우저로 구글 로그인 창을 열고, 인증이 끝나면 http://localhost:포트 라는 주소로 결과를 돌려받는 방식입니다. 내 노트북에서 쓸 때는 자연스럽게 동작하지만, Hostinger VPS의 도커 컨테이너처럼 화면 없는 서버에서는 이 마지막 단계가 막힙니다. 브라우저는 내 노트북에 있고, 결과를 받을 주소(localhost)는 컨테이너 안에 있어서 서로 만나지 못하거든요.

이 부록은 그 마지막 한 칸을 메우는 방법입니다. 결론부터 말하면, 인증 코드를 컨테이너 안에서 직접 전달해 주면 깔끔하게 끝납니다. 위 영상이 전체 과정을 1분 안에 보여주니 먼저 한 번 보시고, 아래 단계를 따라오시면 됩니다.

💡 사전 요구사항: 헤르메스 구글 워크스페이스 연결 가이드에서 gws 설치와 gws auth setup(구글 클라우드 OAuth 클라이언트 등록)을 먼저 끝내 두셔야 합니다. 이 부록은 그다음 단계인 "로그인 인증"만 다룹니다.

왜 막히는지 1분 이해

gws auth login을 실행하면 컨테이너 안에 http://localhost:포트 주소로 응답을 기다리는 작은 콜백 서버가 잠깐 켜집니다. 구글에서 동의를 마치면 브라우저가 그 주소로 이동하면서 인증 코드를 전달하죠.

문제는 그 localhost가 브라우저가 떠 있는 내 노트북을 가리킨다는 점입니다. 노트북에는 그 주소로 받을 서버가 없으니 "접속할 수 없음" 화면이 뜹니다. 하지만 정작 진짜 콜백 서버는 컨테이너 안에서 멀쩡히 코드를 기다리고 있어요. 그래서 그 코드만 컨테이너 안으로 넣어 주면 인증이 완료됩니다.

준비. 컨테이너 터미널 2개 열기 (브라우저 하나로 충분)

SSH 클라이언트를 따로 깔 필요 없이, Hostinger 관리자(hPanel)의 웹 터미널만으로 끝낼 수 있습니다.

hPanel에 로그인한 뒤 도커 매니저로 들어가, 헤르메스 프로젝트(hermes-agent-...) 줄에서 터미널을 클릭합니다.

새 탭에 웹 터미널이 열리고, 곧바로 컨테이너 안으로 들어갑니다. 프롬프트가 root@...:/opt/hermes# 처럼 보이면 컨테이너 내부에 들어온 것입니다.

이 과정에서 핵심은 터미널을 2개 준비하는 것입니다. 같은 방법으로 터미널을 하나 더 열어 탭 2개로 두거나, 영상처럼 화면을 좌우로 분할하세요. 둘 다 같은 컨테이너 안이라 어느 쪽이든 상관없습니다. 왼쪽(터미널 A)은 로그인용, 오른쪽(터미널 B)은 코드 전달용으로 씁니다.

## 1단계. 터미널 A에서 로그인 시작

왼쪽 터미널에서 아래 명령을 실행합니다.

gws auth login

https://accounts.google.com/... 로 시작하는 긴 주소가 출력되고, 그 자리에서 멈춰 콜백을 기다립니다. 이 창은 닫지 말고 그대로 두세요. 출력된 주소를 복사합니다.

> 💡 출력된 주소 안에 redirect_uri=http://localhost:포트번호 가 들어 있습니다. 이 포트 번호는 실행할 때마다 바뀌며, 잠시 뒤 "접속 안 됨" 화면에서 다시 만나게 됩니다.

2단계. 브라우저에서 동의하기

복사한 주소를 브라우저 새 탭에서 엽니다. 구글 계정을 고르고 계속을 누릅니다.

이때 "Google에서 확인하지 않은 앱"이라는 경고 화면이 나올 수 있습니다. 놀라지 마세요. 내가 직접 만든 OAuth 클라이언트가 아직 테스트(게시 전) 상태라서 뜨는 정상 안내입니다. 왼쪽 아래 고급을 누르고, 이어 나오는 (내 앱 이름)(으)로 이동(안전하지 않음) 을 클릭해 진행합니다.

마지막으로 권한 동의 화면입니다. 모두 선택에 체크하고 계속을 누릅니다. 여기서 항목을 빠뜨리면 나중에 해당 기능이 동작하지 않으니, 헤르메스가 요청한 항목은 모두 허용해 주세요.

## 3단계. "접속할 수 없음" 주소 복사하기

동의를 마치면 브라우저가 localhost:포트 주소로 이동하면서 "이 사이트에 연결할 수 없음" 같은 화면이 뜹니다. 앞서 설명한 그대로이니 정상입니다.

여기서 할 일은 딱 하나, 주소창의 전체 주소를 복사하는 것입니다. 주소창에서 우클릭하고 복사를 누르세요. 이 주소 안에 우리가 컨테이너로 넘겨줄 인증 코드(code=...)가 들어 있습니다.

## 4단계. 터미널 B에서 코드 전달 (콜백 완료)

이제 오른쪽 터미널에서 curl 뒤에 따옴표를 열고, 방금 복사한 주소를 그대로 붙여넣은 다음 따옴표를 닫아 실행합니다.

curl "여기에_복사한_localhost_주소를_그대로_붙여넣기"

Success ... You may now close this window. 라는 응답이 나오면 코드가 컨테이너 안 콜백 서버에 잘 전달된 것입니다. 그 순간 왼쪽 터미널 A의 gws auth login이 자동으로 완료되면서 아래처럼 마무리됩니다.

"message": "Authentication successful. Encrypted credentials saved.",
"status": "success"

## 확인

아무 터미널에서나 상태를 확인합니다.

gws auth status

연결된 계정과 권한 목록이 보이면 끝입니다. 이제 헤르메스가 Gmail, Calendar, Drive 같은 구글 워크스페이스를 직접 다룰 수 있습니다.

한 번만 하면 됩니다

발급된 자격증명은 컨테이너의 /opt/data/.config/gws/ 안에 암호화되어 저장됩니다. 이 폴더는 컨테이너가 재시작되거나 업데이트돼도 유지되는 영속 볼륨이라, 한 번 인증해 두면 다시 로그인하지 않아도 됩니다.

자주 만나는 문제

포트 번호가 영상과 다릅니다.정상입니다. localhost:포트의 포트는 실행할 때마다 바뀝니다. 그때 화면에 찍힌 주소를 그대로 복사해서 쓰면 됩니다.

왼쪽 터미널을 닫아 버렸어요.콜백을 받을 서버가 함께 사라집니다. 1단계의 gws auth login부터 다시 시작하세요.

"확인하지 않은 앱" 경고가 불안합니다.내가 직접 만든 OAuth 클라이언트라 안전합니다. 앱이 아직 테스트 상태라 구글이 띄우는 일반 안내이며, 고급을 눌러 진행하면 됩니다.

curl 했더니 코드가 만료됐다거나 오류가 납니다.인증 코드는 한 번만 쓸 수 있고 유효 시간도 짧습니다. 동의 후 너무 오래 지났다면 1단계부터 다시 진행하세요. 같은 주소로 curl을 두 번 실행해도 두 번째는 실패합니다.

keyring 관련 오류가 납니다.화면 없는 서버에서 OS 키링을 못 쓰는 경우입니다. GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 을 설정한 뒤 다시 gws auth login 을 실행하면 파일로 자격증명을 저장합니다.

한눈에 보는 순서

마무리

화면 없는 서버에서 막히던 구글 로그인을, 브라우저 하나와 터미널 두 개로 깔끔하게 넘겼습니다. 이 방식은 gws뿐 아니라 localhost 콜백을 쓰는 다른 CLI 인증에도 똑같이 응용할 수 있습니다. 이제 본 가이드로 돌아가 Sophie에게 구글 워크스페이스 업무를 맡겨 보세요.