IT チーム向け Potato サーバー要件

Potato は、アノテーション研究のためのセルフホスト型 Web アプリケーションです。1つの Potato プロセスが1つの研究を配信し、すべてのアノテーションを研究のフォルダー内のファイルと SQLite データベースに保存します。HTTPS にはプロセスの前段にリバースプロキシが必要です。デフォルトのインストールは外部サービスに何も送信せず、データがサーバーの外に出るのは、研究の設定が有効にした機能を通じてだけです。

このページは、大学、病院、企業でサーバーを運用する担当者に向けて書かれています。研究の運用を依頼したい研究者は、このページをそのまま、プロジェクトフォルダーと次のセクションに挙げた回答と一緒に送ることができます。IT チームなしで研究者が取れる経路については、Potato の研究をオンラインに公開する で説明しています。

研究チームからの情報

研究チームは、Study Designer が Download project (.zip) としてエクスポートするプロジェクトフォルダーを送ります。このフォルダーには、研究の設定である config.yaml と、その設定が指定するデータファイルが入っています。フォルダーに加えて、研究チームは次の質問に答えます。

• アノテーターは何人参加し、機関のアカウントでサインインしますか。それとも研究者が一覧にしたユーザー名でサインインしますか。
• 研究はいつ始まり、いつ終わりますか。
• 項目や回答には個人情報や機微な情報が含まれますか。研究はどの倫理審査の承認のもとで行われますか。
• 設定は、項目をモデルプロバイダーに送信する AI 機能を使っていますか。config.yaml の ai_support、chat_support、solo_mode などのブロックが、そうした機能を示します。

ソフトウェア

Potato は Flask 上に構築された Python の Web アプリケーションです。最も簡単なインストール方法は、公開されている Docker イメージ ghcr.io/davidjurgens/potato です。このイメージは linux/amd64 と linux/arm64 向けにビルドされています。イメージは約 900 MB で、Python 3.11 を使い、権限のないユーザー potato（uid 1000）として gunicorn で動作し、ポート 7860 で待ち受けます。プロジェクトフォルダーは /app にマウントされます。

docker run -d --name potato-study --restart unless-stopped \
  -p 127.0.0.1:8000:7860 \
  -v /srv/potato/my-study:/app \
  -e POTATO_SECRET_KEY="$(openssl rand -hex 32)" \
  ghcr.io/davidjurgens/potato:2.14.0

このコマンドは、研究をホストのループバックインターフェイスのポート 8000 にだけ公開します。そのため、リバースプロキシが唯一の入口になります。latest タグは Potato の開発ブランチに追従するため、研究ではバージョンタグを固定してください。POTATO_SECRET_KEY は一度だけ生成して値を保管してください。起動のたびに新しいキーにすると、再起動のたびにすべてのアノテーターがログアウトされるためです。/app が uid 1000 で書き込めない場合、コンテナは起動しません。コンテナは --user "$(id -u):$(id -g)" を付けて実行するか、フォルダーを uid 1000 に引き渡してください。イメージのタグと環境変数については、Docker で Potato を実行する で説明しています。

Docker を使わない場合、Potato は Python 3.9 以降で pip install potato-annotation を使って PyPI からインストールできます。バックアップとシングルサインオンには hosting エクストラを、SAML サインインには saml エクストラを追加してください。後者は、システムの libxmlsec1 に対してビルドされます。potato start config.yaml は、応答のたびに接続を閉じる開発用サーバーを起動します。インターネット越しに作業するアノテーターのためには、本番セットアップ に示すとおり gunicorn の下で Potato を実行するか、potato start の前段にリバースプロキシを置いてください。

プロセスとワーカー数

Potato は、項目プール、割り当てキュー、すべてのアノテーターの状態を、1つのプロセスのメモリ内に保持しています。2つ目の gunicorn ワーカーや2つ目のレプリカは、この3つの別々のコピーを持ち、最初のプロセスがすでに割り当てた項目を配り、最初のプロセスの保存を上書きします。そのため、イメージは GUNICORN_WORKERS が 1 を超えると起動しません。同時処理を増やすには、GUNICORN_THREADS をデフォルトの 8 から増やしてください。Potato 自身の Docker ドキュメントでは、8 スレッドは、一般的な研究で同時に作業する数十人のアノテーターに相当するとされています。複数の研究を実行する場合は、フォルダーとポートをそれぞれ別にした複数のコンテナとして実行してください。

サーバーのサイズ

メモリ使用量は項目数に応じて増えます。Potato の測定では、1項目あたり 0.9〜1.4 KB のメモリを使い、Potato の参照データセットでは、サーバーは約 365 MB を使用しました。Potato 独自のクラウドコマンドである potato deploy は、ほとんどのホストで 1〜2 vCPU、メモリ 2 GB のマシンを選びます。これは妥当な出発点のサイズです。

ディスクは永続的で書き込み可能である必要があり、データファイル、項目に含まれるメディアファイル、アノテーションを置く容量が必要です。再起動時にディスクが消去されるコンテナは、後述の組み込みバックアップが有効でない限り、すべてのアノテーションを失います。

ネットワークアクセスと HTTPS

Potato は、nginx、Apache、Caddy などのリバースプロキシを通して公開してください。プロキシが TLS 証明書を保持し、コンテナのポートにリクエストを転送します。インターネットに開放する必要があるのは、ポート 443 と、リダイレクトと証明書の更新のためのポート 80 だけです。https://host.example.edu/my-study/ のような URL パスの下で Potato を配信する方法は、リバースプロキシ に示されています。X-Forwarded-Prefix ヘッダーを付けた POTATO_PROXY_FIX=1 か、POTATO_URL_PREFIX を使います。ライブエージェントビューアーは Server-Sent Events でストリーミングします。研究でこれらのビューアーを使う場合は、/api/ ロケーションのプロキシバッファリングをオフにしてください。

GET /health は認証が不要で、サーバーの準備ができると {"status": "ok"} を返し、サーバーがまだデータを読み込んでいる間は 503 を返します。ロードバランサーや監視のチェックは、このルートに向けてください。

Potato は、デフォルトでは外向きのネットワークアクセスを必要としません。アノテーターのブラウザーが読み込むスクリプト、スタイルシート、フォントは、サーバー自身から提供されます。デフォルトのインストールをオフラインに保つ仕組みは、エアギャップとオフラインのデプロイ に挙げられています。外向きのアクセスが必要になるのは、設定が有効にした機能だけです。

• AI 機能は、設定が指定するモデルエンドポイントを呼び出します。ただし、エンドポイントが Ollama のようなローカルのモデルサーバーである場合を除きます。
• バックアップは、設定が指定する Hugging Face データセットまたは S3 バケットに書き込みます。
• シングルサインオンは、IDプロバイダーに接続します。
• リモートデータソースは、設定が指定するバケットまたはデータベースから読み取ります。
• URL でメディアにリンクする項目では、アノテーターのブラウザーがその URL からメディアを取得します。

Potato が書き込むファイル

Potato はすべてを研究のフォルダーに書き込みます。

このため、1つのディレクトリに研究のすべてが入ります。output_annotation_dir は config.yaml の設定で、Study Designer はこの値を output に設定します。

バックアップ

プロジェクトフォルダーを毎晩バックアップすれば、アノテーションファイルとアカウント一覧をカバーできます。2つの SQLite ファイルは、ファイルとしてではなく SQLite 自身のバックアップコマンドでコピーしてください。WAL モードのデータベースのファイルコピーは、壊れていたり、最近の書き込みが抜けていたりすることがあるためです。

sqlite3 /srv/potato/my-study/project.sqlite ".backup /backups/my-study/project.sqlite"

Potato の組み込みバックアップは、アノテーション出力とデータベースのスナップショットを、5分ごとに S3 互換バケットまたは非公開の Hugging Face データセットにコピーします。起動時にディスクが空であれば、バックアップはバケットから復元し、すでにディスクにあるアノテーションを上書きすることはありません。次のブロックは、コピーを大学のオブジェクトストアに送ります。このブロックを研究の config.yaml に追加し、コンテナの環境に POTATO_S3_ACCESS_KEY_ID と POTATO_S3_SECRET_ACCESS_KEY を設定してください。

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: s3
      bucket: research-backups
      prefix: potato/my-study
      endpoint_url: https://s3.example.edu

公開されているイメージには、バックアップ用のクライアントが含まれています。pip でインストールする場合は、hosting エクストラが必要です。

サインインの選択肢

Potato は、アノテーターがサインインする方法を複数サポートしており、config.yaml で設定します。

パスワードは、PBKDF2-SHA256、100,000 回の反復、ユーザーごとのソルトでハッシュ化されます。忘れたパスワードは、Potato が画面に表示する1回限りのリンクでリセットし、Potato はメールを送信しません。TLS を終端するプロキシの背後では、SAML の sp_base_url を公開アドレスに設定してください。設定しないと、IDプロバイダーの応答が Potato の宛先チェックで失敗します。各方法の設定は、SSO と OAuth、パスワード管理、クラウドソーシング統合 にあります。

管理者アクセス

/admin の管理ダッシュボードは、進捗、一致度、すべてのアノテーターの回答を表示し、結果をダウンロードできます。ダッシュボードは管理者キーで開きます。キーは POTATO_ADMIN_API_KEY で設定するか、最初の使用時に Potato がプロジェクトフォルダーに生成する admin_api_key.txt を使い、キーは所属機関が信頼する手段で研究者に渡してください。サーバーでは config.yaml の debug: false を維持してください。デバッグモードでは、ローカルからに見えるリクエストに対して管理ページがキーなしで開き、同じマシン上のプロキシは、すべてのリクエストをローカルに見せてしまうことがあるためです。

データ保護

Potato はセルフホスト型なので、アノテーション、アカウント一覧、項目は、自分で運用するサーバーに残ります。Potato には分析や利用状況の報告が含まれず、デフォルトのインストールは外向きの接続を行いません。データがサーバーの外に出るのは、ネットワークアクセスと HTTPS に挙げた機能だけで、いずれも研究の設定で有効にし、送信先を指定する必要があります。

研究の倫理審査の承認と照らして、次の3点を確認してください。

• アノテーションファイルは各アノテーターをユーザー名で識別するため、メールアドレスをユーザー名にすると、メールアドレスがデータに入ります。
• 研究のアンケートページは個人情報を収集することがあり、その回答は、アノテーターごとの同じファイルに入ります。
• 設定が項目をホスト型のモデルプロバイダーに送信する場合、項目はそのプロバイダーの利用規約のもとでサーバーの外に出ます。

研究が終了したら、研究チームは管理ダッシュボードから結果をダウンロードします。サーバー上のコピーをいつまで保持するかを研究チームと合意し、その日以降はプロジェクトフォルダーとバックアップ用のバケットを削除してください。

関連資料

• Docker で Potato を実行する - イメージのタグ、環境変数、ファイルの所有権
• 本番セットアップ - gunicorn、nginx、Apache、Docker Compose
• リバースプロキシ - URL パスの下で Potato を配信する
• エアギャップとオフラインのデプロイ - 外向きのアクセスがないネットワーク
• Potato の研究をオンラインに公開する - 同じプロセスを研究者の側から見たページ