Potato をローカルまたはクラウドで実行する

Potatoは2つのコマンドで自分のマシン上で動き、potato deployを使えば、コマンドをもう1つ実行するだけで同じ設定をクラウドホストに載せられます。このページでは、よくある状況ごとに適したホストを示し、そのためのコマンドを紹介します。以下のクラウドのデプロイ先には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を使うと、選んだサイズの見積もりが表示されます。

AWSでは、--provider awsが作成するLightsailを使ってください。定額料金にIPv4アドレスと60 GBのディスクが含まれ、必要な権限はlightsail:*だけなので、権限を絞ったIAMロールでも動作します。EC2のデプロイ先（aws-ec2）は、Lightsailが無効になっているアカウント向けです。

Jetstream2は、NSFが資金を提供している研究用クラウドです。ACCESSの割り当てがあれば費用はかからず、各インスタンスにDNS名が付くため、アノテーターには通常のホスト名と通常の証明書が表示されます。デフォルトのインスタンスは1時間あたり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.yaml

Ctrl-Cを押したとき、ノートPCがスリープしたとき、ネットワークが変わったときにリンクは使えなくなり、アノテーションは自分のディスクに残ります。トンネルを開く前に、potato shareはサインインできる人を表示して確認を求めます。トンネルを開くと、設定のサインインルールがリンクを知っている全員に適用されるためです。一部の大学ネットワークはtrycloudflare.comのリンクをブロックしますが、--backend tailscaleを使えばこのブロックを避けられます。パイロットや研究室のミーティングにはpotato shareを使い、参加者が翌日に戻ってくる可能性のあるタスクにはクラウドホストを使ってください。

コマンド1つでクラウドにデプロイする

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のクラウドデプロイ先にデプロイできます。最も大きな違いは再起動後にディスクが残るかどうかで、これによって、次のセクションで説明するバックアップがデプロイに必要かどうかが決まります。

7つの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はプロジェクトをバックアップ用のストレージから取得するため、3つとも--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-bucket

HerokuとECS Expressは、--demoでアノテーションを破棄してよいと宣言しない限り、--backupなしのデプロイを拒否します。復元ではアノテーションと一緒にアカウント一覧も戻るため、アノテーターは同じパスワードでサインインし、中断したところから続けられます。復元がディスク上にすでにあるアノテーションを上書きすることはありません。--s3-endpointを使うと、S3バックアップをCloudflare R2、Backblaze B2、MinIO、大学のオブジェクトストアに送れます。バックアップはVMデプロイ先でも動作し、そこではデータの2つ目のコピーをサーバーの外に保持します。

potato deployを使わない場合は、設定のbackupブロックが、自分で運用するサーバー上で同じ役割を果たします。HuggingFaceとS3のクライアントを含むhosting extraをインストールし、サーバーの環境にHF_TOKENを設定して、既存の設定に次のブロックを追加します。

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: huggingface
      repo_id: lab/pilot-annotations

destroyの前にアノテーションを取得する

potato deploy pullは、デプロイが収集したものをすべてタイムスタンプ付きのディレクトリにダウンロードして、届いた内容を確認します。potato deploy destroyはサーバーを削除します。この順で実行してください。

potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroyは一度もpullされていないデプロイの削除を拒否し、ファイルが0件だった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パスのプレフィックスの下で提供する方法を説明しています。