شروع

فایل cloudhost.toml

تنظیمات هر پروژه در یک فایل کنار کدش: نام، نوع، فایل ورودی، فایل‌های استاتیک، متغیرها، اتصال به دیتابیس و کش و باکت، cron و دستور بیلد. cloudhost deploy بدون آرگومان همین فایل را می‌خواند.

ایجاد فایل#

init

cd my-api
cloudhost init
# wrote cloudhost.toml for my-api; edit it, then: cloudhost deploy
cloudhost deploy

cloudhost init [name] در پوشهٔ فعلی یک cloudhost.toml می‌نویسد. نام پیش‌فرض نام پوشه است. در پوشه‌ای بدون package.json فایل برای یک فانکشن نوشته می‌شود و در غیر این صورت برای یک برنامه؛ cloudhost apps init همیشه برنامه می‌نویسد.

یک نمونهٔ کامل#

cloudhost.toml

name = "guestbook"
type = "function"
main = "index.ts"
runtime_date = "2026-11-01"

[vars]
GREETING = "salam"

[[db]]
binding = "DB"
database = "notes"

[[cache]]
binding = "CACHE"
name = "sessions"

[[bucket]]
binding = "BUCKET"
name = "uploads"

[[queues.producers]]
binding = "JOBS"
queue = "emails"

[triggers]
crons = ["0 3 * * *"]

کلیدها#

کلید	معنی
`name`	الزامی. یک برچسب DNS: حروف کوچک لاتین، رقم و خط تیره، ۱ تا ۶۳ کاراکتر، بدون `--`. آدرس پروژه `<name>.fn.trustpage.ir` یا `<name>.app.trustpage.ir` است.
`type`	`"function"` یا `"app"`. پیش‌فرض: برنامه، اگر `assets` یا یک فریم‌ورک باشد؛ وگرنه فانکشن.
`main`	فایل ورودی فانکشن (TypeScript یا JavaScript). برای برنامهٔ اختیاری است: فانکشنی برای مسیرهایی که فایل ندارند.
`assets`	پوشهٔ فایل‌های استاتیک برنامه.
`runtime_date`	`YYYY-MM-DD`؛ رفتار محیط اجرا را روی آن تاریخ ثابت نگه می‌دارد. پیش‌فرض: امروز.
`spa`	`true`: برای مسیرهای ناشناخته `/index.html` برگردد، در برنامه‌ای که فانکشن هم دارد. برنامه بدون فانکشن این را خودش تشخیص می‌دهد.
`framework`	`"none"` تشخیص خودکار Next.js و Astro را خاموش می‌کند.
`[vars]`	مقدارهای ساده که با `env.NAME` خوانده می‌شوند. برای سکرت‌ها نیست: آن‌ها را با `secrets put` بگذارید.
`[[db]]`	`binding` (پیش‌فرض `DB`) و `database`: دیتابیس تیم به نام `env.DB`.
`[[cache]]`	`binding` (پیش‌فرض `CACHE`) و `name`.
`[[bucket]]`	`binding` (پیش‌فرض `BUCKET`) و `name`.
`[[queues.producers]]`	`binding` و `queue`: فانکشن با `env.<binding>.send(body, {delaySeconds})` و `sendBatch([...])` به صف می‌فرستد. شکل قدیمی `[[queue]]` با `binding` (پیش‌فرض `QUEUE`) و `name` هم پذیرفته است.
`[[queues.consumers]]`	`queue`، و اختیاری `max_batch_size`، `max_batch_wait_ms`، `max_concurrency`، `max_retries`، `retry_delay`، `visibility_timeout` و `dead_letter_queue`. هر استقرار این فانکشن را مصرف‌کنندهٔ صف می‌کند (هندلر `queue(batch, env, ctx)`) و تنظیمات صف را به‌روز می‌کند.
`[triggers] crons`	تا ۵ cron. هر استقرار فهرست پروژه را با همین فهرست جایگزین می‌کند، با منطقهٔ زمانی `Asia/Tehran`. بدون `[triggers]` cronها دست نمی‌خورند.
`[build] command`	دستوری که پیش از استقرار اجرا می‌شود، مثلاً `npm run build`.

استقرار با فایل#

cloudhost deploy در پوشه‌ای که cloudhost.toml دارد: دستور بیلد را اجرا می‌کند، اگر Next.js یا Astro باشد آن را بیلد می‌کند، فایل‌ها و کد را آپلود می‌کند، نسخه را مستقر می‌کند و cronها را می‌گذارد. با --branch feature-x به‌جای production یک پیش‌نمایش بیلد می‌کند.

cloudhost build و git push همین فایل را روی سرورهای ما می‌خوانند. اگر ریپازیتوری cloudhost.toml نداشته باشد، بیلد از نام و نوع پروژه استفاده می‌کند و برنامه‌ای که package.json ندارد از ریشهٔ ریپازیتوری به شکل فایل استاتیک سرو می‌شود.

سکرت‌ها هیچ‌وقت در این فایل نیستند و با استقرار عوض نمی‌شوند: cloudhost functions secrets put <name> <KEY>.