Potato를 로컬 또는 클라우드에서 실행하기
pip나 Docker로 노트북에서 Potato를 실행하는 방법, 한나절 동안 링크로 공유하는 방법, 명령 하나로 AWS, Jetstream2, Hetzner, Fly, Railway에 연구를 올리는 방법을 설명합니다.
Potato는 명령 두 개로 자신의 컴퓨터에서 실행되고, potato deploy를 쓰면 명령 하나를 더 실행해 같은 설정을 클라우드 호스트에 올릴 수 있습니다. 이 페이지는 흔히 마주치는 상황마다 알맞은 호스트를 짝지어 주고 그에 맞는 명령을 제시합니다. 아래의 클라우드 대상에는 Potato 2.10.0 이상이 필요합니다. 2.10.0은 2.9에 이미 있던 DigitalOcean, Render, HuggingFace 대상에 AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode, OpenStack을 추가했습니다.
작업을 실행할 곳 고르기
어떤 호스트가 맞는지는 작업을 얼마나 오래 띄워 두어야 하는지, 그리고 비용을 누가 내는지에 따라 달라집니다. 표의 비용은 Potato 2.10.0이 각 대상의 기본 크기에 대해 출력하는 추정치이며, --dry-run은 직접 고른 크기의 추정치를 출력합니다.
| 상황 | 명령 | 월 비용 |
|---|---|---|
| 작업을 만들거나 시험해 보는 중 | potato start config.yaml | 무료 |
| 몇 사람과 한나절 동안 하는 파일럿 | potato share config.yaml | 무료 |
| AWS 계정이 있는 연구 | potato deploy up config.yaml --provider aws | $12 |
| 예산이 없는 미국 기관의 연구 | potato deploy up config.yaml --provider openstack --cloud jetstream2 | ACCESS 할당이 있으면 무료 |
| 가장 낮은 가격으로 하는 연구 | potato deploy up config.yaml --provider hetzner | 약 €6 |
| 관리할 서버 없이 하는 연구 | potato deploy up config.yaml --provider fly | 약 $6 |
| 다른 사람들이 각자의 계정에서 사본을 실행 | potato deploy button config.yaml --target heroku | 호스트가 정함 |
| 소속 기관이 이미 운영하는 서버 | 리버스 프록시 뒤에 둔 Docker 이미지 | Potato 쪽 비용 없음 |
AWS에서는 --provider aws가 만드는 Lightsail을 사용하십시오. 정액 요금에 IPv4 주소와 60 GB 디스크가 포함되고, lightsail:* 권한만 있으면 되므로 권한이 제한된 IAM 역할에서도 동작합니다. EC2 대상(aws-ec2)은 Lightsail이 꺼져 있는 계정을 위한 것입니다.
Jetstream2는 NSF가 자금을 대는 연구용 클라우드입니다. ACCESS 할당이 있으면 비용이 들지 않고, 인스턴스마다 DNS 이름이 붙으므로 주석자는 평범한 호스트 이름과 평범한 인증서를 보게 됩니다. 기본 인스턴스는 시간당 2 서비스 유닛을 쓰며 1년이면 약 17,500 유닛이 되므로, 연구가 끝나면 삭제하십시오.
자신의 컴퓨터에서 Potato 실행하기
Potato에는 Python 3.9 이상이 필요합니다. 설치한 뒤 작업을 시작합니다.
pip install potato-annotation
potato start myproject/config.yaml -p 8000작업은 http://localhost:8000에서 열리며, 다른 사람은 접속할 수 없습니다. potato start는 설정 파일과 데이터 파일을 놓인 자리에서 읽으므로 재시작하면 수정 내용이 반영됩니다. 그래서 작업을 작성하는 동안에는 이 명령을 씁니다. 빠른 시작에서 첫 설정을 만들고, 설치에서 선택 설치 항목(extra)과 가상 환경을 다룹니다.
공개된 Docker 이미지를 쓰면 호스트에 Python이 없어도 됩니다. 이미지에는 Potato와 그 의존성이 들어 있고, config.yaml과 데이터를 담은 프로젝트 폴더는 /app에 마운트됩니다.
docker run -p 8000:7860 -v "$PWD/myproject:/app" ghcr.io/davidjurgens/potato:latest컨테이너는 포트 7860에서 서비스하고, 명령이 이를 내 컴퓨터의 8000번 포트에 연결합니다. 프로덕션 설정에서 이미지의 태그, 환경 변수, Linux 호스트에서 나타나는 파일 소유권 오류를 다룹니다.
potato share로 만드는 임시 공개 링크
potato share는 작업을 실행하고, 명령이 실행되는 동안 공개 HTTPS 링크로 작업을 엽니다. 터널 클라이언트가 필요하며, cloudflared, Tailscale, ngrok 가운데 설치된 것을 이 순서대로 사용합니다.
brew install cloudflared
potato share myproject/config.yamlCtrl-C를 누르거나, 노트북이 절전 모드로 들어가거나, 네트워크가 바뀌면 링크가 끊기고, 주석은 내 디스크에 그대로 남습니다. 터널을 열기 전에 potato share는 누가 로그인할 수 있는지 출력하고 확인을 요청합니다. 터널이 열리면 설정의 로그인 규칙이 링크를 가진 모든 사람에게 적용되기 때문입니다. 일부 대학 네트워크는 trycloudflare.com 링크를 차단하는데, --backend tailscale을 쓰면 이 차단을 피할 수 있습니다. 파일럿이나 연구실 회의에는 potato share를 쓰고, 참여자가 다음 날 다시 들어올 수 있는 작업에는 클라우드 호스트를 쓰십시오.
명령 하나로 클라우드에 배포하기
potato deploy up은 이미 가진 설정을 받아 서버를 만들고, HTTPS 인증서를 받고, 프로젝트를 업로드하고, 작업을 시작한 뒤 URL을 출력합니다. 대상에 맞는 extra를 설치하고, 실행하기 전에 계획을 확인하십시오.
pip install 'potato-annotation[deploy]' # most targets
pip install 'potato-annotation[deploy-aws]' # the three AWS targets
pip install 'potato-annotation[deploy-openstack]' # Jetstream2 and other OpenStack clouds
potato deploy up myproject/config.yaml --provider aws --dry-run
potato deploy up myproject/config.yaml --provider aws--dry-run에는 계정이 필요 없습니다. 배포가 만들 모든 리소스, 월 비용, 그리고 설정 가운데 공개 서버에서 위험한 항목을 출력합니다. --dry-run 없이 실행해도 Potato는 같은 계획을 보여 주고, 확인할 때까지 아무것도 만들지 않습니다. 같은 설정으로 up을 다시 실행하면 기존 배포가 업데이트되며, 첫 up 이후에는 status, logs, pull, destroy에 --provider가 필요 없습니다.
13개의 클라우드 대상
Potato 2.10.0은 13개의 클라우드 대상에 배포합니다. 대상 사이의 가장 큰 차이는 재시작 후에도 디스크가 남는지이며, 이에 따라 배포에 다음 섹션에서 설명하는 백업이 필요한지가 정해집니다.
--provider | 만드는 것 | 월 비용 | 재시작 후 디스크 유지 |
|---|---|---|---|
aws | AWS Lightsail VM, 2 GB | $12 | 예 |
aws-ec2 | Elastic IP가 붙은 EC2 t4g.small VM | 약 $18 | 예 |
aws-ecs | ECS Express Mode의 컨테이너 | 약 $45-70 | 아니요, --backup 필요 |
openstack | Jetstream2나 다른 OpenStack 클라우드의 VM | 할당이 있으면 무료 | 예 |
hetzner | Hetzner Cloud VM, 2 vCPU, 4 GB | 약 €6 | 예 |
vultr | Vultr VM, 1 vCPU, 2 GB | $10 | 예 |
linode | Akamai Linode VM, 1 vCPU, 2 GB | $12 | 예 |
digitalocean | DigitalOcean Droplet, 2 vCPU, 2 GB | $18 | 예 |
fly | 1 GB 볼륨이 붙은 Fly.io Machine | 약 $6 | 예 |
railway | 볼륨이 붙은 Railway 서비스 | 사용량 기준 과금, 보통 $10-20 | 예 |
render | Render 웹 서비스 | 무료, 또는 starter에서 $7와 디스크 비용 | 유료 디스크일 때만 |
heroku | Heroku Basic dyno 1개 | $7 | 아니요, --backup 필요 |
huggingface | Docker Space와 주석을 담는 비공개 데이터셋 | PRO 플랜($9) 또는 Team 플랜 | 아니요, 데이터셋에 백업됨 |
일곱 개의 VM 대상(aws, aws-ec2, openstack, hetzner, vultr, linode, digitalocean)은 같은 방식으로 구성됩니다. 각 대상에는 해당 배포용으로 생성한 배포 키, 포트 22, 80, 443만 여는 방화벽, Let's Encrypt 인증서를 쓰는 Caddy, systemd 서비스로 실행되는 Potato가 갖춰지며, potato deploy logs와 pull은 이 모든 대상에서 동작합니다. Fly, Railway, Render, ECS Express는 공개된 이미지를 실행하고, 컨테이너가 시작될 때 프로젝트를 내려받습니다. Railway, Render, ECS Express는 프로젝트를 백업 저장소에서 가져오므로 셋 모두 --backup이 필요하며, 디스크가 있는 Railway나 Render 서비스에도 필요합니다. Fly에서는 512 KB 미만인 프로젝트가 Machine의 설정에 담겨 전달되므로 저장소가 필요 없습니다.
Google Cloud Run, Azure Container Apps, AWS App Runner는 대상이 아닙니다. Cloud Run과 Azure Container Apps가 제공하는 저장소는 SQLite 데이터베이스를 안전하게 담을 수 없고, App Runner는 2026년 4월 30일에 신규 고객 접수를 마감했습니다. Azure에서는 Docker 이미지를 실행하는 VM을 쓰면 됩니다.
디스크가 지워지는 호스트를 위한 백업
Heroku, ECS Express, Render 무료 등급, HuggingFace Spaces에서는 서버가 재시작될 때 디스크가 지워집니다. --backup은 주석 출력과 프로젝트 데이터베이스의 스냅숏을 5분마다 HuggingFace 데이터셋이나 S3 버킷에 복사하고, 서버가 빈 디스크로 시작되면 이를 복원합니다.
potato deploy up myproject/config.yaml --provider heroku --backup hf --hf-token hf_...
potato deploy up myproject/config.yaml --provider heroku --backup s3 --s3-bucket my-bucketHeroku와 ECS Express는 --backup 없이는 배포를 거부합니다. 다만 --demo로 주석을 버려도 된다고 밝히면 예외입니다. 복원은 주석과 함께 계정 목록도 되살리므로, 주석자는 같은 비밀번호로 로그인해 멈춘 곳부터 이어서 작업합니다. 복원은 디스크에 이미 있는 주석을 덮어쓰지 않습니다. --s3-endpoint를 쓰면 S3 백업을 Cloudflare R2, Backblaze B2, MinIO, 또는 대학의 오브젝트 스토리지로 보낼 수 있습니다. 백업은 VM 대상에서도 동작하며, 이때는 데이터의 두 번째 사본을 서버 밖에 둡니다.
potato deploy 밖에서는 설정의 backup 블록이 직접 운영하는 서버에서 같은 일을 합니다. HuggingFace와 S3 클라이언트를 제공하는 hosting extra를 설치하고, 서버 환경에 HF_TOKEN을 설정한 뒤, 기존 설정에 다음 블록을 추가하십시오.
backup:
schedule_minutes: 5
restore_on_boot: true
sinks:
- type: huggingface
repo_id: lab/pilot-annotationsdestroy 전에 주석 내려받기
potato deploy pull은 배포가 수집한 모든 것을 타임스탬프가 붙은 디렉터리로 내려받고 도착한 내용을 확인하며, potato deploy destroy는 서버를 삭제합니다. 이 순서대로 실행하십시오.
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yamldestroy는 한 번도 pull하지 않은 배포의 삭제를 거부하며, 파일을 하나도 받지 못한 pull은 pull로 치지 않습니다. pull은 project.sqlite를 파일로 복사하지 않고 SQLite의 백업 명령으로 복사합니다. WAL 모드인 데이터베이스를 파일째 복사하면 최근 작업이 빠질 수 있기 때문입니다. Fly와 Railway에서는 앱을 삭제하면 볼륨도 함께 삭제되므로, 백업을 따로 실행하지 않았다면 pull로 받은 것이 유일한 사본입니다.
다른 사람의 계정을 위한 배포 버튼
potato deploy button은 호스팅 플랫폼이 git 저장소에서 원클릭 배포를 제공하는 데 읽는 파일을 작성하고, README용 배지를 출력합니다. 공동 연구자, 학생, 다른 연구실이 각자의 계정에서 작업을 실행해야 할 때 사용하십시오.
potato deploy button studies/pilot/config.yaml --target heroku \
--backup hf --hf-backup-repo lab/pilot-annotations대상은 heroku, render, aws, railway입니다. aws 대상은 Lightsail 인스턴스를 만드는 CloudFormation "Launch Stack" 템플릿을 작성하고, railway에서는 Railway가 대시보드에서 템플릿을 게시하기 때문에 명령이 절차를 출력합니다. config.yaml은 바뀌지 않으며, 명령은 배포 설정을 적용한 사본 potato.deploy.yaml을 그 옆에 작성합니다. 저장소에는 비밀 값이 들어가지 않습니다. Heroku, Render, AWS 템플릿은 세션 키와 관리자 키를 배포할 때 생성합니다. Heroku, Render, AWS 버튼에는 --backup이 필요하며, 그 자격 증명은 배포하는 사람이 제공합니다.
더 읽을거리
각 대상은 Potato 문서에 자체 페이지가 있습니다.
- Potato 설치와 실행과 작업 배포:
potato deploy의 전체 수명 주기 - AWS: Lightsail, EC2, ECS Express와 각각에 필요한 IAM 권한
- Jetstream2와 OpenStack: 할당을 신청하는 방법 포함
- Hetzner, Vultr, Linode와 DigitalOcean
- Fly.io, Railway, Render, Heroku, HuggingFace Spaces
- 백업, 주석 되찾기, 배포 버튼
- 임시 URL로 작업 공유하기
이 사이트에서는 프로덕션 설정이 직접 관리하는 서버에서 gunicorn과 Docker로 Potato를 실행하는 방법을, 리버스 프록시가 URL 경로 접두사 아래에서 Potato를 제공하는 방법을 다룹니다.