الطريق كله

تمر هذه الصفحة على الطريق كله مرة واحدة، بالترتيب الذي تتبعه، وتربط كل خطوة بالصفحة التي فيها تفاصيلها. تُشغَّل الأوامر من نسخة محلية من مستودع casty ما لم يُذكر أنها تُشغَّل «على المضيف».

0. قبل أن تبدأ

عبارة البذرة تتحكم في الحساب كله. استخدم حساب اختبار لهذا الدليل، ولا تلصق عبارة البذرة إلا في برامج من مطورين تثق بهم، وفضّل مفتاحًا تأذن به محفظتك: casty init --fid <fid>، ثم casty web، وتحت «you» اختر «add a key with your wallet».

تحتاج إلى:

• حساب Farcaster للاختبار: معرّفه fid، ووحدة تخزين واحدة على الأقل (إيجار التخزين)، ومحفظة تحمل العنوان المسجّل له الـ fid (أو، كبديل احتياطي، عبارة البذرة لذلك العنوان). يعرض casty whoami و casty storage كليهما بعد إعداد casty.
• مضيف للعقدة: حساب لدى Hetzner Cloud أو AWS يستأجر منه casty خادمًا، أو جهاز خاص بك بذاكرة 16 GB، و4 أنوية، و2 TB من القرص الحر، وDocker (عقدة في المنزل). يُحاسَب الخادم المستأجر وقرصه بسعة 2 TB حتى تحذفهما (الخطوة 9).
• على جهازك: ssh وcurl وjq، وزوج مفاتيح SSH، افتراضيًا ~/.ssh/id_ed25519. وإلى أن يصدر للمشروع إصدار، تحتاج أيضًا إلى Node.js 22.12 أو أحدث، لأن الخطوة 2 تبني العميل هنا حينئذٍ. على Windows، استخدم WSL2.
• الوقت: تنزّل المزامنة الأولى للعقدة لقطة بحجم عدة مئات من GB وتستغرق ساعات. لا يضيع شيء إن توقفت عن الانتظار؛ إذ يمكن إعادة تشغيل كل خطوة فتتابع من حيث كانت.

git clone https://github.com/castyfun/casty.git && cd casty
ls ~/.ssh/id_ed25519.pub || ssh-keygen -t ed25519   # a key to log in to the node with

1. أعطِ casty سحابة، أو مضيفًا

اضبط بيانات اعتماد مزوّد واحد؛ تقرؤها السكربتات من بيئتك ولا تكتبها في أي مكان (0. تجهيز مضيف).

export HCLOUD_TOKEN=<token>        # Hetzner: Cloud console, your project, Security, API tokens (read/write)
# or, for AWS: aws configure       # or AWS_PROFILE, or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

لجهاز لديك بالفعل، تخطَّ هذا ومرّر --host user@ip في الخطوة 2.

اقرأ ما سيفعله التشغيل قبل إنشاء أي شيء؛ ولا يحتاج التشغيل التجريبي إلى بيانات اعتماد:

./scripts/deploy.sh --dry-run -- --provider hetzner

يطبع كل أمر للمزوّد وكل أمر SSH في سطر DRY: ولا ينشئ شيئًا.

2. شغّله

بأمر واحد

./scripts/deploy.sh --fid <fid>

يشغّل هذا الخطوات الثلاث أدناه بالترتيب ويتوقف عند أول خطوة تفشل، برمز خروج تلك الخطوة. شغّل الأمر نفسه مجددًا للمتابعة: تستغرق المزامنة الأولى ساعات، والضغط على Ctrl-C أثناءها لا يُضيع شيئًا. أضف --domain <name> (أو --tailscale) لتضع الصفحة على المضيف أيضًا، الخطوة 6. بدون --fid، تطلب الخطوة 2c عبارة البذرة بدلًا من ذلك.

ما تطلبه منك كل خطوة:

• مضيف (0-provision.sh): يطبع ما سينشئه وما سيُحاسَب عليه، ولا يتابع إلا بعد أن تكتب اسم الخادم مجددًا (--yes يتخطى السؤال). يكتب node.env، الذي تقرؤه كل خطوة لاحقة ويحتاج إليه حذف العقدة: احتفظ به. مع --host user@ip لا يُنشأ شيء؛ ويُفحص المضيف عبر SSH.
• العقدة (1-node.sh): لا شيء تجيب عنه. يفحص المضيف (الذاكرة، والقرص، وDocker، والساعة)، ويشغّل Snapchain، ويطبع تقدّم المزامنة، ويفتح نفق SSH إلى 127.0.0.1:3381 بعد أن تلحق العقدة بالشبكة.
• العميل (2-client.sh): مع --fid، لا شيء؛ يُعَدّ casty لمعرّفك fid دون مفتاح بعد، وتُقرأ التغذية. وبدونه، كلمة مرور لمخزن المفاتيح (مرتين)، ثم عبارة البذرة، في مطالبة مخفية.

أو خطوة بخطوة

الشيء نفسه، خطوة في كل مرة:

./scripts/0-provision.sh             # a: a server, a 2 TB volume and a firewall; or --host user@ip
./scripts/1-node.sh                  # b: the read node, the wait for its sync, the tunnel
./scripts/2-client.sh --fid <fid>    # c: ./bin/casty, set up for your fid; the seed phrase path without --fid

أثناء مزامنة العقدة، يعرض ./scripts/1-node.sh status مقدار تأخر كل شريحة، و ينتظر ./scripts/1-node.sh status --wait حتى تكتمل المزامنة. التفاصيل: 1. تشغيل عقدة القراءة، 2. تثبيت العميل.

3. أضف مفتاح تطبيق

يكتب casty بمفتاح تطبيق: مفتاح Ed25519 يأذن به عنوان الحفظ (custody address) لمعرّفك fid، ويُضاف برسالة KEY_ADD بلا رسوم غاز عبر عقدتك، دون معاملة ودون رسوم غاز (عنوان الحفظ ومفاتيح التطبيقات).

بمحفظتك

./bin/casty web

1. يطلب casty web كلمة مرور لمخزن المفاتيح الذي يوشك أن ينشئه، مرتين، ويطبع رابطًا فيه رمز. افتحه في متصفح فيه محفظتك (إضافة مثل MetaMask).
2. تحت «you»، اختر «add a key with your wallet».
3. تُسأل المحفظة عن حسابها؛ اختر الحساب المسجّل له الـ fid. إن كانت على سلسلة أخرى، تُطلب منها الانتقال إلى Ethereum mainnet، وهذا لا يكلّف شيئًا.
4. وقّع الطلبين اللذين تعرضهما المحفظة: طلب المفتاح، ثم إضافة المفتاح.
5. تتحقق الصفحة من التوقيعين، وترسل KEY_ADD عبر عقدتك، وتنتظر حتى تُدرج العقدة المفتاح، وتخزّنه مشفرًا في ~/.config/casty/keys.enc.json.

على هاتف محفظته تطبيق، شغّل ./bin/casty web --listen 0.0.0.0:3390 (أو استخدم الصفحة على المضيف، الخطوة 6)، وافتح الصفحة على الهاتف، وتحت «you» استخدم الرابط الذي يفتحها في متصفح محفظتك؛ والزر المجاور له ينسخ رابط الاقتران للصقه هناك.

بعبارة البذرة، كبديل احتياطي

./bin/casty init

يطلب كلمة المرور، ثم العبارة في مطالبة مخفية؛ تُستخدم العبارة مرة واحدة لتوقيع طلب المفتاح ولا تُكتب على القرص أبدًا. يختار --address-index عنوانًا آخر من العبارة.

في الحالتين، يمكن للمفتاح توقيع المنشورات والتفاعلات والمتابعات (يضيف --scopes تغييرات الملف الشخصي)، وتنتهي صلاحيته بعد 30 يومًا دون استخدام (--ttl، بحد أقصى 90d)؛ وكل رسالة يوقّعها تجدّد صلاحيته. يعرض ./bin/casty whoami المفتاح وعنوان الحفظ ومساحة التخزين لديك.

4. استخدمه في الطرفية

يسرد ./bin/casty --help كل الأوامر؛ ويسرد <command> --help خيارات الأمر. لتكتب casty بدلًا من ذلك، اربطه مرة واحدة: ln -s "$PWD/bin/casty" ~/.local/bin/casty.

لكي	شغّل
تقرأ تغذيتك	casty feed، casty feed --since 24h --no-replies --limit 20
تقرأ ما قاله لك الآخرون	casty mentions
تفتح منشورًا مع ما يرد عليه والردود عليه	casty thread 2
تنشر	casty cast "hello from my own node"، --channel /name، --embed <url>
ترد، تعجب، تعيد النشر	casty reply 1 "agreed"، casty like 1، casty recast 1
تتراجع	casty unlike 1، casty unrecast 1، casty delete 1
تتابع	casty follow @name، casty unfollow @name
ترى التطبيقات وراء مفاتيح fid	casty clients --fid <fid>
تتحقق من مساحة التخزين	casty storage
تتحقق من العقدة والساعة والإعداد	casty doctor، casty node status

الرقم أمام المنشور في آخر قائمة هو ما تقبله like وreply وrecast وdelete و thread؛ وكذلك <fid>:<hash> ورابط المنشور على farcaster.xyz. يذكر via التطبيق الذي نُشر المنشور من خلاله؛ ويرشّح --only-app و--exclude-app بحسبه. كل عملية كتابة تنتظر حتى تصل الرسالة إلى العقدة، وتقول ذلك إن لم تصل.

5. استخدمه في المتصفح

يقدّم ./bin/casty web الأوامر نفسها كصفحة على http://127.0.0.1:3390 ويطبع رابطًا يقرن المتصفح (في المتصفح وعلى الهاتف).

• على هاتف في المنزل: يطبع ./bin/casty web --listen 0.0.0.0:3390 رابطًا لكل عنوان شبكة ورمز QR؛ امسحه على الشبكة نفسها. الاتصال HTTP عادي، فاستخدم شبكة تثق بها. أضف الصفحة إلى الشاشة الرئيسية لتفتحها بملء الشاشة.
• قراءة فقط: لا يطلب --read-only كلمة مرور، ولا تستطيع الصفحة الكتابة.
• رمز جديد: يجعل --new-token كل رابط طُبع من قبل يتوقف عن العمل.

يوقف Ctrl-C الأمر casty web؛ ويجب أن يبقى الجهاز قيد التشغيل ما دام الهاتف يستخدمه.

6. الصفحة من أي شبكة

للوصول إلى الصفحة من شبكة جوال، شغّلها على مضيف العقدة خلف HTTPS (من أي شبكة). تحتاج أولًا إلى مفتاح تطبيق هنا (الخطوة 3): ينتقل مخزن المفاتيح وكلمة مروره إلى المضيف كسر Docker، ما لم تحدد --read-only.

مع نطاق:

1. وجّه سجل DNS من نوع A لاسم تملكه، node.example.org مثلًا، إلى عنوان IP للعقدة (NODE_IP في node.env).

2. شغّل:

   ./scripts/deploy.sh --fid <fid> --domain node.example.org

   على عقدة استأجرها casty، يفتح هذا المنفذين 80 و443 في جدار حمايتها؛ وعلى مضيف خاص بك، افتحهما بنفسك. ثم يبني casty على المضيف، ويشغّله خلف Caddy، الذي يحصل على الشهادة، ويطلب كلمة مرور مخزن المفاتيح، ويطبع https://node.example.org/#token=.... رمز QR لذلك الرابط موجود في ./scripts/1-node.sh logs casty.

مع Tailscale بدلًا من ذلك، ثبّته على المضيف وسجّل دخوله، وضع الهاتف على شبكة tailnet نفسها، وشغّل ./scripts/deploy.sh --fid <fid> --tailscale؛ ولا يُفتح أي منفذ على الإنترنت.

على المضيف تأتي التغذية من فهرس يتابع أحداث العقدة. تحت «you»، يشغّل «notifications» إشعار دفع لكل ذِكر أو رد، يذكر اسم المرسل ولا شيء غيره؛ على iPhone، أضف الصفحة إلى الشاشة الرئيسية أولًا (iOS 16.4 وما بعده).

بعد أي تغيير في casty، شغّل ./scripts/1-node.sh serve --domain <name> مجددًا: فهو يعيد بناء الصفحة وتشغيلها.

7. تشغيل العقدة

لكي	شغّل
ترى المزامنة	./scripts/1-node.sh status (رمز الخروج 1 ما دامت متأخرة)
تتابع سجلاتها، أو سجلات الصفحة	./scripts/1-node.sh logs، ./scripts/1-node.sh logs casty
تعيد فتح النفق بعد إعادة تشغيل جهازك	./scripts/1-node.sh tunnel (--stop يغلقه)
تنتقل إلى أحدث إصدار من Snapchain	./scripts/1-node.sh upgrade
تبقى على إصدار واحد	./scripts/1-node.sh upgrade --release 0.14.3
تجري الترقية كل أسبوع تلقائيًا	./scripts/1-node.sh --autoupgrade --fid <fid>: يشغّل docker system prune --volumes -f على المضيف كله
تحتفظ بعدد أقل من الكتل	./scripts/1-node.sh --block-retention 30 (بالأيام)
ترى Grafana	على المضيف، docker compose up -d grafana في ~/snapchain؛ وهنا، ssh -L 3000:127.0.0.1:3000 <user>@<ip> وhttp://127.0.0.1:3000
توقف العقدة، والصفحة	./scripts/1-node.sh down؛ وتبقى قاعدة البيانات على القرص

من شبكة أخرى، يظل جدار الحماية يسمح بالعنوان الذي كان لديك فقط: شغّل ./scripts/0-provision.sh مجددًا، فينقل القواعد إلى عنوانك الحالي، على العقدة نفسها.

8. المفاتيح والأمان

لكي	شغّل
تسرد مفاتيح معرّفك fid	casty key list
تزيل مفتاح casty هذا بالمفتاح نفسه	casty key revoke --self
تزيل أي مفتاح	casty key revoke <key>، بعبارة البذرة
تلغي اقتران كل المتصفحات	casty web --new-token؛ وعلى المضيف، احذف ~/snapchain/casty/config/web-token وdocker compose restart casty

يُتخطى المفتاح الذي انتهت صلاحيته، أو أُزيل من مكان آخر؛ أضف غيره كما في الخطوة 3. تسرد صفحة الأمان كل سر معني، وأين يوجد، وما يجب فعله إن تسرّب أحدها.

9. احذف كل شيء

./bin/casty key revoke --self        # first, while the node runs: the key stops working everywhere
./scripts/1-node.sh down             # stops the node and the page; nothing is deleted
./scripts/0-provision.sh --destroy   # deletes the server, its volume and its firewall, after you type the name
rm -rf ~/.config/casty               # the config and the encrypted key store here

يقرأ --destroy الملف node.env ليعرف ما يحذفه ويزيله بعد ذلك؛ والعقدة الجديدة تتزامن من البداية. على مضيف خاص بك لا يوجد ما يُدمَّر: احذف ~/snapchain هناك.

بدون عقدة

pnpm install، ثم pnpm demo، يشغّل العميل مقابل عقدة وهمية بعبارة الاختبار ويزيل ما أنشأه؛ ويقدّم pnpm demo:web الصفحة بالطريقة نفسها حتى Ctrl-C.

عندما تتوقف خطوة

يطبع كل سكربت ما فشل وما يجب فعله، ويخرج برمز يقول نوع المشكلة:

الرمز	0-provision.sh	1-node.sh	2-client.sh
1		غير متزامنة، أو لم تُجب العقدة
2	وسائط خاطئة	وسائط خاطئة	وسائط خاطئة
3	أداة أو بيانات اعتماد مفقودة	أداة مفقودة	أداة مفقودة، أو Node قديم جدًا
4	رفض المزوّد	لا اتصال SSH، أو فشل تنزيل	تعذّر الوصول إلى العقدة (افتح النفق)، أو لا تنزيل سليم
5	المضيف لا يفي بالمتطلبات	المضيف لا يفي بالمتطلبات	مشكلة في المفتاح: كلمة المرور، عبارة البذرة، التخزين

تحوي صفحة استكشاف الأخطاء وإصلاحها كل رسالة مع حلّها. يتوقف deploy.sh برمز الخطوة التي توقفت، ويتابع الأمر نفسه من هناك.