설치 가이드

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

사전 요구사항

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

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

지원 플랫폼

Alpamon은 Linux, macOS, Windows에 대한 공식 빌드를 제공합니다.

플랫폼별 기능 범위

Linux와 macOS는 사용자/그룹 관리, Unix 권한 변경(chmod / chown)을 포함한 Alpacon의 모든 기능을 사용할 수 있습니다. Windows 서버는 **터미널 세션(Websh)**과 **파일 전송(WebFTP)**을 지원하며, 사용자/그룹 관리와 Unix 권한 제어는 적용되지 않으므로 해당 UI가 비활성화됩니다.

곧 출시 예정

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

빠른 설치

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

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

1. Alpacon 워크스페이스에 로그인
2. Servers → 서버 등록으로 이동한 뒤 토큰으로 등록 선택
3. Platform을 선택하고, 필요하면 서버 이름을 지정한 다음 등록 토큰을 선택합니다. 접근 그룹은 이 양식에서 설정하지 않고 토큰에서 상속됩니다.

전체 등록 절차(Ansible 포함)는 서버 등록하기를 참고하세요.

2단계: 생성된 명령으로 설치

워크스페이스에서 생성된 명령을 복사하여 서버에서 실행합니다. 워크스페이스는 선택한 플랫폼에 맞춰 명령을 자동 생성합니다.

Linux / macOS: 터미널에 붙여넣기:

# The command will look similar to this:
curl https://your-workspace.ap1.alpacon.io/api/servers/installers/YOUR_UNIQUE_ID/ | sudo -EH bash

Windows: 관리자 권한 PowerShell(관리자 권한으로 실행)에 붙여넣습니다. 생성된 명령은 GitHub Releases에서 에이전트를 내려받고 체크섬을 검증한 뒤 alpamon.exe register를 실행합니다. 동일한 수동 단계는 Windows를 참고하세요.

명령은 어느 경우든 다음을 수행합니다:

1. Alpamon 에이전트 설치
2. 워크스페이스에 서버 등록
3. 에이전트를 서비스로 시작

참고: Linux와 macOS에서 sudo -EH는 환경 변수(예: 프록시 설정)를 유지하고 설치 과정의 HOME을 설정합니다.

3단계: 설치 확인

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

수동 설치 (고급)

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

Linux 패키지는 packagecloud.io에서 호스팅됩니다. macOS는 Homebrew tap을 사용하고, Windows는 GitHub Releases에 게시된 릴리스 아카이브를 사용합니다.

Linux

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

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

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

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

방법 A: Alpacon 웹 UI 사용

1. Alpacon 워크스페이스에 로그인
2. Servers → 서버 등록로 이동
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.ap1.alpacon.io"
export PLUGIN_ID="your-plugin-id"
export PLUGIN_KEY="your-plugin-key"

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

3단계: Alpamon 설치

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

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

참고: 워크스페이스에 sudo with MFA가 활성화되어 있으면 설치 명령에 alpamon-pam을 추가하여 PAM 모듈도 함께 설치하세요. 예를 들어 sudo -EH apt-get install -y alpamon alpamon-pam(RHEL 계열은 yum 사용)입니다. 워크스페이스에서 생성된 명령은 이를 자동으로 추가합니다.

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

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

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

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

export ALPACON_URL="https://your-workspace.ap1.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 -EH dpkg -i alpamon_amd64.deb
 
# 누락된 종속성 설치
sudo -EH apt-get install -f -y
 
# 서비스 시작
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 -EH rpm -i alpamon.x86_64.rpm
 
# 서비스 시작
sudo systemctl start alpamon
sudo systemctl enable alpamon

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

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

macOS

Homebrew로 Alpamon을 설치한 뒤 alpamon register를 실행하면 설정 파일이 작성되고 launchd 서비스가 시작됩니다. 아래 $(brew --prefix) 형식은 Apple Silicon(/opt/homebrew/bin)과 Intel(/usr/local/bin) Mac 모두에서 동작합니다. Apple Silicon에서는 sudo가 Homebrew 바이너리를 찾지 못할 수 있으므로 전체 경로를 사용합니다.

brew tap alpacax/alpacon
brew install alpamon
sudo "$(brew --prefix)/bin/alpamon" register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_API_TOKEN

alpamon register는 나중에 다시 실행해도 안전합니다. 설정 파일을 갱신하고 서비스를 다시 시작합니다.

Windows

관리자 권한 PowerShell(관리자 권한으로 실행)을 열고 아래 두 방법 중 하나를 선택하세요. 두 방법 모두 alpamon.exe register가 에이전트를 C:\Program Files\alpamon\에 설치하고, 부팅 시 자동으로 시작되는 Windows 서비스로 등록한 뒤 서비스를 시작합니다. register는 나중에 다시 실행해도 안전합니다. 설정을 갱신하고 서비스를 다시 시작합니다.

방법 1: 수동 설치

1. GitHub Releases에서 alpamon-X.Y.Z-windows-amd64.zip을 다운로드하고 압축을 풉니다.
2. 압축을 푼 폴더에서 관리자 권한 PowerShell을 통해 실행:

.\alpamon.exe register `
    --url https://your-workspace.ap1.alpacon.io `
    --token YOUR_API_TOKEN

방법 2: install.ps1 자동 설치

cloud-init, EC2 UserData, Packer, Azure Custom Script Extension에 권장됩니다. 스크립트는 릴리스 아카이브를 다운로드하고, 릴리스와 함께 게시된 체크섬으로 다운로드 무결성을 검증한 뒤 압축을 풀고 alpamon register를 실행합니다.

파일 다운로드 후 실행 (권장: 설치 스크립트가 디스크에 남아 감사가 가능합니다):

$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_API_TOKEN"
$installer = Join-Path $env:TEMP 'alpamon-install.ps1'
Invoke-WebRequest -UseBasicParsing `
    -Uri 'https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1' `
    -OutFile $installer
& powershell -ExecutionPolicy Bypass -File $installer

파이프 iex 형식 (간결하지만 감사성이 떨어집니다):

$env:ALPAMON_URL   = "https://your-workspace.ap1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_API_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex

고급: 수동 등록

Alpamon을 수동으로 설치한 경우(워크스페이스에서 생성된 설치 명령을 사용하지 않고)에는 별도로 등록할 수 있습니다:

등록 정보 받기

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

서버 등록

서버에서 등록 명령 실행:

sudo alpamon register \
  --url https://your-workspace.ap1.alpacon.io \
  --token YOUR_API_TOKEN \
  --name "production-web-01" \
  --tag env=prod --tag role=web

옵션:

• --url: Alpacon 서버 URL (필수)
• --token: servers:register 범위의 API 토큰 (필수)
• --name: 서버 이름 (선택사항, 기본값: 호스트네임)
• --platform: 플랫폼 타입 debian, rhel, darwin, windows (선택사항, 자동 감지)
• --ssl-verify: SSL 인증서 검증 활성화 (기본값: true)
• --ca-cert: CA 인증서 파일 경로 (선택사항)
• --tag: key=value 형식의 서버 태그 (선택사항, 반복 지정 가능)
• --no-cloud-probe: 클라우드 호스트에서 클라우드 제공자 메타데이터 자동 감지 건너뛰기 (선택사항)

등록 확인

플랫폼에 맞는 명령으로 에이전트 상태를 확인합니다.

Linux

sudo systemctl status alpamon
sudo journalctl -u alpamon -f

macOS

sudo launchctl print system/com.alpacax.alpamon
tail -f /var/log/alpamon/alpamon.log

Windows

sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Wait -Tail 50

워크스페이스에서:

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

구성

구성 파일

구성 파일 위치는 플랫폼에 따라 다릅니다:

• Linux: /etc/alpamon/alpamon.conf
• macOS: /Library/Application Support/alpamon/alpamon.conf
• Windows: %ProgramData%\alpamon\alpamon.conf

형식 (INI):

[server]
id = your-server-id
key = your-server-key
url = https://your-workspace.ap1.alpacon.io
 
[ssl]
verify = true
# ca_cert = /path/to/ca.crt    # Custom CA certificate (optional)
 
[logging]
level = info    # debug, info, warning, error, fatal
debug = false
 
[pool]
max_workers = 20        # Maximum concurrent workers
queue_size = 200        # Job queue size
default_timeout = 30    # Task timeout in seconds (0 = no timeout)
 
[editor]
idle_timeout = 60       # Code-server idle timeout in minutes (0 = disabled)

참고: 이 파일은 설치 또는 등록 시 자동으로 생성됩니다. 일반적으로 수동으로 편집할 필요가 없습니다.

환경 변수

다음 환경 변수는 패키지 설치 시 자동 등록에 사용됩니다:

# Required for auto-registration
export ALPACON_URL="https://your-workspace.ap1.alpacon.io"
export PLUGIN_ID="your-server-id"
export PLUGIN_KEY="your-server-key"
 
# Optional
export ALPACON_SSL_VERIFY="true"      # SSL certificate verification
export ALPACON_CA_CERT="/path/to/ca.crt"  # CA certificate path
export PLUGIN_DEBUG="false"           # Enable debug logging

프록시 구성

서버가 프록시 뒤에 있는 경우, 설치 명령 또는 alpamon register 실행 전에 HTTP 프록시 환경 변수를 설정합니다:

export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

참고: 소문자 형식(http_proxy / https_proxy)을 사용하세요. 워크스페이스에서 생성된 명령과 시스템 패키지 매니저가 이 형식을 읽습니다. sudo -EH의 -EH 플래그는 설치 과정에서 이 변수를 보존합니다.

에이전트 업그레이드

서버를 등록하면 Alpacon이 Linux와 macOS에서 Alpamon 에이전트를 최신 상태로 유지해 줍니다. 직접 내려받거나 다시 설치할 필요가 없습니다. 두 가지 방법이 있습니다.

• 자동: 워크스페이스 설정에서 자동 에이전트 업그레이드가 켜져 있으면(기본값) 에이전트가 알아서 최신 버전으로 업그레이드됩니다.
• 수동: CLI에서 alpacon agent upgrade SERVER로 특정 서버를 업그레이드한 뒤, alpacon events로 진행 상황을 확인합니다.

에이전트는 새 버전을 받아 적용한 뒤 자동으로 재시작합니다. 서버가 잠깐 오프라인이 됐다가 다시 연결될 수 있으며, 업그레이드가 실패하면 에이전트는 이전 버전을 그대로 유지합니다. Linux에서는 시스템 패키지 매니저(apt/yum)를 통해, macOS에서는 GitHub Releases에서 업데이트를 받습니다. 모든 서버는 버전 확인을 위해 api.github.com으로의 아웃바운드 HTTPS가 필요합니다.

Windows에서는 명령을 통한 업그레이드가 아직 지원되지 않습니다. 최신 릴리스로 설치 프로그램을 다시 실행해 업그레이드하세요.

업그레이드가 적용되지 않으면 에이전트 업그레이드 문제를 참고하세요.

제거

Linux

# 서비스 중지
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

macOS

brew uninstall alpamon
 
# Remove configuration, data, and logs
sudo rm -rf "/Library/Application Support/alpamon"
sudo rm -rf /var/log/alpamon

Windows

관리자 권한 PowerShell에서:

sc.exe stop alpamon
sc.exe delete alpamon
 
# Remove binaries, configuration, and logs
Remove-Item "C:\Program Files\alpamon" -Recurse -Force
Remove-Item "$env:ProgramData\alpamon" -Recurse -Force

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

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

문제 해결

에이전트가 시작되지 않음

해당 플랫폼의 명령으로 서비스 상태와 로그를 확인합니다.

Linux (systemd)

sudo systemctl status alpamon
sudo journalctl -u alpamon -n 50

macOS (launchd)

sudo launchctl print system/com.alpacax.alpamon
tail -n 50 /var/log/alpamon/alpamon.log

Windows (Service Control Manager)

관리자 권한 PowerShell에서:

sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 50

서비스 시작 자체가 실패하는 경우 이벤트 뷰어 → Windows 로그 → 응용 프로그램 및 응용 프로그램 및 서비스 로그도 확인하세요.

등록 실패

일반적인 문제:

• 잘못된 토큰: 워크스페이스에서 토큰 재생성
• 네트워크 오류: 방화벽/프록시 설정 확인
• 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

성능 튜닝

/etc/alpamon/alpamon.conf에서 워커 풀 및 에디터 설정을 조정합니다:

[pool]
max_workers = 20        # Maximum concurrent workers (default: 20)
queue_size = 200        # Job queue size (default: 200)
default_timeout = 30    # Task timeout in seconds (default: 30, 0 = no timeout)
 
[editor]
idle_timeout = 60       # Code-server idle timeout in minutes (default: 60, 0 = disabled)

다음 단계

성공적인 설치 후:

1. 액세스 제어 구성 - 역할 및 권한 설정
2. Websh를 통한 연결 - 브라우저를 통해 서버에 접근
3. 활동 검토 - 세션·명령·승인 결정 감사
4. CI/CD와 통합 - 배포 자동화

도움이 필요하신가요?

• 문제 해결 가이드 확인
• FAQ 방문
• Discord 커뮤니티 참여
• 이메일 지원: support@alpacax.com