설치 가이드

서버에 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. 서버 세부 정보 입력:
   • Name: 서버 식별자 (예: production-web-01)
   • Platform: OS 선택 (Debian 기반, Red Hat 기반, macOS, Windows)
   • User Groups (선택사항): 이 서버에 접근할 수 있는 그룹
4. Save 클릭

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

워크스페이스에서 생성된 설치 스크립트를 복사하여 서버에서 실행합니다. 워크스페이스는 선택한 플랫폼에 맞춰 스크립트를 자동 생성합니다—Linux와 macOS에는 셸 명령, Windows에는 PowerShell 명령.

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

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

Windows—관리자 권한 PowerShell(관리자 권한으로 실행)에 붙여넣기:

# The script will look similar to this:
$env:ALPAMON_URL   = "https://your-workspace.us1.alpacon.io"
$env:ALPAMON_TOKEN = "YOUR_TOKEN"
iwr https://raw.githubusercontent.com/alpacax/alpamon/main/scripts/install.ps1 -UseB | iex

스크립트는 어느 경우든 다음을 수행합니다:

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

참고: Linux와 macOS에서는 sudo -E의 -E 플래그가 환경 변수를 유지합니다 (프록시 구성에 유용).

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.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?any=true | 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?any=true | 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 버전 및 아키텍처에 대한 모든 사용 가능한 패키지를 확인하세요.

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

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.us1.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.us1.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.us1.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.us1.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.us1.alpacon.io \
  --token YOUR_API_TOKEN \
  --name "production-web-01"

옵션:

• --url: Alpacon 서버 URL (필수)
• --token: server:register 범위의 API 토큰 (필수)
• --name: 서버 이름 (선택사항, 기본값: 호스트네임)
• --platform: 플랫폼 타입—debian, rhel, darwin, windows (선택사항, 자동 감지)
• --ssl-verify: SSL 인증서 검증 활성화 (기본값: true)
• --ca-cert: CA 인증서 파일 경로 (선택사항)

등록 확인

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

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.us1.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.us1.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

참고: sudo -E의 -E 플래그는 설치 과정에서 이러한 변수를 보존합니다.

제거

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