مسیر فایل: scripts/bring_up.sh
۱. کاراییش به زبان ساده
این اسکریپت همان دکمهٔ «پروژه را برایم بالا بیاور» است؛ ولی دیگر همه‌چیز را با یک docker compose up -d واحد روشن نمی‌کند. روی ماشین تازه یا سرور نصب‌شده اجرا می‌شود، فایل‌های محیطی گم‌شده را از نمونه‌ها می‌سازد (بدون بازنویسی فایل‌های موجود)، اعتبارنامه‌های خالی Postgres را پر می‌کند، سپس استک را مرحله‌به‌مرحله بالا می‌آورد: اول زیرساخت، بعد فقط app-api، بعد ثبت اپ‌های اولیه با seed_apps.sh، و در نهایت بقیهٔ سرویس‌های پیش‌فرض (از جمله crawler و storage-consumer). هدف این ترتیب این است که اولین چرخهٔ crawl با لیست اپ‌های ازپیش‌ثبت‌شده شروع شود، نه با دیتابیس خالی. در پایان، مگر با --skip-check، Smoke Test زیرساخت (check_infra.sh) را اجرا می‌کند. نصب Docker روی سیستم‌عامل را انجام نمی‌دهد؛ آن کار عمداً به اپراتور یا Ansible سپرده شده است.
۲. کجا در پروژه کلی استفاده می‌شود؟
- نقطهٔ ورود توصیه‌شده برای راه‌اندازی اولیه و بالا آوردن روزمرهٔ استک (طبق
docs/setup.mdو فهرست اسکریپت‌ها). - همان اسکریپتی که نقش
deployدر Ansible صدا می‌زند (./scripts/bring_up.sh --skip-check)؛ بنابراین ترتیب seed قبل از crawler روی سرور هم اعمال می‌شود. - جایگزین فراخوانی دستی و پراکندهٔ
docker compose upبرای اپراتورهایی که می‌خواهند env، wait، seed و smoke check یک‌جا انجام شود. - با فلگ
--with-cycle-reportsسرویس Compose به نامcycle-reporterرا هم فعال می‌کند که داخلشfinalize_cycle_reports.pyدر حلقه اجرا می‌شود. - با فلگ
--infra-onlyفقط لایهٔ داده و ابزارهای کمکی را بالا می‌آورد (بدون app-api / seed / crawler) تا توسعهٔ host/venv روی App API و Crawler ممکن باشد. - نیمهٔ Shell از «نصب و راه‌اندازی» است؛ نیمهٔ Ansible در پوشهٔ
ansible/عمداً جدا مانده و اینجا صدا زده نمی‌شود.
۳. چیکارا می‌کند؟ (جریان مرحله‌ای)
در حالت کامل (بدون --infra-only) ترتیب ثابت است. سرویس‌های پروفایل tools و test در گام آخر با up عادی بالا نمی‌آیند.
| مرحله | چه چیزی بالا می‌آید / اجرا می‌شود | منتظر چه چیزی می‌ماند |
|---|---|---|
| ۰ — پیش‌نیاز و env | docker / Compose روی PATH؛ ساخت .envهای گم‌شده از *.env.example؛ پر کردن Postgres خالی و آینه به envهای host-side مربوط به app_api و storage_consumer. |
— |
| ۱ — زیرساخت | postgres، zookeeper، kafka، kafka-init، kafka-ui، metabase |
Postgres آماده؛ وجود/ساخت idempotent دیتابیس metabase_app_db؛ سلامت Metabase (با بودجهٔ retry بلند)؛ Kafka؛ اتمام موفق kafka-init |
| ۲ — فقط app-api | docker compose up -d app-api (و در صورت نیاز --build) |
healthcheck کانتینر project_app_api سبز شود |
| ۳ — Seed اپ‌ها | اجرای ./scripts/seed_apps.sh از روی host با APP_API_PORT خوانده‌شده از root .env |
اگر حداقل یک [FAIL] واقعی باشد، bring_up با exit غیرصفر قطع می‌شود (قبل از بالا آوردن crawler) |
| ۴ — بقیهٔ استک پیش‌فرض | storage-consumer، crawler؛ و در صورت --with-cycle-reports سرویس cycle-reporter. فهرست سرویس‌ها صریح است تا پروفایل‌های tools / test ناخواسته فعال نشوند. |
سلامت storage-consumer |
| ۵ — Sentiment (اختیاری) | اگر image از قبل موجود playpulse-sentiment:latest باشد: compose --profile tools up -d --no-build sentiment؛ وگرنه skip بدون cold-build. |
— |
| ۶ — Smoke | scripts/infra/check_infra.sh (مگر --skip-check) |
exit معنادار از smoke |
چرا این ترتیب؟ Crawler در شروع چرخه لیست اپ‌های فعال را از App API می‌گیرد. اگر crawler همزمان با app-api (روی DB خالی) بالا بیاید، اولین چرخه با total=0 تمام می‌شود. Seed بین «app-api سالم» و «شروع crawler» این شکاف را می‌بندد.
حالت --infra-only: فقط مرحلهٔ ۰ و ۱؛ بدون app-api، seed، crawler، consumer و sentiment.
آنچه bring_up عمداً انجام نمی‌دهد:
- فعال کردن پروفایل
test(سرویس‌های*-tests). - فعال کردن پروفایل
toolsبرایnetwork-analyzer— آن job دسته‌ای است و باید جداگانه باdocker compose --profile tools run --rm network-analyzerصدا زده شود. - cold-build کردن image سنتیم‌نت؛ فقط در صورت وجود قبلی ممکن است کانتینر را با
--no-buildبسازد.
۴. تصمیمات معماری
- Staged startup به‌جای یک up واحد: تضمین ترتیب وابستگی داده (registry پر → crawler) فراتر از
depends_onکه فقط «کانتینر سالم» را تضمین می‌کند، نه «داده seed شده». - جدا بودن از Ansible: نصب OS/Docker کار provisioning است؛ این اسکریپت فقط bootstrap داخل مخزن کلون‌شده است تا مرز مسئولیت شفاف بماند.
- هرگز overwrite نکردن .env: جلوگیری از از دست رفتن تنظیمات اپراتور روی سرور زنده.
- آینه‌کردن credentials: یک منبع حقیقت برای Postgres در root
.env، و همگام‌سازی envهای host تا تست/اجرای محلی گیر نکند. - Metabase در INFRA نه APP: مثل Kafka UI یک ابزار ops است، فقط به Postgres سالم نیاز دارد، و در حالت
--infra-onlyهم مفید است. - فهرست صریح سرویس‌ها در گام آخر: تا
cycle-reporterفقط با فلگ بیاید و پروفایل‌های tools/test دست‌نخورده بمانند. - Sentiment بدون cold-build: همان قرارداد
run_tests_in_docker.sh؛ build سنگین مدل فقط وقتی اپراتور عمداًcompose --profile tools build sentimentزده باشد. - Wait قبل از smoke و قبل از seed: «کانتینر بالا آمده» با «سرویس آماده است» یکی نیست.
- شکست seed = توقف bring_up: بهتر است crawler اصلاً بالا نیاید تا اینکه با registry ناقص شروع کند.
۵. دستورات
# از ریشهٔ مخزن — استک کامل (infra → app-api → seed → consumer + crawler)
./scripts/bring_up.sh
# فقط زیرساخت (Postgres / ZooKeeper / Kafka / UI / Metabase)
./scripts/bring_up.sh --infra-only
# استک کامل + گزارش‌های چرخه (crawler pending + cycle-reporter)
./scripts/bring_up.sh --with-cycle-reports
# رد کردن smoke check (مثلاً وقتی Ansible جداگانه check_infra را می‌زند)
./scripts/bring_up.sh --skip-check
# استفاده از imageهای از قبل buildشده
./scripts/bring_up.sh --no-build
./scripts/bring_up.sh --help
پیش‌نیاز: Docker Engine + پلاگین Compose، اجرا از ریشهٔ کلون مخزن؛ برای seed روی host به curl و python3 نیاز است (همان پیش‌نیازهای seed_apps.sh).
بررسی سریع پس از موفقیت:
# ترتیب زمانی شروع: app-api باید قبل از crawler باشد
docker inspect -f '{{.Name}} started={{.State.StartedAt}}' project_app_api project_crawler
# ۱۵ اپ seedشده
curl -sS "http://localhost:${APP_API_PORT:-8000}/api/applications/" | python3 -m json.tool
# اولین چرخه نباید total=0 باشد
docker compose logs crawler | grep "Crawl cycle summary"
# گام عملیاتی بعدی
./scripts/verify/verify_storage_consumer.sh