Запуск Potato локально или в облаке

Potato запускается на вашей машине двумя командами, а potato deploy переносит ту же конфигурацию на облачный хост ещё одной. На этой странице каждой типичной ситуации сопоставлен хост и дана команда для неё. Облачные цели ниже требуют Potato 2.10.0 или новее: эта версия добавила AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode и OpenStack к целям DigitalOcean, Render и HuggingFace, которые были уже в 2.9.

Где запускать задачу

Подходящий хост зависит от того, как долго задача должна работать и кто за неё платит. Стоимость в таблице взята из оценок, которые Potato 2.10.0 печатает для размера по умолчанию у каждой цели, а --dry-run печатает оценку для выбранного вами размера.

На AWS используйте Lightsail: именно его создаёт --provider aws. В его фиксированную цену входят IPv4-адрес и диск на 60 GB, а нужны ему только lightsail:* и sts:GetCallerIdentity, так что он работает и под ограниченной ролью IAM. Цель EC2 (aws-ec2) предназначена для аккаунтов, где Lightsail отключён.

Исследовательское облако Jetstream2 финансирует NSF. При выделении ACCESS оно ничего не стоит, и каждый экземпляр получает DNS-имя, так что разметчики видят обычное имя хоста с обычным сертификатом. Экземпляр по умолчанию расходует 2 сервисные единицы в час, около 17 500 за год, поэтому удалите его, когда исследование закончится.

Potato на своей машине

Potato нужен Python 3.9 или новее. Установите его и запустите задачу:

pip install potato-annotation
potato start myproject/config.yaml -p 8000

Задача доступна по адресу http://localhost:8000, и больше никто до неё не достучится. potato start читает конфигурацию и файлы данных там, где они лежат, поэтому перезапуск подхватывает правку. Это делает его командой для работы, пока вы пишете задачу. На странице Быстрый старт создаётся первая конфигурация, а на странице Установка описаны необязательные дополнения и виртуальные окружения.

Опубликованному Docker-образу Python на хосте не нужен. В нём есть Potato и его зависимости, а папка проекта с config.yaml и данными монтируется в /app:

docker run -p 8000:7860 -v "$PWD/myproject:/app" ghcr.io/davidjurgens/potato:latest

Контейнер слушает порт 7860, который команда отображает на порт 8000 вашей машины. На странице Production-настройка описаны теги образа, его переменные окружения и ошибка владельца файлов, о которой сообщают хосты на Linux.

Временная публичная ссылка через potato share

potato share запускает задачу и открывает её по публичной ссылке HTTPS, пока работает команда. Ей нужен клиент туннеля, и она использует cloudflared, Tailscale или ngrok, в таком порядке, смотря что установлено:

brew install cloudflared
potato share myproject/config.yaml

Ссылка перестаёт работать, когда вы нажимаете Ctrl-C, когда ноутбук засыпает или когда меняется сеть, а разметка остаётся на вашем диске. Перед тем как открыть туннель, potato share печатает, кто сможет войти, и просит подтверждения, потому что после этого правила входа из конфигурации действуют для всех, у кого есть ссылка. Некоторые университетские сети блокируют ссылки trycloudflare.com, и --backend tailscale обходит эту блокировку. Используйте potato share для пилота или лабораторного семинара, а облачный хост для любой задачи, к которой участник может вернуться на следующий день.

Развёртывание в облаке одной командой

potato deploy up берёт уже имеющуюся у вас конфигурацию, создаёт сервер, получает сертификат HTTPS, загружает проект, запускает задачу и печатает URL. Установите дополнение для своей цели и посмотрите план, прежде чем его выполнять:

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
pip install 'potato-annotation[huggingface]'       # Hugging Face Spaces
 
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.

Тринадцать облачных целей

Potato 2.10.0 развёртывает задачи на тринадцать облачных целей. Сильнее всего они различаются тем, переживает ли диск перезапуск, и от этого зависит, нужна ли развёртыванию резервная копия, описанная в следующем разделе.

Семь целей с виртуальными машинами (aws, aws-ec2, openstack, hetzner, vultr, linode и digitalocean) настраиваются одинаково. Каждая получает ключ развёртывания, сгенерированный для этого развёртывания, файрвол, открывающий только порты 22, 80 и 443, Caddy с сертификатом Let's Encrypt и Potato в виде службы systemd, и potato deploy logs и pull работают на всех. Fly, Railway, Render и ECS Express запускают опубликованный образ и скачивают ваш проект при старте контейнера. Railway, Render и ECS Express берут его из хранилища резервных копий, поэтому всем трём нужен --backup, и сервису Railway или Render с диском он тоже нужен. На Fly проект меньше 512 KB передаётся внутри конфигурации Machine и хранилища не требует.

Четыре пошаговых руководства охватывают шесть целей, от настройки учётных данных до выгрузки данных: AWS Lightsail, Jetstream2, Hetzner, Vultr и Linode и Hugging Face Spaces.

Google Cloud Run, Azure Container Apps и AWS App Runner целями не являются. Хранилище, которое предлагают Cloud Run и Azure Container Apps, не может надёжно держать базу данных SQLite, а App Runner закрылся для новых клиентов 30 апреля 2026 года. На Azure подойдёт виртуальная машина с Docker-образом.

Резервные копии для хостов, которые стирают диск

На Heroku, ECS Express, бесплатном тарифе Render и HuggingFace Spaces диск стирается при перезапуске сервера. --backup каждые пять минут копирует результаты разметки и снимки баз данных проекта в датасет 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 не развернёт задачу без --backup, если только --demo не объявляет разметку одноразовой. Цель Hugging Face создаёт свой приватный датасет для резервной копии и без этого флага, а --demo его пропускает. ECS Express, Render, Railway и Fly всегда требуют --backup, потому что проект попадает к ним через хранилище резервных копий. Вместе с разметкой восстанавливается и список учётных записей, так что разметчики входят с прежними паролями и продолжают с того места, где остановились, а разметку, которая уже лежит на диске, восстановление никогда не перезаписывает. --s3-endpoint отправляет резервную копию S3 в Cloudflare R2, Backblaze B2, MinIO или университетское объектное хранилище. Резервное копирование работает и на целях с виртуальными машинами, где оно держит вторую копию данных за пределами сервера.

Вне potato deploy ту же работу на сервере, которым вы управляете сами, выполняет блок backup в конфигурации. Установите дополнение hosting, в котором есть клиенты HuggingFace и S3, задайте 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 отказывается удалять развёртывание, которое ни разу не выгружали, и выгрузка, не вернувшая ни одного файла, не считается. Выгрузка копирует project.sqlite через команду резервного копирования SQLite, а не как файл, потому что в копии файла базы данных в режиме WAL может не оказаться последних изменений. На Fly и Railway удаление приложения удаляет и его том, так что выгрузка остаётся единственной копией, если вы не запускали ещё и резервное копирование.

Кнопки развёртывания для чужих аккаунтов

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 записывает шаблон CloudFormation «Launch Stack», который создаёт экземпляр Lightsail, а для railway команда печатает шаги, потому что Railway публикует шаблоны из своей панели управления. Ваш config.yaml не меняется: команда записывает рядом копию potato.deploy.yaml с применёнными настройками развёртывания. Секреты в репозиторий не попадают. Heroku, Render и шаблон AWS генерируют ключи сессии и администратора во время развёртывания. Кнопкам Heroku, Render и AWS нужен --backup, и учётные данные для него указывает тот, кто развёртывает. В Potato 2.11.1 и более ранних версиях команда записывает названный вами датасет или бакет в файлы, которые попадают в репозиторий, поэтому каждое развёртывание с этой кнопки делает резервные копии в одно и то же место и восстанавливается из него при старте. Давайте кнопку только тем, кто должен делить это хранилище, а все остальные пусть сделают форк репозитория и создадут кнопку со своим датасетом или бакетом.

Что почитать дальше

Для каждой цели в документации Potato есть своя страница:

• Установка и запуск Potato и Развёртывание задачи: весь жизненный цикл potato deploy
• AWS: Lightsail, EC2 и ECS Express с правами IAM, которые нужны каждой цели
• Jetstream2 и OpenStack, включая то, как запросить выделение
• Hetzner, Vultr и Linode и DigitalOcean
• Fly.io, Railway, Render, Heroku и HuggingFace Spaces
• Резервные копии, Как получить разметку обратно и Кнопки развёртывания
• Как открыть задачу по временному URL

На этом сайте страница Production-настройка описывает запуск Potato под gunicorn и в Docker на сервере, которым вы управляете, а страница Обратный прокси описывает, как открыть его по URL с префиксом пути.