gcx 설치하기

gcx 설치하기

이 문서는 Grafana CLI 도구인 gcx를 설치하는 다양한 방법을 알려드려요. 설치 스크립트, Homebrew, 사전 빌드된 바이너리, 소스 빌드까지 방법별로 설명합니다.

출처: 문서

본문

스크립트로 빠르게 설치하기

Linux나 macOS에서 gcx를 설치하는 가장 빠른 방법은 스크립트를 사용하는 거예요:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

이 스크립트는:

  • 운영 체제와 아키텍처를 감지합니다.
  • GitHub에서 최신 릴리스를 다운로드합니다.
  • SHA-256 체크섬을 검증합니다.
  • 바이너리를 ~/.local/bin에 설치합니다.

업그레이드

업그레이드는 같은 명령을 다시 실행하면 돼요. 스크립트는 항상 최신 릴리스를 설치합니다.

결과를 확인하세요:

gcx --version

버전이 바뀌지 않는다면 업그레이드 후에도 버전이 바뀌지 않을 때를 참고하세요.

설치 프로그램 설정 옵션

다음 환경 변수로 설치 스크립트를 커스터마이즈할 수 있어요:

환경 변수 기본값 설명
GCX_INSTALL_DIR $HOME/.local/bin 바이너리를 설치할 디렉터리
GCX_VERSION latest 설치할 특정 버전 (예: 0.2.4)
GITHUB_TOKEN unset API 요청용 GitHub 토큰 (속도 제한 회피)

스크립트는 INSTALL_DIR과 VERSION도 받아들입니다. GCX_ 이름이 우선합니다. INSTALL_DIR과 VERSION은 흔한 이름이고 curl | sh가 셸에서 내보낸 모든 변수를 상속받기 때문에, GCX_ 이름을 선호하세요.

예시

특정 버전 설치:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_VERSION=0.2.4 sh

/usr/local/bin에 설치:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh

제거하기

gcx를 제거하려면 바이너리를 삭제하면 돼요:

rm ~/.local/bin/gcx

Homebrew로 설치하기 (macOS 및 Linux)

Homebrew로 gcx를 설치하려면:

brew install gcx

이 명령은 homebrew-core에서 gcx 포뮬러를 설치합니다. Homebrew는 macOS와 Linux용 사전 빌드된 bottle을 갖고 있어서 설치는 몇 초면 끝나요. tap을 추가할 필요는 없습니다.

기존 설치를 업그레이드하려면:

brew upgrade gcx

Grafana tap에서 설치하기

Grafana tap에도 gcx가 있어요. Homebrew가 바이너리를 여러분의 머신에서 컴파일하길 원한다면 tap을 사용하세요:

brew install grafana/grafana/gcx

Homebrew는 이 포뮬러의 빌드 의존성으로 go를 설치합니다. 첫 설치는 보통 30~60초 걸리고, 이후 업그레이드는 Homebrew 다운로드 캐시를 재사용합니다.

gcx는 한 곳에서만 설치하세요. 같은 이름의 두 Homebrew 포뮬러는 서로 충돌합니다.

Homebrew와 macOS Gatekeeper

두 Homebrew 방법 모두 macOS Gatekeeper 문제를 피합니다. Homebrew는 설치하는 파일에 속성(quarantine attribute)을 설정하지 않으므로, notarisation 관련 우회 조치가 필요 없어요.

사전 빌드된 바이너리 설치하기

사전 빌드된 바이너리는 다양한 시스템과 아키텍처에서 제공됩니다. 자세한 내용은 GitHub 릴리스 버전을 참고하세요.

사전 빌드된 바이너리를 설치하려면:

  1. 필요한 운영 체제와 아키텍처용 아카이브를 다운로드합니다.
  2. 아카이브를 압축 해제합니다.
  3. 실행 파일을 보관하려는 디렉터리로 이동합니다.
  4. 그 디렉터리가 PATH에 있는지 확인합니다.
  5. 파일에 실행 권한이 있는지 확인합니다.

macOS를 사용한다면 수동으로 다운로드한 바이너리가 Gatekeeper에 차단될 수 있어요. 자세한 내용은 macOS Gatekeeper와 killed: 9를 참고하세요.

소스로 설치하기

Go로 gcx를 설치하려면 다음이 필요합니다:

  • git
  • go 1.24 이상

설치하려면:

go install github.com/grafana/gcx/cmd/gcx@latest

업그레이드 후에도 버전이 바뀌지 않을 때

이 페이지에는 여러 설치 방법이 있고, 각각 gcx를 다른 디렉터리에 씁니다. 두 가지 방법을 쓰면 복사본이 두 개가 돼요. 셸은 PATH에서 먼저 오는 디렉터리의 복사본을 실행하며, 다른 복사본을 업그레이드해도 눈에 보이는 변화는 없습니다.

모든 복사본을 나열하세요:

which -a gcx

첫 번째 줄이 셸이 실행하는 복사본이에요. 원하지 않는 복사본을 제거하세요:

경로 설치 방법 제거 명령
~/.local/bin/gcx 설치 스크립트 rm ~/.local/bin/gcx
/usr/local/bin/gcx 사전 빌드 바이너리 또는 GCX_INSTALL_DIR 스크립트 sudo rm /usr/local/bin/gcx
/opt/homebrew/bin/gcx , /home/linuxbrew/.../gcx Homebrew brew uninstall gcx
~/go/bin/gcx go install rm ~/go/bin/gcx

복사본을 제거한 뒤에도 셸의 명령 해시 테이블에 옛 경로가 남아 있을 수 있어요. 새 터미널을 열거나 다음을 실행하세요:

hash -r

설치 스크립트는 이 문제를 직접 알려줍니다. 두 경로와 두 버전을 모두 명명하고 제거 명령도 제공합니다.

macOS Gatekeeper와 killed 9

macOS는 다운로드한 바이너리를 기본적으로 격리(quarantine)합니다. gcx 릴리스 바이너리는 아직 Apple notarisation을 받지 않았기 때문에, macOS가 처음 실행 시 차단할 수 있습니다. 이 경우 다음 두 가지 증상 중 하나가 나타납니다:

  • Intel macOS: "Apple could not verify 'gcx' is free of malware…"라는 대화상자가 뜨고 바이너리가 실행되지 않습니다.
  • Apple Silicon (M-시리즈) macOS: 대화상자 없이 바이너리가 즉시 killed: 9로 종료됩니다.

Homebrew 사용자는 영향을 받지 않습니다. Homebrew는 설치하는 파일에 xattr를 설정하지 않습니다.

macOS Gatekeeper 우회하기

수동 다운로드에서는 xattr를 지우고 바이너리에 ad-hoc 서명을 해서 Apple Silicon이 받아들이게 함으로써 우회할 수 있어요:

xattr -d com.apple.quarantine "$(command -v gcx)" 2>/dev/null || true
codesign --sign - --force "$(command -v gcx)"   # required on Apple Silicon

그다음 gcx --version을 다시 실행하세요. 이후 호출은 차단 없이 성공할 거예요.

이 단계는 gcx 릴리스 바이너리가 Apple notarisation을 받으면 더 이상 필요 없게 됩니다.

더 알아보기 (Learn more)