설치 가이드

서버에 Alpacon 에이전트(Alpamon)를 설치하고 워크스페이스에 연결하는 방법을 알아봅니다.

사전 요구사항

Alpacon을 설치하기 전에 다음을 확인하세요:

  • Alpacon 워크스페이스: 없다면 alpacon.io에서 가입하세요
  • 서버 요구사항:
    • 지원되는 OS (지원 플랫폼 참조)
    • 설치를 위한 root 또는 sudo 접근 권한
    • 아웃바운드 HTTPS 연결 (포트 443)
    • 150MB 여유 디스크 공간
    • 128MB 사용 가능한 RAM

지원 플랫폼

Linux 배포판 (공식 지원)

  • Ubuntu: 18.04, 20.04, 22.04, 24.04 LTS
  • Debian: 10 (Buster), 11 (Bullseye), 12 (Bookworm)
  • RHEL: 7, 8, 9
  • CentOS: 7, 8 Stream, 9 Stream
  • Rocky Linux: 8, 9
  • Alma Linux: 8, 9
  • Oracle Linux: 7, 8, 9
  • Fedora: 36, 37, 38, 39
  • Amazon Linux: 2, 2023
  • SUSE Linux Enterprise: 12, 15
  • Alpine Linux: 3.14+
  • Raspberry Pi OS: 최신 버전

개발 환경 전용

  • macOS: 11 (Big Sur) 이상 - 개발 및 테스트 목적으로만 사용
    • 프로덕션 사용 권장하지 않음
    • Apple Silicon (M1/M2/M3) 및 Intel 지원

곧 출시 예정

  • Windows: Windows Server 지원 계획 중
  • 컨테이너 환경: Docker, Kubernetes 지원 개발 중

빠른 설치

Alpamon을 설치하고 등록하는 권장 방법:

1단계: 워크스페이스에서 서버 등록 준비

  1. Alpacon 워크스페이스에 로그인
  2. Servers → Connect Server로 이동
  3. 서버 세부 정보 입력:
    • Name: 서버 식별자 (예: production-web-01)
    • Platform: OS 선택 (Ubuntu, RHEL, CentOS 등)
    • User Groups (선택사항): 이 서버에 접근할 수 있는 그룹
  4. Save 클릭

2단계: 생성된 스크립트로 설치

워크스페이스에서 생성된 설치 스크립트를 복사하여 서버에서 실행:

# 스크립트는 다음과 유사한 형태입니다:
curl https://your-workspace.us1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -E bash

이 스크립트는 다음을 수행합니다:

  1. OS와 아키텍처를 감지
  2. 적절한 Alpamon 패키지 다운로드 (~120MB)
  3. 에이전트를 설치하고 구성
  4. 워크스페이스에 서버를 자동으로 등록
  5. Alpamon 서비스 시작

참고: -E 플래그는 환경 변수를 유지합니다 (프록시 구성에 유용)

3단계: 설치 확인

워크스페이스에서 서버 목록에 서버가 Connected 상태로 표시되는지 확인합니다. 이제 터미널을 통해 접근할 수 있습니다.

수동 설치 (고급)

참고: 대부분의 사용자에게는 워크스페이스 생성 설치 스크립트 사용을 권장합니다 (빠른 설치 참조). 수동 설치 시 별도 등록이 필요합니다.

모든 Alpamon 패키지는 packagecloud.io에서 호스팅됩니다.

방법 1: 레포지토리 설치 (권장)

이 방법을 사용하면 시스템 패키지 관리자를 통한 자동 업데이트가 가능합니다.

1단계: Alpacon에서 환경변수 가져오기

설치 전에 Alpacon 워크스페이스에서 등록 자격 증명을 가져와야 합니다.

방법 A: Alpacon 웹 UI 사용

  1. Alpacon 워크스페이스에 로그인
  2. Servers → Connect Server로 이동
  3. 새 서버 항목 생성
  4. 설치 안내에서 환경변수 복사: ALPACON_URL, PLUGIN_ID, PLUGIN_KEY

방법 B: Alpacon CLI 사용

# CLI로 서버 생성 (대화형 프롬프트)
alpacon server create
 
# 생성 후 환경변수가 포함된 설치 안내가 표시됩니다
# ALPACON_URL, PLUGIN_ID, PLUGIN_KEY 값을 복사하세요

2단계: 환경변수 설정

대상 서버에서 자격 증명을 export:

export ALPACON_URL="https://your-workspace.us1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

중요: export를 사용하여 설치 중에 이러한 변수를 사용할 수 있도록 해야 합니다. sudo -E의 -E 플래그는 환경변수를 보존합니다.

3단계: Alpamon 설치

DEB 기반 시스템 (Ubuntu/Debian):

# 레포지토리 및 GPG 키 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.deb.sh | sudo -E bash
 
# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -E apt-get install alpamon
 
# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM 기반 시스템 (RHEL/CentOS/Rocky/Alma/Fedora):

# 레포지토리 추가 (환경변수 보존)
curl -s https://packagecloud.io/install/repositories/alpacax/alpamon/script.rpm.sh | sudo -E bash
 
# Alpamon 설치 (환경변수를 사용하여 자동 등록)
sudo -E yum install alpamon
 
# 서비스 시작 및 활성화
sudo systemctl start alpamon
sudo systemctl enable alpamon

방법 2: 직접 패키지 다운로드

특정 패키지 버전을 직접 다운로드하여 설치합니다. 이 방법도 자동 등록을 위해 환경변수가 필요합니다.

1단계: 환경변수 가져오기 및 설정

방법 1과 동일한 단계로 ALPACON_URL, PLUGIN_ID, PLUGIN_KEY를 가져와서 export합니다.

export ALPACON_URL="https://your-workspace.us1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

2단계: 다운로드 및 설치

DEB 기반 시스템 (Ubuntu/Debian):

# 최신 패키지 다운로드
wget https://packagecloud.io/alpacax/alpamon/packages/ubuntu/focal/alpamon_amd64.deb/download.deb?distro_version_id=210 -O alpamon_amd64.deb
 
# 패키지 설치 (환경변수 보존)
sudo -E dpkg -i alpamon_amd64.deb
 
# 누락된 종속성 설치
sudo apt-get install -f
 
# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon

RPM 기반 시스템 (RHEL/CentOS/Rocky/Alma/Fedora):

# 최신 패키지 다운로드
wget https://packagecloud.io/alpacax/alpamon/packages/el/8/alpamon-x86_64.rpm/download.rpm -O alpamon.x86_64.rpm
 
# 패키지 설치 (환경변수 보존)
sudo -E rpm -i alpamon.x86_64.rpm
 
# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon

모든 패키지 찾아보기: packagecloud.io/alpacax/alpamon에서 다양한 OS 버전 및 아키텍처에 대한 모든 사용 가능한 패키지를 확인하세요.

참고: 설치 중에 환경변수가 올바르게 설정되면 에이전트가 자동으로 등록됩니다. 그렇지 않으면 수동 등록을 진행하세요.

고급: 수동 등록

Alpamon을 수동으로 설치한 경우 (워크스페이스 생성 설치 스크립트 없이), 별도로 등록할 수 있습니다:

등록 정보 받기

  1. Alpacon 워크스페이스에 로그인
  2. Servers → Connect Server로 이동
  3. 서버 항목을 생성하고 등록 세부 정보를 기록

서버 등록

서버에서 등록 명령 실행:

sudo alpamon register \
  --workspace https://alpacon.io/your-workspace/ \
  --token YOUR_REGISTRATION_TOKEN \
  --name "production-web-01"

옵션:

  • --workspace: 워크스페이스 URL
  • --token: 워크스페이스의 등록 토큰
  • --name: 서버의 친숙한 이름 (선택사항)
  • --groups: 쉼표로 구분된 그룹 목록 (선택사항)

등록 확인

에이전트 상태 확인:

# 서비스 상태 확인
sudo systemctl status alpamon
 
# 에이전트 로그 확인
sudo journalctl -u alpamon -f

워크스페이스에서:

  1. Servers 페이지로 이동
  2. 서버가 “Connected”로 표시되어야 함
  3. 서버를 클릭하여 터미널에 접근

구성

구성 파일

주요 구성 파일 위치:

  • Linux: /etc/alpamon/config.yaml
  • Windows: C:\ProgramData\Alpamon\config.yaml
  • macOS: /usr/local/etc/alpamon/config.yaml

예제 구성:

# 워크스페이스 구성
workspace:
  url: https://alpacon.io/your-workspace/
  token: your-registration-token
 
# 에이전트 설정
agent:
  name: production-web-01
  groups:
    - webservers
    - production
  labels:
    environment: production
    region: us-east-1
    team: platform
 
# 네트워크 설정
network:
  proxy: http://proxy.example.com:8080
  timeout: 30s
  retry_interval: 10s
 
# 로깅
logging:
  level: info  # debug, info, warn, error
  file: /var/log/alpamon/agent.log
  max_size: 100MB
  max_backups: 5
 
# 보안
security:
  allowed_users:
    - root
    - ubuntu
    - admin
  command_logging: true
  session_recording: false

환경 변수

환경 변수를 사용하여 Alpamon을 구성할 수도 있습니다:

export ALPAMON_WORKSPACE_URL="https://alpacon.io/your-workspace/"
export ALPAMON_TOKEN="your-registration-token"
export ALPAMON_PROXY="http://proxy.example.com:8080"
export ALPAMON_LOG_LEVEL="debug"

프록시 구성

서버가 프록시 뒤에 있는 경우:

# 등록 시 프록시 설정
sudo alpacon agent register \
  --token YOUR_TOKEN \
  --workspace YOUR_WORKSPACE \
  --proxy http://proxy.example.com:8080
 
# 또는 구성 파일에서
network:
  proxy: http://proxy.example.com:8080
  no_proxy: localhost,127.0.0.1,internal.domain

제거

Linux 서버에서 Alpamon을 제거하려면:

# 서비스 중지
sudo systemctl stop alpamon
 
# 패키지 제거 (Debian/Ubuntu)
sudo apt-get remove --purge alpamon
 
# 패키지 제거 (RHEL/CentOS/Rocky/Alma)
sudo yum remove alpamon
 
# 구성 및 데이터 제거
sudo rm -rf /etc/alpamon
sudo rm -rf /var/lib/alpamon
sudo rm -rf /var/log/alpamon

제거 후 워크스페이스에서 서버를 삭제합니다:

  1. 워크스페이스의 Servers로 이동
  2. 서버 선택
  3. Delete 클릭

문제 해결

에이전트가 시작되지 않음

서비스 상태와 로그 확인:

# 서비스 상태 확인
sudo systemctl status alpamon
 
# 로그 보기
sudo journalctl -u alpamon -n 50
 
# 로그 파일 확인
sudo tail -f /var/log/alpamon/agent.log

등록 실패

일반적인 문제:

  • 잘못된 토큰: 워크스페이스에서 토큰 재생성
  • 네트워크 오류: 방화벽/프록시 설정 확인
  • DNS 문제: alpacon.io를 확인할 수 있는지 검증
  • 시간 동기화: 시스템 시간이 정확한지 확인

연결 문제

연결 테스트:

# HTTPS 연결 테스트
curl -v https://alpacon.io
 
# 프록시로 테스트
curl -v -x http://proxy:8080 https://alpacon.io
 
# DNS 확인
nslookup alpacon.io
dig alpacon.io
 
# 방화벽 확인
sudo iptables -L -n | grep 443

성능 문제

Alpamon 성능 최적화:

# /etc/alpamon/config.yaml에서 조정
performance:
  max_sessions: 10
  buffer_size: 65536
  keepalive_interval: 30s
  compression: true

다음 단계

성공적인 설치 후:

  1. 액세스 제어 구성 - 역할 및 권한 설정
  2. Websh를 통한 연결 - 브라우저를 통해 서버에 접근
  3. 모니터링 설정 - 알림 및 대시보드 구성
  4. CI/CD와 통합 - 배포 자동화

도움이 필요하신가요?