Files

T

dihwang a72a30ce3b chore: 리눅스 서버용 htpasswd 경로 및 배포 문서 조정

Co-authored-by: aider (gemini/gemini-2.5-flash) <aider@aider.chat>

2026-04-13 14:14:46 +09:00

4.0 KiB

Raw Blame History

VaultKeeper 배포 가이드

이 문서는 VaultKeeper 애플리케이션의 빌드, 초기 설정 및 Nginx 연동 방법을 안내합니다.

1. 백엔드 빌드

Go 바이너리를 가볍게 빌드하려면 다음 명령어를 사용합니다. 이 명령어는 디버그 정보를 제거하고 심볼 테이블을 생략하여 최종 바이너리 크기를 줄입니다.

go build -o vaultkeeper -ldflags "-s -w" main.go

빌드가 완료되면 현재 디렉토리에 vaultkeeper 실행 파일이 생성됩니다.

2. VaultKeeper 설정 파일 (`config.json`) 생성 및 설정

VaultKeeper는 config.json 파일을 통해 .htpasswd 파일 경로와 서버 포트를 설정합니다. 애플리케이션을 실행하기 전에 이 파일을 생성하고 내용을 채워야 합니다.

프로젝트 루트 디렉토리에 config.json 파일을 다음 내용으로 생성합니다.

{
  "htpasswdPath": "/etc/nginx/.htpasswd",
  "port": 8000
}

"htpasswdPath": Nginx가 사용하는 실제 .htpasswd 파일의 절대 경로를 지정합니다. VaultKeeper가 이 파일에 대한 읽기/쓰기 권한을 가지고 있어야 합니다.
"port": VaultKeeper 서버가 수신 대기할 포트 번호를 지정합니다. (기본값: 8000)

3. 최초 관리자 계정 생성 (터미널)

VaultKeeper는 자체 로그인 로직을 포함하지 않으며, Nginx auth_basic 모듈에 인증을 위임합니다. 웹 UI에 접근하려면 Nginx를 통해 인증할 수 있는 계정이 필요합니다. 최초 관리자 계정은 VaultKeeper가 실행되기 전에 터미널에서 htpasswd 명령어를 사용하여 생성해야 합니다.

.htpasswd 파일이 아직 없는 경우:

htpasswd -c /etc/nginx/.htpasswd adminuser

adminuser를 원하는 관리자 사용자 이름으로 바꾸세요. 이 명령어는 /etc/nginx/.htpasswd 파일을 생성하고 adminuser를 추가합니다.

.htpasswd 파일이 이미 있는 경우 (새 사용자를 추가하거나 기존 사용자의 비밀번호를 변경):

htpasswd /etc/nginx/.htpasswd anotheruser

-c 옵션을 사용하면 기존 파일이 덮어쓰여지므로 절대 이미 존재하는 파일에 -c 옵션을 다시 사용하지 마세요.

4. VaultKeeper 실행

config.json 파일 생성 및 .htpasswd 파일 준비가 완료되면, 빌드된 VaultKeeper 바이너리를 실행합니다.

./vaultkeeper

VaultKeeper는 config.json에 설정된 포트에서 수신 대기합니다 (기본값: 8000번 포트).

5. Nginx 설정 예시

Nginx의 auth_basic 모듈 뒤에서 VaultKeeper를 실행하여 접근을 제한할 수 있습니다. 다음은 Nginx 설정 파일 (/etc/nginx/nginx.conf 또는 conf.d 내부 파일)에 추가할 수 있는 location 블록 예시입니다.

이 설정은 /vaultkeeper/ 경로로 들어오는 요청을 VaultKeeper 백엔드(8000번 포트)로 프록시하고, auth_basic을 통해 .htpasswd 파일로 인증을 요구합니다.

server {
    listen 80;
    server_name your_domain.com; # 도메인 또는 IP 주소로 변경

    location /vaultkeeper/ {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd; # .htpasswd 파일 경로를 정확히 지정

        proxy_pass http://127.0.0.1:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }

    # 다른 Nginx 설정...
}

Nginx 설정을 변경한 후에는 반드시 Nginx를 재로드하거나 재시작하여 변경사항을 적용해야 합니다.

sudo nginx -t # 설정 파일 유효성 검사
sudo systemctl reload nginx # Nginx 재로드

이제 http://your_domain.com/vaultkeeper/ (또는 http://your_server_ip/vaultkeeper/)로 접근하여 VaultKeeper 웹 UI를 사용할 수 있습니다. 접근 시 Nginx가 사용자 이름과 비밀번호를 요청할 것입니다.

4.0 KiB Raw Blame History