Requisitos de servidor do Potato para a sua equipe de TI

O Potato é uma aplicação web auto-hospedada para estudos de anotação. Um processo do Potato serve um estudo, guarda todas as anotações em arquivos e bancos SQLite dentro da pasta do estudo e precisa de um proxy reverso na frente do processo para o HTTPS. Uma instalação padrão não envia nada a serviços externos, e os dados saem do servidor somente por recursos que a configuração do estudo ativa.

Esta página é escrita para as pessoas que administram servidores em uma universidade, um hospital ou uma empresa. Um pesquisador que quer um estudo hospedado pode enviar a página sem alterações, junto com a pasta do projeto e as respostas listadas na próxima seção. Coloque seu estudo do Potato no ar cobre os caminhos que um pesquisador pode seguir sem uma equipe de TI.

Informações da equipe de pesquisa

A equipe de pesquisa envia a pasta do projeto, que o Study Designer exporta como Download project (.zip). A pasta contém o config.yaml, a configuração do estudo, e os arquivos de dados que a configuração nomeia. Junto com a pasta, a equipe de pesquisa responde a estas perguntas:

• Quantos anotadores participam, e eles entram com contas institucionais ou com nomes de usuário que o pesquisador lista?
• Quando o estudo começa e termina?
• Os itens ou as respostas contêm informações pessoais ou sensíveis, e sob qual aprovação ética o estudo roda?
• A configuração usa recursos de IA que enviam itens a um provedor de modelos? Blocos como ai_support, chat_support e solo_mode no config.yaml indicam esses recursos.

Software

O Potato é uma aplicação web em Python construída sobre o Flask. A instalação mais simples é a imagem Docker publicada, ghcr.io/davidjurgens/potato, construída para linux/amd64 e linux/arm64. A imagem tem cerca de 900 MB, roda o Python 3.11 sob o gunicorn como o usuário sem privilégios potato (uid 1000) e escuta na porta 7860. A pasta do projeto é montada em /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

O comando publica o estudo somente na porta 8000 da interface de loopback do host. O proxy reverso é, então, o único caminho de entrada. A tag latest acompanha o branch de desenvolvimento do Potato, e um estudo deve fixar uma tag de versão. Gere POTATO_SECRET_KEY uma vez e guarde o valor, porque uma chave nova a cada inicialização desconecta todos os anotadores a cada reinicialização. O contêiner se recusa a iniciar quando /app não é gravável pelo uid 1000. Execute o contêiner com --user "$(id -u):$(id -g)" ou entregue a pasta ao uid 1000. Executar o Potato no Docker cobre as tags e as variáveis de ambiente da imagem.

Sem o Docker, o Potato se instala a partir do PyPI no Python 3.9 ou mais recente com pip install potato-annotation. Adicione o extra hosting para backups e login único, e o extra saml para o login SAML, que é compilado com a libxmlsec1 do sistema. potato start config.yaml roda um servidor de desenvolvimento que fecha a conexão após cada resposta. Para anotadores que trabalham pela internet, execute o Potato sob o gunicorn como mostra Configuração de Produção, ou coloque um proxy reverso na frente de potato start.

Processo e número de workers

O Potato mantém o pool de itens, a fila de atribuição e o estado de cada anotador na memória de um único processo. Um segundo worker do gunicorn ou uma segunda réplica tem uma cópia separada dos três, distribui itens que o primeiro processo já atribuiu e sobrescreve os salvamentos do primeiro processo. Por isso, a imagem se recusa a iniciar com GUNICORN_WORKERS acima de 1. Para mais concorrência, aumente GUNICORN_THREADS a partir do padrão de 8. A própria documentação de Docker do Potato indica que oito threads atendem às dezenas de anotadores simultâneos que um estudo típico tem. Execute vários estudos como vários contêineres, cada contêiner com uma pasta e uma porta separadas.

Tamanho do servidor

A memória cresce com o número de itens. As medições do Potato indicam de 0,9 a 1,4 KB de memória por item, e o servidor no conjunto de dados de referência do Potato usou cerca de 365 MB. potato deploy, o comando de nuvem do próprio Potato, escolhe uma máquina com 1 ou 2 vCPUs e 2 GB de memória na maioria dos hosts, o que é um tamanho inicial razoável.

O disco precisa ser persistente e gravável, e precisa ter espaço para os arquivos de dados, para os arquivos de mídia que os itens incluem e para as anotações. Um contêiner cujo disco é apagado na reinicialização perde todas as anotações, a menos que o backup embutido descrito abaixo esteja ligado.

Acesso de rede e HTTPS

Exponha o Potato por meio de um proxy reverso como nginx, Apache ou Caddy. O proxy guarda o certificado TLS e encaminha as requisições para a porta do contêiner. Somente as portas 443, e a 80 para redirecionamentos e renovação de certificado, precisam estar abertas para a internet. Proxy reverso mostra como servir o Potato sob um caminho de URL como https://host.example.edu/my-study/, com POTATO_PROXY_FIX=1 e um cabeçalho X-Forwarded-Prefix ou com POTATO_URL_PREFIX. Os visualizadores de agentes ao vivo transmitem por server-sent events. Desligue o buffering do proxy no local /api/ se o estudo usar esses visualizadores.

GET /health não exige autenticação e retorna {"status": "ok"} quando o servidor está pronto, e 503 enquanto o servidor ainda carrega os dados. Aponte um balanceador de carga ou uma verificação de monitoramento para essa rota.

O Potato não precisa de acesso de rede de saída por padrão. Os scripts, as folhas de estilo e as fontes que os navegadores dos anotadores carregam vêm do próprio servidor, e Implantação isolada e offline (air-gap) lista como o Potato mantém a instalação padrão offline. O acesso de saída é necessário somente para recursos que a configuração ativa:

• Os recursos de IA chamam o endpoint de modelo que a configuração nomeia, a menos que o endpoint seja um servidor de modelo local, como o Ollama.
• Os backups gravam no conjunto de dados do Hugging Face ou no bucket S3 que a configuração nomeia.
• O login único contata o provedor de identidade.
• As fontes de dados remotas leem do bucket ou do banco de dados que a configuração nomeia.
• Itens que apontam para mídia por URL fazem o navegador do anotador buscar a mídia nessa URL.

Arquivos que o Potato grava

O Potato grava tudo na pasta do estudo:

Um único diretório guarda, portanto, o estudo inteiro. output_annotation_dir é uma configuração do config.yaml, e o Study Designer define o valor como output.

Backups

Um backup noturno da pasta do projeto cobre os arquivos de anotação e a lista de contas. Copie os dois arquivos SQLite com o comando de backup do próprio SQLite, e não como arquivos, porque uma cópia de arquivo de um banco em modo WAL pode ficar corrompida ou perder gravações recentes:

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

O backup embutido do Potato copia a saída das anotações e snapshots dos bancos de dados para um bucket compatível com S3 ou para um conjunto de dados privado do Hugging Face a cada cinco minutos. Na inicialização, o backup restaura a partir do bucket quando o disco está vazio, e o backup nunca sobrescreve anotações que já estão no disco. O bloco abaixo envia a cópia a um armazenamento de objetos da universidade. Adicione o bloco ao config.yaml do estudo e defina POTATO_S3_ACCESS_KEY_ID e POTATO_S3_SECRET_ACCESS_KEY no ambiente do contêiner:

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

A imagem publicada inclui os clientes de backup. Uma instalação com pip precisa do extra hosting.

Opções de login

O Potato aceita várias formas de os anotadores entrarem, definidas no config.yaml:

As senhas passam por hash PBKDF2-SHA256 com 100.000 iterações e um sal por usuário. Uma senha esquecida é redefinida por um link de uso único que o Potato mostra na tela, e o Potato não envia e-mail. Atrás de um proxy que encerra o TLS, defina sp_base_url do SAML como o endereço público, ou a resposta do provedor de identidade falha na verificação de destino do Potato. Autenticação SSO e OAuth, Gerenciamento de Senhas e Integração com Crowdsourcing dão a configuração de cada método.

Acesso de administrador

O painel do administrador em /admin mostra o progresso, a concordância e as respostas de todos os anotadores, e baixa os resultados. O painel abre com uma chave de administrador. Defina a chave por POTATO_ADMIN_API_KEY, ou deixe o Potato gerar o admin_api_key.txt na pasta do projeto no primeiro uso, e passe a chave ao pesquisador por um canal em que a sua instituição confie. Mantenha debug: false no config.yaml em qualquer servidor, porque o modo de depuração abre as páginas de administração sem chave para requisições que parecem locais, e um proxy na mesma máquina pode fazer toda requisição parecer local.

Proteção de dados

O Potato é auto-hospedado, de modo que as anotações, a lista de contas e os itens ficam no servidor que você administra. O Potato não contém análise de uso nem relatórios de uso, e uma instalação padrão não faz conexões de saída. Os dados saem do servidor somente pelos recursos listados em Acesso de rede e HTTPS, cada um dos quais a configuração do estudo precisa ativar e para o qual precisa nomear um destino.

Confira três pontos com a aprovação ética do estudo:

• Os arquivos de anotação identificam cada anotador pelo nome de usuário, de modo que nomes de usuário que são endereços de e-mail colocam endereços de e-mail nos dados.
• As páginas de questionário de um estudo podem coletar informações pessoais, e as respostas ficam nos mesmos arquivos por anotador.
• Quando a configuração envia itens a um provedor de modelos hospedado, os itens saem do servidor sob os termos desse provedor.

Quando o estudo termina, a equipe de pesquisa baixa os resultados do painel do administrador. Combine com a equipe por quanto tempo a cópia do servidor é mantida e exclua a pasta do projeto e qualquer bucket de backup depois dessa data.

Leitura adicional

• Executar o Potato no Docker, para as tags da imagem, as variáveis de ambiente e a propriedade de arquivos
• Configuração de Produção, para gunicorn, nginx, Apache e Docker Compose
• Proxy reverso, para servir o Potato sob um caminho de URL
• Implantação isolada e offline (air-gap), para redes sem acesso de saída
• Coloque seu estudo do Potato no ar, o lado do pesquisador do mesmo processo