Files

T

dihwang 8d9be8eddd docs: 배포 가이드에 서버 이전 및 환경 준비 섹션 추가

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

2026-04-13 14:41:05 +09:00

5.1 KiB

Raw Blame History

VaultKeeper 배포 가이드

이 문서는 VaultKeeper 애플리케이션을 새로운 서버에 배포하고 설정하는 방법을 안내합니다.

0. 서버 이전 시 파일 전송

프로젝트를 새로운 서버로 이전할 때는 다음 핵심 파일들을 함께 옮겨야 합니다:

main.go: 백엔드 Go 애플리케이션 소스 코드
index.html: 프론트엔드 웹 UI 파일
config.json: 애플리케이션 설정 파일 (htpasswd 경로, 포트 등)
run.sh: 빌드 및 실행을 자동화하는 셸 스크립트

이 파일들을 새로운 서버의 원하는 디렉토리로 복사하십시오. (예: /opt/vaultkeeper/)

1. 서버 환경 준비

VaultKeeper를 실행하기 전에 새로운 서버에 다음 도구들이 설치되어 있는지 확인해야 합니다.

Go 런타임: main.go를 빌드하고 실행하기 위해 필요합니다.
- 설치되어 있지 않다면, 공식 Go 웹사이트를 참조하여 설치하십시오. (예: sudo apt install golang 또는 sudo yum install golang)
htpasswd 도구: Apache HTTP Server Utils 패키지에 포함되어 있으며, .htpasswd 파일을 관리하는 데 사용됩니다.
- Debian/Ubuntu: sudo apt install apache2-utils
- CentOS/RHEL: sudo yum install httpd-tools

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 파일 준비가 완료되면, run.sh 스크립트를 사용하여 VaultKeeper를 쉽게 빌드하고 실행할 수 있습니다.

먼저, run.sh 파일에 실행 권한을 부여합니다:

chmod +x run.sh

그 다음, 다음 명령어를 실행하여 VaultKeeper를 시작합니다:

./run.sh

run.sh 스크립트는 Go 바이너리를 빌드하고 실행합니다. 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가 사용자 이름과 비밀번호를 요청할 것입니다.

5.1 KiB Raw Blame History