تشغيل 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:*، لذا يعمل تحت دور 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 على جهازك. يغطي إعداد الإنتاج وسوم الصورة ومتغيرات البيئة الخاصة بها وخطأ ملكية الملفات الذي تبلّغ عنه مضيفات 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
 
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 ولا يحتاج إلى تخزين.

ليست 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 وECS Express النشر من دون --backup، إلا إذا أعلن --demo أن التعليقات قابلة للتخلص منها. وتعيد الاستعادة قائمة الحسابات مع التعليقات، فيسجّل المعلّقون الدخول بكلمات المرور نفسها ويكملون من حيث توقفوا، ولا تكتب الاستعادة أبدًا فوق تعليقات موجودة على القرص. ويرسل --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:

• تثبيت Potato وتشغيله ونشر مهمة، دورة حياة potato deploy الكاملة
• AWS: Lightsail وEC2 وECS Express، مع صلاحيات IAM التي يحتاجها كل منها
• Jetstream2 وOpenStack، بما في ذلك طريقة طلب تخصيص
• Hetzner وVultr وLinode وDigitalOcean
• Fly.io وRailway وRender وHeroku وHuggingFace Spaces
• النسخ الاحتياطي واستعادة التعليقات وأزرار النشر
• مشاركة مهمة على عنوان URL مؤقت

وعلى هذا الموقع، يغطي إعداد الإنتاج تشغيل Potato تحت gunicorn وDocker على خادم تديره بنفسك، ويغطي الوكيل العكسي تقديمه تحت بادئة مسار URL.