استقرار Node.js در ابران

Generated builder ابران برنامه‌های Node.js و frameworkهایی مانند Express، Fastify، Koa و NestJS را از package.json تشخیص می‌دهد. یک server قابل‌استقرار باید command شروع مشخص داشته باشد و روی آدرس و پورت runtime گوش دهد.

۱. server را برای runtime آماده کنید

پورت را از PORT بخوانید و روی 0.0.0.0 bind کنید. نمونه Express:

import express from 'express'
 
const app = express()
const port = Number(process.env.PORT || 3000)
 
app.get('/health', (_request, response) => response.status(200).send('ok'))
app.listen(port, '0.0.0.0')

برای Fastify از listen({ host: '0.0.0.0', port }) استفاده کنید. در NestJS نیز await app.listen(port, '0.0.0.0') را صریح بنویسید.

۲. package.json را کامل کنید

برنامه JavaScript ساده باید start داشته باشد:

{
  "engines": { "node": "22" },
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

برای برنامه compile‌شونده، build و start artifact را جدا کنید:

{
  "scripts": {
    "build": "nest build",
    "start": "node dist/main.js"
  }
}

NestJS از روی dependency تشخیص داده می‌شود و script build اجرا می‌شود. برای Express، Fastify یا Koa نوشته‌شده با TypeScript، build خودکار صرفاً از نام framework نتیجه‌گیری نمی‌شود؛ commandها را در abrun.yaml صریح کنید:

builder:
  platform: node
  build_command: npm run build
  run_command: node dist/server.js
runtime:
  port: 3000
  health: /health

۳. App را بسازید و deploy کنید

abrun app create my-api --plan <plan> --port 3000
abrun deploy my-api --logs

Builder نسخه Node را از engines.node می‌خواند و در نبود آن از نسخه پیش‌فرض پشتیبانی‌شده استفاده می‌کند. package manager از pnpm-lock.yaml، yarn.lock، package-lock.json یا field مربوط در package.json تشخیص داده می‌شود.

Generated build فعلی npm، pnpm و Yarn را پشتیبانی می‌کند. برای Bun از Dockerfile استفاده کنید.

۴. پیکربندی و دیتابیس

secretها و connection stringها را به‌صورت environment variable وارد کنید:

abrun app env set my-api 'DATABASE_URL=<connection-url>'
abrun app env set my-api NODE_ENV=production
abrun app restart my-api

مقدار واقعی secret را در command نمونه، repository یا log منتشر نکنید. برای اتصال امن، راهنمای اتصال دیتابیس را ببینید.

monorepo و workspace

abrun deploy my-api . --root-directory apps/api

اگر package هدف از dependencyهای workspace استفاده می‌کند، repository root باید workspaceها را تعریف و package هدف باید name داشته باشد. در غیر این صورت build context مستقل را انتخاب یا Dockerfile بنویسید.

رفع مشکل

• run command could not be resolved: یک script به نام start یا builder.run_command معتبر اضافه کنید.
• TypeScript اجرا نمی‌شود: build command و مسیر artifact نهایی مانند dist/main.js را صریح کنید.
• App فقط روی localhost است: host را به 0.0.0.0 تغییر دهید.
• dependency پیدا نمی‌شود: manifest، lockfile و مسیر package هدف را بررسی کنید و dependencyهای runtime را طبق قرارداد package خود تعریف کنید.
• install ناپایدار است: lockfile درست را commit و lockfileهای package manager دیگر را حذف کنید.

قدم بعدی

• مراحل و لاگ‌های استقرار
• متغیرهای محیطی
• اتصال دیتابیس
• چک‌لیست production