GitLab CI 통합
공식 Docker 컨테이너를 사용하여 GitLab CI/CD 파이프라인에서 Alpacon으로 배포와 서버 관리를 자동화하세요.
빠른 시작
1. API 토큰 생성
AlpacaX 워크스페이스 설정에서:
- Settings → API Tokens로 이동
- “Create Token” 클릭
- 배포에 필요한 허용된 명령 추가
- 생성된 토큰 복사
2. CI/CD 변수 추가
GitLab 프로젝트에 다음 변수를 추가하세요 (Settings → CI/CD → Variables):
ALPACON_WORKSPACE_URL: 워크스페이스 URL (예:https://your-workspace.us1.alpacon.io)ALPACON_API_TOKEN: API 토큰 (Masked와 Protected로 표시)
3. .gitlab-ci.yml 생성
중요: alpacax/alpacon-cli 이미지는 ENTRYPOINT ["alpacon"]으로 설정되어 있으므로, GitLab CI에서 entrypoint: [""]로 오버라이드해야 합니다.
stages:
- deploy
deploy:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon websh -r prod-server "docker ps"
only:
- main사용 예제
docker-compose.yml로 배포
deploy-compose:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
- alpacon websh -r prod-server "docker compose -f /tmp/app-compose.yml up -d"
- alpacon websh -r prod-server "docker ps"
only:
- main환경 변수 파일과 함께 배포
참고: 디렉토리에 여러 파일을 업로드할 때는 먼저 디렉토리를 생성하고 적절한 권한을 설정해야 합니다:
deploy-with-env:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
# Create directory with proper permissions
- alpacon websh -r prod-server "mkdir -p /tmp/myapp && chown $USER:$USER /tmp/myapp"
# Upload files
- alpacon cp docker-compose.yml prod-server:/tmp/myapp/
- alpacon cp .env prod-server:/tmp/myapp/
# Deploy
- alpacon websh -r prod-server "docker compose -f /tmp/myapp/docker-compose.yml up -d"
- alpacon websh -r prod-server "docker ps"
only:
- main이미지 태그와 함께 배포
deploy-tagged:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon websh -r prod-server "docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD"
- alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
- alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" prod-server "docker compose -f /tmp/app-compose.yml up -d"
only:
- main다중 환경 배포
deploy-staging:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon cp docker-compose.yml staging-server:/tmp/app-compose.yml
- alpacon websh -r staging-server "docker compose -f /tmp/app-compose.yml up -d"
only:
- develop
environment:
name: staging
deploy-production:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
- alpacon websh -r prod-server "docker compose -f /tmp/app-compose.yml up -d"
only:
- main
environment:
name: production
when: manual완전한 CI/CD 파이프라인
stages:
- build
- deploy
build-image:
stage: build
image: docker:latest
services:
- docker:dind
script:
- docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
- docker build -t $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA .
- docker push $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA
only:
- main
deploy:
stage: deploy
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]
script:
- alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
- alpacon websh -r --env="DOCKER_USERNAME=$DOCKER_USERNAME" --env="DOCKER_PASSWORD=$DOCKER_PASSWORD" prod-server "docker login -u \$DOCKER_USERNAME -p \$DOCKER_PASSWORD"
- alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
- alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" prod-server "docker compose -f /tmp/app-compose.yml pull"
- alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" prod-server "docker compose -f /tmp/app-compose.yml up -d"
- alpacon websh -r prod-server "docker ps"
only:
- main
needs:
- build-image문제 해결
Entrypoint 오류
증상: Error: unknown command "sh" for "alpacon"
해결 방법:
이미지 구성에 entrypoint: [""]를 추가하는 것을 잊었습니다. 다음과 같이 사용하세요:
image:
name: alpacax/alpacon-cli:latest
entrypoint: [""]권한 거부
증상: Docker 명령 실행 시 permission denied
해결 방법:
root로 실행하려면 -r 플래그를 추가하세요: alpacon websh -r server-name "docker ps"
업로드 후 파일을 찾을 수 없음
증상: 파일이 성공적으로 업로드되었지만 명령 실행 시 찾을 수 없음
해결 방법: 디렉토리가 존재하지 않거나 권한이 없을 수 있습니다. 적절한 소유권으로 디렉토리를 생성하세요:
- alpacon websh -r server "mkdir -p /path/to/dir && chown username:username /path/to/dir"
- alpacon cp file.txt server:/path/to/dir/