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

از اولین استقرار تا CI/CD، دامنه و پایگاه داده.

PaaSCLI · API

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

شروع سریع

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

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

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

شرط	توضیح
گوش دادن روی 0.0.0.0	نه 127.0.0.1؛ وگرنه ترافیک به اپ نمی‌رسد
پورت	همان پورتی که در تنظیمات اپ آمده؛ متغیر `PORT` همیشه مقدار آن را دارد
بی‌حالت بودن	فایل‌هایی که در کانتینر نوشته می‌شوند با هر استقرار پاک می‌شوند؛ برای فایل‌های ماندگار دیسک دائمی بگیرید

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

منابع کد

مخزن Git

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

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

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

سرویس	مسیر	رویداد
GitHub	Settings › Webhooks › Add webhook (Content type: application/json)	Just the push event
GitLab	Settings › Webhooks	Push events
Gitea	Settings › Webhooks › Gitea	Push

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

فایل ZIP

پوشه پروژه را فشرده کنید (حداکثر ۲۰۰ مگابایت). پوشه‌های 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

بیلد خودکار

پشته	از روی	دستور بیلد پیش‌فرض	دستور اجرای پیش‌فرض
Next.js	next در package.json	npm run build	npm start
Node.js	package.json	—	npm start
Python / Django / FastAPI / Flask	requirements.txt، pyproject.toml	pip install	gunicorn / uvicorn
Laravel / PHP	composer.json، artisan	composer install	PHP-FPM + Nginx
Go	go.mod	go build	باینری خروجی
Java	pom.xml، build.gradle	mvn package	java -jar
.NET	‎*.csproj	dotnet publish	dotnet app.dll
Dockerfile	Dockerfile در ریشه	docker build	CMD ایمیج

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

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

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

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

پایگاه داده

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

موتور	متغیر پیش‌فرض	نمونه
PostgreSQL	DATABASE_URL	postgres://user:pass@host:5432/db
MySQL / MariaDB	DATABASE_URL	mysql://user:pass@host:3306/db
MongoDB	MONGODB_URI	mongodb://user:pass@host:27017/db
Redis	REDIS_URL	redis://:pass@host:6379

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

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

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

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

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

مقیاس و منابع

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

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

هر استقرار ابتدا کامل بیلد می‌شود، سپس نمونه‌های جدید بالا می‌آیند و فقط وقتی «مسیر سلامت» (پیش‌فرض /) پاسخ موفق بدهد ترافیک را می‌گیرند. اگر بیلد یا 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 }} }

API

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

متد	مسیر	توضیح
GET	`/apps`	فهرست اپ‌ها
GET	`/apps/{app}`	جزئیات اپ (شناسه یا نام)
POST	`/apps/{app}/deployments`	شروع استقرار (برای ZIP: `upload_id`)
GET	`/apps/{app}/deployments/{id}`	وضعیت و لاگ بیلد
GET	`/apps/{app}/logs`	لاگ اجرا
PUT	`/apps/{app}/env`	تنظیم یا حذف متغیرها (`null` = حذف)
POST	`/apps/{app}/actions`	start، stop یا restart

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

هزینه

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

محدودیت‌ها

مورد	سقف
حجم ZIP	۲۰۰ مگابایت
زمان بیلد	۳۰ دقیقه
زمان بالا آمدن نسخه جدید	۱۰ دقیقه
استقرار با Webhook	۳۰ در ساعت برای هر اپ
تعداد نمونه دستی / خودکار	۱۰ / ۲۰
پشتیبان دستی هر پایگاه داده	۱۰