Turborepo 원격 캐시 설정 방법 (Vercel / Self-hosted)

안녕하세요. J4J입니다.

 

이번 포스팅은 turborepo 원격 캐시 설정하는 방법에 대해 적어보는 시간을 가져보려고 합니다.

 

 

 

관련 글

 

모노레포를 위한 Turborepo 기초 가이드

모노레포를 위한 Turborepo 기초 가이드

 

Helm 이란? Helm 입문을 위한 기본 개념 설명

Helm 이란? Helm 입문을 위한 기본 개념 설명

 

 

반응형

 

 

원격 캐시를 설정하는 이유

 

이전 글에서 모노레포 환경에서 turborepo를 사용하는 이유 중 하나로 캐싱에 대해 언급한 적이 있습니다.

 

turborepo는 이미 build 된 결과물을 캐싱하여 다시 재 사용 하기에, turbo.json 파일에 설정한 방식에 따라 많은 시간을 절약하는 경험을 하게 됩니다.

 

 

 

하지만 로컬에서만 수행되는 단순 캐싱만을 사용하게 되면 아쉬운 점이 다음과 같이 있습니다.

 

• git ci 환경에서는 캐싱 효과가 제공되지 않음
• 서로 다른 개발자 간 캐싱된 결과물을 공유할 수 없음
• 등등...

 

 

그래서 이런 부분을 보완하고자 원격 캐시 서버를 이용하는 방법이 존재합니다.

 

원격 캐시 서버를 이용하는 방법은 크게 다음과 같이 2가지로 나뉩니다.

 

• vercel 활용
• 캐시 서버 자체 구축 (self-hosted)

 

 

 

오픈된 환경에서 프로젝트를 구축하는 경우에는 vercel을 이용하여 편리하게 활용해 볼 수 있습니다.

 

별도의 서버 구축 없이 vercel에 인증 정보를 기반으로 연결만 하면 원격 캐싱 기능을 활용하여 더 누적된 시간 절약을 경험할 수 있게 됩니다.

 

하지만 사용되는 방식에 따라 비용이 필요할 수 있는 것으로 알고 있습니다.

 

그러므로 vercel을 이용하실 것이라면 자신의 프로젝트가 비용을 필요로 할지 한번 확인해 보시고 사용하는 것을 권장합니다.

 

 

 

오픈되지 않은 환경에서 개발을 하고 있거나, 내부 서버 구축이 필요하다고 생각한다면 self-hosted 기반의 서버 구축을 진행하는 방법도 있습니다.

 

여러 레퍼런스를 참고해보면 가장 많이 보이는 방식은 ducktors/turborepo-remote-cache를 활용하는 방법인 것 같습니다.

GitHub - ducktors/turborepo-remote-cache: Open source implementation of the Turborepo custom remote cache server.

 

이런 오픈된 서버 구현체들을 이용하여 직접 서버에 배포를 한다면 캐시 서버를 구축하는데 도움이 될 것이고, turborepo-remote-cache 말고도 다른 서버들도 있기에 선택지도 존재합니다.

 

그리고 k8s 기반으로 사용되는 곳에서도 위와 같은 서버 구현체를 활용할 수 있지만, helm 기반으로 리소스 관리를 좋아하시는 분들은 helm chart도 제공되기에 참고하시면 될 것 같습니다.

turborepo-remote-cache 1.1.1 · adriantr/adriantr

 

 

 

 

Vercel 설정

 

가장 먼저 vercel을 활용하는 경우 설정하는 방법에 대해 간단히 적어보겠습니다.

 

다음의 순서를 따라 진행해 주시면 됩니다.

 

 

 

[ 1. vercel 인증 ]

 

프로젝트가 사용되는 곳에서 다음 명령어를 입력해 줍니다.

 

vercel의 계정이 있어야 진행될 수 있기에 계정이 없으신 분들은 계정 생성을 먼저 해주셔야 합니다.

 

$ npx turbo login

 

turbo login 명령어를 통해 vercel 인증 처리 진행 페이지

 

turbo login 명령어를 통해 vercel 인증이 올바르게 수행되는 경우 보이는 페이지

 

 

 

[ 2. 원격 서버 연결 ]

 

다음의 명령어를 이용하여 서버 연결을 진행해 줍니다.

 

명령어를 입력하면 vercel 캐시 서버를 사용할 것인지 scope는 어떤 곳으로 할지 선택하는 곳이 나오게 됩니다.

 

$ npx turbo link

 

 

 

[ 3. 테스트 ]

 

연결까지 모두 완료되었다면 원격 캐싱이 올바르게 동작하는지 확인해 보겠습니다.

 

가장 먼저 .turbo 하위를 보면 config.json에서 캐시 서버가 설정되면서 사용되는 team id 정보를 확인할 수 있습니다.

 

원격 캐싱이 설정된 경우 team id 정보를 확인하는 json 파일

 

 

 

또한 .turbo/cache 하위에 있는 모든 파일을 삭제한 뒤 turbo 명령어 기반 build를 수행해 보면 다음과 같이 원격 캐싱의 사용 여부를 확인할 수 있습니다.

 

그리고 설정이 올바르게 되었다면 로컬 캐시 정보가 없더라도 cache hit가 되어 캐싱된 build 처리가 이루어지는 것을 확인할 수 있습니다.

 

원격 캐싱에 의해 원격 캐싱 사용 여부와 cache hit 로그가 발생

 

 

 

[ 4. gitlab ci 설정 ]

 

github의 경우 github action을 사용하면 되고, gitlab의 경우 gitlab ci를 사용하면 됩니다.

 

저의 경우 gitlab을 기반으로 설정해 보고자 합니다.

 

 

 

어떤 방식을 사용하더라도 가장 중요한 것은 vercel access token과 team 정보를 확인하는 것입니다.

 

access token의 경우 Vercel Token 설정을 접속하면 생성해 볼 수 있습니다.

Settings – Vercel

 

 

token을 생성할 때는 scope로 지정할 team 정보를 올바르게 설정해야 합니다.

 

 

 

token이 생성 되었다면 CI/CD variable에 접속하여 2개의 variable을 등록해 줍니다.

 

TURBO_TOKEN의 경우 방금 생성한 access token 값을 그대로 넣어 주시면 됩니다.

 

TURBO_TEAM의 경우 config.json 파일에서 확인할 수 있었던 team id 값을 넣어 주시면 됩니다.

 

gitlab ci/cd variable 설정 페이지

 

 

 

그 외에 ci를 관리하는 리소스 파일에는 turborepo를 위해 별도로 작업할 것은 없습니다.

 

이 상태에서 build를 수행하는 ci를 작성하여 gitlab 내부에서 pipeline이 동작되게 만들면 다음과 같이 원격 캐싱이 ci에서도 사용되는 것을 확인할 수 있습니다.

 

gitlab ci에서 remote caching이 올바르게 동작되어 캐시 처리가 이루어지는 로그 확인

 

 

 

 

Self-hosted 설정

 

이번에는 자체 서버 구현을 통해 원격 캐시를 적용해 보겠습니다.

 

self-hosted 방법에 대해서는 위에서 얘기한 것처럼 여러 가지 방법이 있지만, 저는 이곳에서 helm chart를 활용하여 구성해 보겠습니다.

 

 

 

[ 1. repository 추가 ]

 

$ helm repo add adriantr https://adriantr.github.io/charts
$ helm repo update

 

 

 

[ 2. namespace 생성 ]

 

$ kubectl create namespace remote-cache

 

 

 

[ 3. values.yaml 설정 ]

 

chart에서 제공하는 정보를 그대로 사용하는 경우 원격 캐시 서버가 원하는 방식으로 동작되지 않을 수 있습니다.

 

다음과 같이 각자의 환경에 맞춰 구성하기 위해 yaml 파일을 작성해 주시면 됩니다.

 

// turborepo-remote-cache-values.yaml
replicaCount: 1 # replication 설정

image: # remote cache 구축에 사용될 image 설정
  repository: ducktors/turborepo-remote-cache
  tag: "2.7.0"
  pullPolicy: IfNotPresent
  
config:
  storageProvider: "local" # storage provider 설정, local로 설정하는 경우 container 내부에서 캐시 파일 관리 (local, s3 등)
  storagePath: "turborepo-cache" # storage 경로 설정
  turboToken: "my-token" # token 설정, 보안 등급이 높은 random secret 기반으로 설정 권장

# ingress 설정이 필요한 경우
# ingress:
  # enabled: true
  # className: nginx
  # hosts:
    # - host: turbo-remote-cache.example.com
      # paths:
        # - path: /
          # pathType: Prefix

# resource 설정이 필요한 경우
# resources:
  # requests:
    # cpu: 100m
    # memory: 128Mi
  # limits:
    # cpu: 100m
    # memory: 128Mi

 

 

 

 

[ 4. cluster에 chart 적용 ]

 

$ helm install turborepo-remote-cache adriantr/turborepo-remote-cache -n remote-cache -f turborepo-remote-cache-values.yaml

 

 

 

[ 5. 테스트 ]

 

원격 캐시 서버가 올바르게 구동이 되었다면 먼저 로컬에 연결하여 테스트 해보겠습니다.

 

캐시 서버를 사용하고자 하는 프로젝트에서 다음과 같이 변수 정보들을 설정해 주시면 됩니다.

 

vercel 설정과 달리 team 정보는 원하는 값을 자유롭게 입력할 수 있고, token 정보는 위에 yaml에서 구성했던 turboToken 값을 그대로 사용해 주시면 됩니다.

 

다만, 참고 사항으로 team 정보가 서로 동일한 곳에서만 캐시 값들이 공유됩니다.

 

// mac 기반으로 설정하는 경우
export TURBO_API="{원격 캐시 서버 host}"
export TURBO_TEAM="my-team"
export TURBO_TOKEN="my-token"

// window 기반으로 설정하는 경우
$env:TURBO_API="{원격 캐시 서버 host}"
$env:TURBO_TEAM="my-team"
$env:TURBO_TOKEN="my-token"

 

 

 

변수 설정이 완료되면 build를 수행하여 캐시 적용 여부를 확인할 수 있습니다.

 

올바르게 구성이 되었다면 vercel을 사용했던 것처럼 다음과 같은 build 로그를 볼 수 있습니다.

 

원격 캐싱에 의해 원격 캐싱 사용 여부와 cache hit 로그가 발생

 

 

그리고 원격 캐시 서버의 container 내부를 확인해 보면 다음의 경로에 캐싱된 파일들을 확인할 수도 있습니다.

 

원격 캐시 서버 내부에 캐싱된 파일 확인

 

 

 

[ 6. gitlab ci 설정 ]

 

이번에도 gitlab 기반의 ci 설정을 해보겠습니다.

 

gitlab ci 설정은 vercel 기반으로 하는 것과 동일하게 variable 설정만 해주시면 됩니다.

 

self-hosted는 로컬 설정에서 사용했던 정보를 그대로 활용하여 다음과 같이 총 3개의 variable을 구성해 줍니다.

 

그러면 build를 수행하는 ci pipeline이 동작할 때 원격 캐싱이 적용되어 더 빠른 속도로 stage가 완료되는 경험을 겪을 수 있습니다.

 

gitlab ci/cd variable 설정 페이지

 

 

 

 

 

 

 

이상으로 turborepo 원격 캐시 설정하는 방법에 대해 간단하게 알아보는 시간이었습니다.

 

읽어주셔서 감사합니다.