IT 팀을 위한 Potato 서버 요구 사항

Potato는 주석 연구를 위한 자체 호스팅 웹 애플리케이션입니다. Potato 프로세스 하나가 연구 하나를 제공하고, 모든 주석을 연구 폴더 안의 파일과 SQLite 데이터베이스에 보관하며, HTTPS를 위해 프로세스 앞에 리버스 프록시가 필요합니다. 기본 설치는 외부 서비스로 아무것도 보내지 않으며, 데이터는 연구의 설정이 켠 기능을 통해서만 서버를 떠납니다.

이 페이지는 대학, 병원, 기업에서 서버를 운영하는 사람들을 위해 쓰였습니다. 연구를 호스팅받으려는 연구자는 이 페이지를 그대로, 프로젝트 폴더와 다음 섹션에 나열된 답변과 함께 보낼 수 있습니다. IT 팀 없이 연구자가 택할 수 있는 경로는 Potato 연구를 온라인에 올리기가 다룹니다.

연구팀이 제공할 정보

연구팀은 Study Designer가 **Download project (.zip)**으로 내보내는 프로젝트 폴더를 보냅니다. 이 폴더에는 연구의 설정인 config.yaml과 설정이 이름을 부르는 데이터 파일이 들어 있습니다. 폴더와 함께 연구팀은 다음 질문에 답합니다.

• 주석자는 몇 명이 참여하며, 기관 계정으로 로그인합니까, 연구자가 목록으로 만든 사용자 이름으로 로그인합니까?
• 연구는 언제 시작하고 언제 끝납니까?
• 항목이나 답에 개인 정보나 민감한 정보가 들어 있으며, 연구는 어떤 윤리 승인을 따릅니까?
• 설정이 항목을 모델 공급자에게 보내는 AI 기능을 쓰고 있습니까? config.yaml의 ai_support, chat_support, solo_mode 같은 블록이 그런 기능을 나타냅니다.

소프트웨어

Potato는 Flask 기반의 Python 웹 애플리케이션입니다. 가장 간단한 설치는 게시된 Docker 이미지 ghcr.io/davidjurgens/potato이며, 이 이미지는 linux/amd64와 linux/arm64용으로 빌드됩니다. 이미지는 약 900 MB이고, 권한 없는 사용자 potato(uid 1000)로 gunicorn 아래에서 Python 3.11을 실행하며, 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를 쓰지 않으면 Python 3.9 이상에서 pip install potato-annotation으로 PyPI에서 Potato를 설치합니다. 백업과 싱글 사인온에는 hosting extra를, 시스템의 libxmlsec1을 기준으로 빌드되는 SAML 로그인에는 saml extra를 추가하십시오. potato start config.yaml은 응답마다 연결을 닫는 개발 서버를 실행합니다. 인터넷으로 작업하는 주석자를 위해서는 프로덕션 설정이 보여 주는 대로 gunicorn에서 Potato를 실행하거나, potato start 앞에 리버스 프록시를 두십시오.

프로세스와 워커 수

Potato는 항목 풀, 할당 대기열, 모든 주석자의 상태를 프로세스 하나의 메모리에 보관합니다. 두 번째 gunicorn 워커나 두 번째 레플리카는 이 셋의 사본을 따로 가지므로, 첫 번째 프로세스가 이미 할당한 항목을 내주고 첫 번째 프로세스의 저장 내용을 덮어씁니다. 그래서 이미지는 GUNICORN_WORKERS가 1을 넘으면 시작을 거부합니다. 동시성을 높이려면 GUNICORN_THREADS를 기본값 8에서 올리십시오. Potato의 Docker 문서는 스레드 여덟 개가 일반적인 연구의 동시 주석자 수십 명을 감당한다고 봅니다. 연구를 여러 개 운영한다면 컨테이너를 여러 개 두되, 컨테이너마다 폴더와 포트를 따로 쓰십시오.

서버 규모

메모리는 항목 수에 따라 늘어납니다. Potato의 측정으로는 항목 하나가 메모리에서 0.9에서 1.4 KB를 차지하며, Potato의 기준 데이터셋에서 서버는 약 365 MB를 썼습니다. Potato 자체의 클라우드 명령인 potato deploy는 대부분의 호스트에서 vCPU 1개 또는 2개와 메모리 2 GB의 머신을 고르며, 이 정도가 무난한 시작 크기입니다.

디스크는 영속적이고 쓸 수 있어야 하며, 데이터 파일, 항목에 포함된 미디어 파일, 주석을 담을 공간이 필요합니다. 재시작할 때 디스크가 지워지는 컨테이너는 아래에 설명하는 내장 백업을 켜지 않으면 모든 주석을 잃습니다.

네트워크 접근과 HTTPS

nginx, Apache, Caddy 같은 리버스 프록시로 Potato를 공개하십시오. 프록시가 TLS 인증서를 갖고 요청을 컨테이너의 포트로 전달합니다. 인터넷에 열어야 하는 포트는 443번과, 리디렉션과 인증서 갱신을 위한 80번뿐입니다. 리버스 프록시는 X-Forwarded-Prefix 헤더와 함께 쓰는 POTATO_PROXY_FIX=1이나 POTATO_URL_PREFIX를 통해 Potato를 https://host.example.edu/my-study/ 같은 URL 경로 아래에서 제공하는 방법을 보여 줍니다. 라이브 에이전트 뷰어는 서버 전송 이벤트로 스트리밍합니다. 연구가 이 뷰어를 쓴다면 /api/ 위치에서 프록시 버퍼링을 끄십시오.

GET /health는 인증이 필요 없으며 서버가 준비되면 {"status": "ok"}를 반환하고, 서버가 아직 데이터를 불러오는 중에는 503을 반환합니다. 로드 밸런서나 모니터링 점검이 이 경로를 가리키게 하십시오.

Potato는 기본적으로 외부로 나가는 네트워크 접근이 필요 없습니다. 주석자의 브라우저가 불러오는 스크립트, 스타일시트, 글꼴은 서버 자체에서 제공되며, Potato가 기본 설치를 오프라인으로 유지하는 방법은 에어갭 및 오프라인 배포에 나와 있습니다. 외부 접근은 설정이 켠 기능에만 필요합니다.

• AI 기능은 로컬 모델 서버(예: Ollama)가 아닌 한 설정이 지정한 모델 엔드포인트를 호출합니다.
• 백업은 설정이 지정한 Hugging Face 데이터셋이나 S3 버킷에 씁니다.
• 싱글 사인온은 ID 공급자에 접속합니다.
• 원격 데이터 소스는 설정이 지정한 버킷이나 데이터베이스에서 읽습니다.
• 미디어를 URL로 연결하는 항목은 주석자의 브라우저가 그 URL에서 미디어를 가져오게 합니다.

Potato가 쓰는 파일

Potato는 모든 것을 연구 폴더에 씁니다.

따라서 디렉터리 하나에 연구 전체가 들어 있습니다. output_annotation_dir은 config.yaml의 설정이며, Study Designer는 이 값을 output으로 설정합니다.

백업

프로젝트 폴더를 매일 밤 백업하면 주석 파일과 계정 목록이 포함됩니다. 두 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 extra가 필요합니다.

로그인 방식

Potato는 주석자가 로그인하는 방식을 여러 가지 지원하며 config.yaml에서 설정합니다.

비밀번호는 PBKDF2-SHA256으로 100,000회 반복하고 사용자마다 솔트를 두어 해시합니다. 잊어버린 비밀번호는 Potato가 화면에 보여 주는 일회용 링크로 재설정하며, 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에 나열된 기능을 통해서만 서버를 떠나며, 그 기능은 모두 연구의 설정이 켜고 대상을 지정해야 합니다.

연구의 윤리 승인과 대조해 세 가지를 확인하십시오.

• 주석 파일은 각 주석자를 사용자 이름으로 부르므로, 이메일 주소를 사용자 이름으로 쓰면 이메일 주소가 데이터에 들어갑니다.
• 연구의 설문 페이지는 개인 정보를 수집할 수 있고, 그 답은 같은 주석자별 파일에 있습니다.
• 설정이 항목을 호스팅 모델 공급자에게 보내면 항목은 그 공급자의 약관에 따라 서버를 떠납니다.

연구가 끝나면 연구팀이 관리자 대시보드에서 결과를 내려받습니다. 서버의 사본을 얼마 동안 보관할지 팀과 합의하고, 그 날짜가 지나면 프로젝트 폴더와 백업 버킷을 삭제하십시오.

더 읽을거리

• Docker로 Potato 실행하기, 이미지의 태그, 환경 변수, 파일 소유권
• 프로덕션 설정, gunicorn, nginx, Apache, Docker Compose
• 리버스 프록시, URL 경로 아래에서 Potato 제공하기
• 에어갭 및 오프라인 배포, 외부 접근이 없는 네트워크용
• Potato 연구를 온라인에 올리기, 같은 과정의 연구자 쪽