다른 연구실 계정에서 연구를 실행하는 배포 버튼

이 튜토리얼은 어노테이션 연구의 git 저장소에 원클릭 배포 버튼을 추가하여, 협력자, 학생 또는 다른 연구실이 Potato를 설치하지 않고도 자신의 클라우드 계정에서 연구를 실행할 수 있게 합니다. 재현 패키지는 보통 설정 파일과 데이터 파일에 더해 도구를 설치하고 서버를 시작하라는 안내를 함께 제공하는데, 그 안내의 모든 단계가 재현이 멈출 수 있는 지점입니다. 배포 버튼은 이를 계정 로그인과 클릭 한 번으로 바꾸며, 각 배포는 어노테이션을 배포하는 사람이 지정한 저장소에 백업합니다. 이 튜토리얼은 각 배포자가 자신의 백업을 지정하는 첫 릴리스인 Potato 2.12.0을 설명하므로, 버튼은 2.12.0 이상으로 생성하세요. 또한 config.yaml과 데이터가 이미 git 저장소에 있는 연구가 필요합니다.

배포 버튼이 쓰는 파일

Heroku, Render, AWS CloudFormation은 각각 저장소의 파일로 서비스를 빌드할 수 있습니다. Heroku는 app.json을, Render는 render.yaml을, CloudFormation은 템플릿을 읽습니다. potato deploy button은 연구에 맞게 이 파일들을 쓰고 README에 붙여 넣을 배지를 출력합니다. 사용자의 config.yaml은 절대 바뀌지 않습니다. 이 명령은 그 옆에 디버그를 끄고 세션을 유지하며 백업을 설정한 사본 potato.deploy.yaml을 쓰고, 생성된 파일들은 그 사본을 가리킵니다.

저장소에는 비밀 값이 들어가지 않습니다. Heroku와 Render는 누군가 배포할 때 세션 키와 관리자 키를 생성하고, AWS 템플릿은 인스턴스에서 이를 생성하며, 배포하는 사람은 배포 시점에 백업 자격 증명을 제공합니다.

대상 고르기

네 가지 대상은 클릭하는 사람에게 필요한 것이 서로 다릅니다.

Heroku에서 버튼은 월 $7의 Basic 다이노 하나를 실행하며, 다이노의 디스크는 매일 지워집니다. AWS 버튼은 디스크가 유지되는 월 $12의 Lightsail 인스턴스를 만들며, 몇 주 동안 이어질 연구에 알맞습니다. Railway는 자체 대시보드에서 템플릿을 게시하므로, 그 대상에서는 명령이 파일을 쓰는 대신 단계를 출력합니다. Railway 템플릿은 백업 저장소를 포함해 사용자 자신의 배포를 복사하므로, 이를 배포하는 모두가 사용자의 데이터셋을 공유하게 되며 출력되는 단계가 이를 경고합니다.

Heroku 버튼 추가하기

저장소 루트에서 연구의 설정 파일과 백업 종류를 지정해 명령을 실행합니다.

potato deploy button studies/pilot/config.yaml --target heroku --backup hf

Heroku와 Render 버튼은 재시작하면 사라지는 디스크에 배포되고, AWS 버튼의 인스턴스에서는 아무도 어노테이션을 가져가지 않으므로, 파일을 쓰는 세 대상 모두 --backup이 필요합니다. 백업은 5분마다 어노테이션 출력과 프로젝트 데이터베이스의 스냅샷을 백업 저장소에 복사하며, 재시작된 서버는 이를 복원합니다. 배포하는 사람은 버튼을 클릭할 때 이 저장소를 지정합니다. HuggingFace 데이터셋에는 POTATO_BACKUP_HF_REPO와 HF_TOKEN을, S3에는 POTATO_BACKUP_S3_BUCKET과 버킷의 키를 씁니다. Heroku와 Render는 기본값 없이 이를 요청하고 AWS 템플릿은 필수 스택 매개변수로 받으므로, 각 배포는 자신의 저장소에 백업합니다. button은 --hf-backup-repo, --hf-token, --s3-bucket, --s3-region, --s3-endpoint를 무시하며, 무시한다고 알려 줍니다.

Potato 2.11.1 이하로 생성한 버튼은 사용자의 데이터셋을 시작 시 복원이 켜진 채로 potato.deploy.yaml에 기록했습니다. 쓰기 권한이 없는 배포자는 백업이 실패했고, 쓰기 권한이 있는 배포자는 자신의 어노테이션을 사용자의 데이터셋으로 보냈으며, 새 배포는 사용자의 어노테이터를 복원할 수 있었습니다. 그런 버튼은 2.12.0과 --force로 다시 생성한 다음 파일을 커밋하고 푸시하세요.

명령은 무언가를 쓰기 전에 두 가지 파일을 검사합니다. Heroku와 Render는 저장소로 이미지를 빌드하는데, .potato/(관리자 키와 배포 비밀 값), annotation_output/, SQLite 데이터베이스는 이미지에 들어가면 안 됩니다. 저장소에 .dockerignore가 없으면 명령이 하나를 쓰고, 있지만 그 항목들이 빠져 있으면 빠진 항목을 나열합니다. 또한 버튼은 푸시한 것을 그대로 배포하므로, git check-ignore가 무시된다고 보고하지 않는 해당 경로도 나열합니다.

생성된 파일을 커밋하고 푸시합니다.

git add app.json heroku.yml Dockerfile.potato .dockerignore studies/pilot/potato.deploy.yaml
git commit -m "Add a Deploy to Heroku button"
git push

명령이 출력한 배지를 README에 붙여 넣으세요. 배지를 클릭한 방문자는 Heroku에 로그인하고, 자신의 백업 데이터셋을 지정하고 그에 대한 토큰을 입력하면, Heroku가 할당한 주소에서 연구가 실행됩니다.

AWS Launch Stack 버튼 추가하기

CloudFormation은 S3에서만 템플릿을 읽으므로, AWS 버튼에는 한 단계가 더 필요합니다. 템플릿을 생성하고 직접 소유한 버킷에 업로드한 다음, 템플릿의 URL로 버튼을 다시 생성합니다.

potato deploy button config.yaml --target aws --backup hf
aws s3 cp potato-lightsail.cfn.yaml s3://my-bucket/ --acl public-read
potato deploy button config.yaml --target aws --backup hf \
    --template-url https://my-bucket.s3.amazonaws.com/potato-lightsail.cfn.yaml --force

스택은 Lightsail 인스턴스와 고정 IP를 만듭니다. 인스턴스는 공개 저장소를 클론하고, 비밀 값을 생성하며, 고정 IP용 인증서와 함께 Potato를 시작합니다. 스택의 URL 출력이 어노테이터에게 줄 주소이며, 스택이 완료되고 몇 분 뒤에 준비됩니다. 관리자 키는 인스턴스에 남아 있고, 배포한 사람은 Lightsail의 브라우저 SSH에서 sudo grep ADMIN /opt/potato/potato.env로 읽습니다.

Potato 버전과 데이터 고정하기

재현은 원본과 같은 Potato 버전으로 실행되어야 합니다. 2.11부터 버튼은 이미지를 자신을 생성한 Potato 버전에 고정합니다. Potato 2.10은 대신 latest 태그를 쓰므로, 몇 달 뒤의 배포는 그때의 최신 Potato로 실행되며, 그 사이에 일치도나 내보내기가 수정되면 재현이 보고하는 수치가 달라질 수 있습니다. 2.10에서는 버튼을 생성할 때 --image로 이미지를 고정하세요. 예를 들어 --image ghcr.io/davidjurgens/potato:2.10.3입니다. 데이터도 같은 방식으로, 시작할 때 내려받지 말고 설정과 함께 커밋하여 고정하세요.

--dry-run은 아무것도 쓰지 않고 모든 파일을 출력하므로, 커밋하기 전에 버튼이 무엇을 하는지 확인할 수 있습니다. 기존 파일은 --force가 있을 때만 교체됩니다. Potato를 로컬이나 클라우드에서 실행하기는 다른 배포 대상과 함께 이 버튼을 다루며, 배포 버튼 문서는 모든 옵션을 나열합니다.