Executar o Potato localmente ou na nuvem

O Potato roda na sua própria máquina com dois comandos, e potato deploy coloca a mesma configuração em um host na nuvem com mais um. Esta página associa cada situação comum a um host e dá o comando para ela. Os destinos na nuvem abaixo exigem o Potato 2.10.0 ou posterior, que acrescentou AWS, Heroku, Fly, Railway, Hetzner, Vultr, Linode e OpenStack aos destinos DigitalOcean, Render e HuggingFace que a 2.9 já tinha.

Escolhendo onde executar uma tarefa

O host certo depende de quanto tempo a tarefa precisa ficar no ar e de quem paga por ela. Os custos da tabela são as estimativas que o Potato 2.10.0 exibe para o tamanho padrão de cada destino, e --dry-run exibe a estimativa para o tamanho que você escolher.

Na AWS, use o Lightsail, que é o que --provider aws cria. O preço fixo inclui o endereço IPv4 e um disco de 60 GB, e ele precisa apenas de permissões lightsail:*, então funciona sob uma função do IAM restrita. O destino EC2 (aws-ec2) é para contas em que o Lightsail está desativado.

O Jetstream2 é uma nuvem de pesquisa financiada pela NSF. Com uma alocação do ACCESS, ele não custa nada, e cada instância recebe um nome DNS, então os anotadores veem um nome de host comum com um certificado comum. A instância padrão consome 2 unidades de serviço por hora, cerca de 17.500 ao longo de um ano, então destrua-a quando o estudo terminar.

Executando o Potato na sua própria máquina

O Potato precisa do Python 3.9 ou mais recente. Instale-o e inicie uma tarefa:

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

A tarefa fica em http://localhost:8000, e ninguém mais consegue acessá-la. potato start lê os arquivos de configuração e de dados onde eles estão, então uma reinicialização incorpora uma edição, o que faz dele o comando a usar enquanto você escreve uma tarefa. O Início Rápido monta uma primeira configuração, e a página de Instalação cobre os extras opcionais e os ambientes virtuais.

A imagem Docker publicada dispensa Python no host. Ela contém o Potato e suas dependências, e a pasta do seu projeto, com o config.yaml e seus dados, é montada em /app:

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

O contêiner serve na porta 7860, que o comando mapeia para a 8000 na sua máquina. A Configuração de Produção cobre as tags da imagem, suas variáveis de ambiente e o erro de propriedade de arquivos que hosts Linux relatam.

Um link público temporário com potato share

potato share executa a tarefa e a coloca em um link HTTPS público enquanto o comando estiver rodando. Ele precisa de um cliente de túnel e usa cloudflared, Tailscale ou ngrok, nessa ordem, o que estiver instalado:

brew install cloudflared
potato share myproject/config.yaml

O link para de funcionar quando você pressiona Ctrl-C, quando o notebook entra em suspensão ou quando a rede muda, e as anotações ficam no seu próprio disco. Antes de abrir o túnel, potato share exibe quem poderá fazer login e pede sua confirmação, porque a partir daí as regras de login da configuração valem para qualquer pessoa com o link. Algumas redes universitárias bloqueiam links trycloudflare.com, e --backend tailscale contorna o bloqueio. Use potato share para um piloto ou uma reunião do laboratório, e um host na nuvem para qualquer tarefa à qual um participante possa voltar no dia seguinte.

Implantando na nuvem com um comando

potato deploy up recebe a configuração que você já tem, cria o servidor, obtém um certificado HTTPS, envia o projeto, inicia a tarefa e exibe a URL. Instale o extra do seu destino e examine o plano antes de executá-lo:

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 não precisa de conta. Ele exibe cada recurso que a implantação criaria, o custo mensal e qualquer opção da sua configuração que seja arriscada em um servidor público. Sem --dry-run, o Potato mostra o mesmo plano e espera sua confirmação antes de criar qualquer coisa. Executar up de novo na mesma configuração atualiza a implantação existente, e depois do primeiro up, status, logs, pull e destroy dispensam --provider.

Os treze destinos na nuvem

O Potato 2.10.0 implanta em treze destinos na nuvem. A maior diferença entre eles é se o disco sobrevive a uma reinicialização, o que decide se uma implantação precisa do backup descrito na próxima seção.

Os sete destinos de VM (aws, aws-ec2, openstack, hetzner, vultr, linode e digitalocean) são configurados da mesma forma. Cada um recebe uma chave de implantação gerada para aquela implantação, um firewall que abre apenas as portas 22, 80 e 443, o Caddy com um certificado Let's Encrypt e o Potato como serviço do systemd, e potato deploy logs e pull funcionam em todos eles. Fly, Railway, Render e ECS Express executam a imagem publicada e baixam seu projeto quando o contêiner inicia. Railway, Render e ECS Express o buscam no armazenamento do backup, então os três precisam de --backup, e um serviço do Railway ou do Render com disco também precisa. No Fly, um projeto com menos de 512 KB viaja dentro da configuração da Machine e não precisa de armazenamento.

Google Cloud Run, Azure Container Apps e AWS App Runner não são destinos. O armazenamento que o Cloud Run e o Azure Container Apps oferecem não consegue guardar um banco de dados SQLite com segurança, e o App Runner deixou de aceitar novos clientes em 30 de abril de 2026. No Azure, uma VM executando a imagem Docker funciona.

Backups para hosts que apagam o disco

No Heroku, no ECS Express, no plano gratuito do Render e nos HuggingFace Spaces, o disco é apagado quando o servidor reinicia. --backup copia a saída das anotações e snapshots dos bancos de dados do projeto para um dataset do HuggingFace ou um bucket S3 a cada cinco minutos, e os restaura quando um servidor inicia com o disco vazio:

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 e ECS Express se recusam a implantar sem --backup, a menos que --demo declare as anotações descartáveis. A restauração traz de volta a lista de contas junto com as anotações, então os anotadores fazem login com as mesmas senhas e continuam de onde pararam, e ela nunca sobrescreve anotações que já estão no disco. --s3-endpoint envia o backup S3 para Cloudflare R2, Backblaze B2, MinIO ou um armazenamento de objetos da universidade. O backup também funciona nos destinos de VM, onde mantém uma segunda cópia dos dados fora do servidor.

Fora do potato deploy, um bloco backup na configuração faz o mesmo trabalho em um servidor que você mesmo mantém. Instale o extra hosting, que fornece os clientes do HuggingFace e do S3, defina HF_TOKEN no ambiente do servidor e adicione este bloco a uma configuração existente:

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

Baixando as anotações antes do destroy

potato deploy pull baixa tudo o que uma implantação coletou para um diretório com data e hora e verifica o que chegou, e potato deploy destroy remove o servidor. Execute-os nessa ordem:

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

destroy se recusa a remover uma implantação da qual nunca foi feito um pull, e um pull que retorna zero arquivos não conta. O pull copia o project.sqlite pelo comando de backup do SQLite, e não como arquivo, porque a cópia de arquivo de um banco de dados em modo WAL pode deixar de fora trabalho recente. No Fly e no Railway, destruir o app apaga o volume dele, então o pull é a única cópia, a menos que você também tenha rodado um backup.

Botões de implantação para contas de outras pessoas

potato deploy button grava os arquivos que uma plataforma de hospedagem lê para oferecer uma implantação com um clique a partir do seu repositório git, e exibe o selo para o README. Use-o quando colaboradores, estudantes ou outro laboratório devem executar sua tarefa nas próprias contas:

potato deploy button studies/pilot/config.yaml --target heroku \
    --backup hf --hf-backup-repo lab/pilot-annotations

Os destinos são heroku, render, aws e railway. O destino aws grava um template "Launch Stack" do CloudFormation que cria uma instância do Lightsail, e para railway o comando exibe os passos, porque o Railway publica templates pelo próprio painel. Seu config.yaml não é alterado, e o comando grava uma cópia ao lado dele, potato.deploy.yaml, com as configurações de implantação aplicadas. Nenhum segredo vai para o repositório. Heroku, Render e o template da AWS geram as chaves de sessão e de administrador no momento da implantação. Os botões do Heroku, do Render e da AWS exigem --backup, e quem faz a implantação fornece as credenciais dele.

Leitura adicional

Cada destino tem sua própria página na documentação do Potato:

• Instalar e executar o Potato e Implantar uma tarefa, o ciclo de vida completo do potato deploy
• AWS: Lightsail, EC2 e ECS Express, com as permissões do IAM de que cada um precisa
• Jetstream2 e OpenStack, incluindo como solicitar uma alocação
• Hetzner, Vultr e Linode e DigitalOcean
• Fly.io, Railway, Render, Heroku e HuggingFace Spaces
• Backups, Recuperar as anotações e Botões de implantação
• Compartilhar uma tarefa em uma URL temporária

Neste site, a Configuração de Produção cobre a execução do Potato com gunicorn e Docker em um servidor que você administra, e o Proxy reverso cobre como servi-lo sob um prefixo de caminho de URL.