مستندات گره اپ

گره اپ کد شما را می‌گیرد، بیلد می‌کند و با HTTPS اجرا می‌کند. این راهنما همه چیزهایی را که برای استقرار یک اپ در production لازم دارید توضیح می‌دهد.

شروع سریع

1. در پنل › اپ‌ها «اپ جدید» را بزنید.
2. منبع را انتخاب کنید: مخزن Git، فایل ZIP، ایمیج Docker یا Docker Compose.
3. پلن، تعداد نمونه و متغیرهای محیطی را تنظیم کنید و «ساخت و استقرار» را بزنید.
4. چند دقیقه بعد اپ روی https://<نام-اپ>.gereh.dev در دسترس است.

قراردادهای اجرا

اپ شما باید این سه شرط را داشته باشد:

app.listen(process.env.PORT || 3000, "0.0.0.0");

منابع کد

مخزن Git

نشانی HTTPS مخزن و شاخه را وارد کنید. برای مخزن خصوصی یک توکن فقط-خواندنی در نشانی بگذارید:

https://<TOKEN>@github.com/acme/shop.git

برای استقرار خودکار با هر push، از تب «تنظیمات» اپ آدرس Webhook را کپی کنید و در مخزن ثبت کنید:

فقط push روی شاخه تنظیم‌شده استقرار را شروع می‌کند. اگر آدرس Webhook لو رفت، از همان صفحه «ساخت توکن جدید» را بزنید.

پوشه یا فایل ZIP

در پنل «انتخاب پوشه پروژه» را بزنید تا مرورگر پوشه را خودش فشرده و بارگذاری کند، یا فایل ZIP پروژه را بفرستید (حداکثر ۲۰۰ مگابایت). هنگام انتخاب پوشه، node_modules، .git و فایل‌های .env خودکار کنار گذاشته می‌شوند. پوشه‌های node_modules، .git، vendor و خروجی‌های بیلد را داخل ZIP نگذارید؛ هنگام بیلد دوباره ساخته می‌شوند. اگر همه فایل‌ها داخل یک پوشه باشند، همان پوشه ریشه در نظر گرفته می‌شود.

ایمیج Docker

نام کامل ایمیج عمومی، مثل ghcr.io/acme/api:1.4.2 یا nginx:alpine را وارد کنید و پورتی را که کانتینر روی آن گوش می‌دهد مشخص کنید. با تغییر ایمیج در تنظیمات، استقرار جدید شروع می‌شود.

Docker Compose

ZIP پروژه‌ای که docker-compose.yml یا compose.yaml در ریشه دارد را بارگذاری کنید (حداکثر ۸ سرویس). سرویس‌های دارای build جداگانه بیلد می‌شوند و سرویس‌های دارای image مستقیم اجرا می‌شوند.

• سرویس عمومی (همان که آدرس اپ و دامنه‌ها به آن وصل می‌شود) اولین سرویسی است که ports دارد؛ یا با برچسب gereh.public: "true" مشخصش کنید. مسیر سلامت روی همین سرویس بررسی می‌شود.
• سرویس‌ها همدیگر را مثل خود Compose با نام سرویس پیدا می‌کنند (مثلاً redis://cache:6379).
• environment هر سرویس اعمال می‌شود، ولی متغیرهای تب «متغیرها» بر آن مقدم‌اند و به همه سرویس‌ها داده می‌شوند.
• همه سرویس‌ها منابع پلن اپ را با هم شریک‌اند؛ تعداد نمونه فقط روی سرویس عمومی اعمال می‌شود.
• volumes و env_file نادیده گرفته می‌شوند و در لاگ بیلد هشدار می‌گیرند. برای داده ماندگار از پایگاه داده مدیریت‌شده (با پشتیبان) یا دیسک دائمی اپ استفاده کنید.

services:
  web:
    build: .
    ports: ["3000"]
    environment: [REDIS_URL=redis://cache:6379]
  worker:
    build: .
    command: node worker.js
  cache:
    image: redis:7-alpine

بیلد خودکار

دستورهای بیلد و اجرا را می‌توانید در تنظیمات اپ بازنویسی کنید. برای monorepo «پوشه ریشه» را تنظیم کنید (مثلاً apps/web).

متغیرهای محیطی

از تب «متغیرها» اضافه کنید یا محتوای فایل .env را مستقیم بچسبانید. ذخیره متغیرها اپ را بدون بیلد مجدد با مقادیر جدید ری‌استارت می‌کند.

• متغیرهای محرمانه رمزنگاری‌شده ذخیره می‌شوند و بعد از ثبت دیگر نمایش داده نمی‌شوند؛ حتی پشتیبانی گره هم آن‌ها را نمی‌بیند.
• PORT، GEREH_APP و GEREH_DEPLOYMENT را پلتفرم تنظیم می‌کند.
• متغیرهایی که هنگام بیلد خوانده می‌شوند (مثل NEXT_PUBLIC_* یا VITE_*) بعد از تغییر به یک استقرار جدید نیاز دارند.

پایگاه داده

از پنل › پایگاه داده یک PostgreSQL، MySQL، MariaDB، MongoDB یا Redis بسازید و در تب «پایگاه داده» اپ آن را متصل کنید. آدرس اتصال کامل به‌صورت متغیر به اپ داده می‌شود:

پشتیبان خودکار روزانه با نگهداری ۷ نسخه انجام می‌شود و تا ۱۰ پشتیبان دستی هم می‌توانید بگیرید. بازگردانی همه داده‌های فعلی را جایگزین می‌کند؛ قبل از آن یک پشتیبان دستی بگیرید.

دامنه اختصاصی

در تب «دامنه‌ها» دامنه را اضافه کنید و یک رکورد CNAME به آدرس پیش‌فرض اپ بسازید:

www.example.ir.  CNAME  my-shop.gereh.dev.

برای ریشه دامنه از ALIAS/ANAME استفاده کنید. بعد از تأیید DNS، گواهی SSL خودکار صادر و تمدید می‌شود. اگر دامنه را در گره ثبت کرده‌اید، رکورد را از بخش DNS همان دامنه بسازید.

CDN و کش لبه

از تب «دامنه‌ها» CDN را روشن کنید. پاسخ‌هایی که اپ با Cache-Control قابل کش اعلام کند (مثلاً public, max-age=3600) در لبه شبکه نگه داشته می‌شوند و بدون رسیدن به اپ سرو می‌شوند. پاسخ‌های دارای Set-Cookie یا private هرگز کش نمی‌شوند. وضعیت هر پاسخ در سربرگ X-Cache-Status (HIT، MISS…) دیده می‌شود و «پاک کردن کش» همه نسخه‌های ذخیره‌شده را بی‌اعتبار می‌کند. فشرده‌سازی Gzip و Brotli برای همه اپ‌ها روشن است.

مقیاس و منابع

• پلن منابع هر نمونه را تعیین می‌کند (پردازنده و حافظه).
• تعداد نمونه ترافیک را بین چند کپی از اپ پخش می‌کند؛ برای دسترس‌پذیری بالا دست‌کم ۲ نمونه.
• مقیاس خودکار با بار CPU بین تعداد فعلی و حداکثر تعیین‌شده بالا و پایین می‌رود.
• دیسک دائمی فقط با یک نمونه کار می‌کند و قابل کوچک کردن نیست.

دستور انتشار، پردازش‌های پس‌زمینه و زمان‌بندی

در پنل اپ › «پردازش و زمان‌بندی»:

• دستور انتشار (release): پس از هر بیلد موفق و پیش از رسیدن ترافیک به نسخه جدید، یک بار در کانتینری جدا اجرا می‌شود؛ مثل python manage.py migrate --noinput یا npx prisma migrate deploy. اگر خطا بدهد، استقرار متوقف می‌شود و نسخه قبلی سرویس می‌دهد.
• پردازش‌های پس‌زمینه: تا ۵ پردازش بدون پورت HTTP (مثل celery -A app worker یا php artisan queue:work) با همان ایمیج و متغیرها. هر نمونه به اندازه پلن اپ منابع دارد و مثل یک نمونه وب محاسبه می‌شود.
• زمان‌بندی (cron): تا ۱۰ دستور دوره‌ای به وقت تهران، با فاصله دست‌کم ۵ دقیقه. اجراها هم‌پوشانی ندارند و حداکثر یک ساعت طول می‌کشند.
• اجرای دستور یک‌باره: از پنل، با gereh run python manage.py createsuperuser یا از ایجنت هوش مصنوعی (ابزار run_job). خروجی تا ۲۴ ساعت نگه داشته می‌شود.

پیش‌نمایش و انتقال به نسخه اصلی

هر اپ Git یا ZIP یک پیش‌نمایش کنار نسخه اصلی دارد: <نام>-preview.gereh.dev. از پنل › استقرارها شاخه‌ای را بسازید (یا gereh deploy --preview --branch feature-x)، آن را امتحان کنید و با «انتقال به نسخه اصلی» (یا gereh promote) همان ایمیج بدون بیلد دوباره روی نسخه اصلی می‌رود. با روشن کردن «پیش‌نمایش خودکار» در تنظیمات، هر push به شاخه‌ای غیر از شاخه اصلی پیش‌نمایش می‌سازد.

• پیش‌نمایش یک نمونه است و تا وقتی فعال است هزینه یک نمونه اضافه دارد؛ با «حذف» متوقف می‌شود.
• همان متغیرهای محیطی اپ را دارد (به‌علاوه GEREH_PREVIEW=1)؛ اگر نباید به پایگاه داده اصلی وصل شود، در کد با این متغیر جدا کنید.
• دستور انتشار در پیش‌نمایش اجرا نمی‌شود؛ هنگام انتقال به نسخه اصلی اجرا می‌شود.

فایل gereh.json

تنظیمات اجرای اپ را می‌توانید در ریشه مخزن نگه دارید؛ پس از هر بیلد نسخه اصلی خوانده و پیش از انتشار اعمال می‌شود (همان فایلی که gereh link می‌سازد):

{
  "app": "shop",
  "start": "gunicorn config.wsgi",
  "port": 8000,
  "health": "/healthz",
  "release": "python manage.py migrate --noinput",
  "processes": { "worker": "celery -A config worker", "beat": { "command": "celery -A config beat", "instances": 1 } },
  "crons": [{ "name": "cleanup", "schedule": "0 3 * * *", "command": "python manage.py clearsessions" }]
}

کلیدهایی که در فایل نیستند دست نمی‌خورند. اگر فایل خطا داشته باشد، استقرار با پیام دقیق متوقف می‌شود و نسخه فعلی سرویس می‌دهد. دستور بیلد را در nixpacks.toml یا Dockerfile تعیین کنید.

استقرار بدون قطعی و بازگشت

هر استقرار ابتدا کامل بیلد می‌شود، سپس نمونه‌های جدید بالا می‌آیند و فقط وقتی «مسیر سلامت» (پیش‌فرض /) پاسخ موفق بدهد ترافیک را می‌گیرند. اگر بیلد یا health check شکست بخورد، نسخه قبلی بدون تغییر به کار ادامه می‌دهد. از تب «استقرارها» هر نسخه موفق قبلی را با یک کلیک برگردانید.

CLI

npx @gereh/cli login          # توکن خواندن-نوشتن از پنل › SSH و API
npx @gereh/cli link my-shop   # gereh.json را در پوشه پروژه می‌سازد
npx @gereh/cli deploy -m "v1.4"
npx @gereh/cli logs -f
npx @gereh/cli env set API_KEY=xyz --secret

برای اپ‌های ZIP، CLI پوشه فعلی را (با رعایت .gerehignore یا .gitignore) فشرده و بارگذاری می‌کند. برای اپ‌های Git، بیلد از آخرین کامیت شاخه انجام می‌شود.

استقرار از GitHub Actions

name: deploy
on: { push: { branches: [main] } }
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @gereh/cli deploy --app my-shop -m "$GITHUB_SHA"
        env: { GEREH_TOKEN: ${{ secrets.GEREH_TOKEN }} }

افزونه VS Code

افزونه «Gereh Cloud» اپ‌ها، پایگاه‌های داده و سرورها را در نوار کناری VS Code نشان می‌دهد و دیپلوی، پیش‌نمایش و انتقال به نسخه اصلی، لاگ زنده، اجرای دستور و ری‌استارت را از همان‌جا انجام می‌دهد. با دستور «Gereh: Connect AI agents» هم Copilot و دیگر ایجنت‌ها به سرور MCP گره وصل می‌شوند. پس از نصب، «Gereh: Sign in» را بزنید و توکن خواندن/نوشتن را وارد کنید.

API

همه کارهای بالا با API عمومی هم در دسترس است:

بارگذاری ZIP با POST /api/paas/upload (multipart، فیلد file) و همان توکن انجام می‌شود و uploadId برمی‌گرداند.

هزینه

قیمت هر پلن ماهانه اعلام شده و هر ساعت ۱/۷۲۰ آن از کیف پول کم می‌شود. هزینه اپ = قیمت پلن × تعداد نمونه + دیسک دائمی. اپ خاموش فقط هزینه دیسک دارد. برای ساخت یا بزرگ کردن سرویس باید اعتبار دست‌کم ۲۴ ساعت مصرف در کیف پول باشد. اگر موجودی تمام شود سرویس‌ها معلق می‌شوند (حذف نمی‌شوند) و با شارژ دوباره خودکار روشن می‌شوند.

محدودیت‌ها