رفتن به محتوا

راه‌اندازی محیط‌ها

محیط پشتهٔ در حال اجرای یک فضاست: سرویس‌هایی که یک شاخه نیاز دارد، جدا از همهٔ فضاهای دیگر، نمایان در نوار کناری و در دسترس عامل‌ها. درخواست‌های کشش هم محیط دارند، چون هر PR از قبل فضای خودش را دارد.

مدیر فضای کاری یک بار تعریف را می‌نویسد. سپس اعضا در بخش محیط نوار کناری فضا یا PR روی شروع می‌زنند. تعریف‌ها در پایگاه‌دادهٔ فضای کاری هستند، بنابراین یک شاخهٔ قابلیت هرگز آنچه را Control Center اجرا می‌کند تغییر نمی‌دهد، هرچند ابزارها همچنان کد آن شاخه را اجرا می‌کنند.

  1. تنظیمات → فضای کاری → محیط‌ها را باز کنید. فقط مدیران فضای کاری می‌توانند تعریف‌ها را تغییر دهند، و فقط مالک سرور می‌تواند تعریفی را که روی میزبان سرور اجرا می‌شود ذخیره کند (ببینید چه کسی چه چیزی را ذخیره می‌کند).
  2. روی تعریف جدید و سپس تعریف خالی یا پیش‌نویس از مخزن کلیک کنید. پیش‌نویس مخزن را برای فایل‌های compose، یک Procfile و اسکریپت‌های package.json می‌گردد و نتیجه را شما بازبینی می‌کنید.
  3. فرم را پر کنید یا از زبانهٔ JSON استفاده کنید. نمونه‌های این صفحه همان JSON هستند.
  4. روی اجرای آزمایش کلیک کنید. این کار یک محیط یک‌بارمصرف را آغاز می‌کند، تا آماده شدنش صبر می‌کند و آن را نابود می‌کند.

هنگام ذخیره، تعریف به‌دقت بررسی می‌شود. هر فیلد ناشناخته، مقدار با نوع نادرست یا گزینهٔ غلط‌نوشته‌شده رد می‌شود، همراه با مسیر آن و نزدیک‌ترین نام معتبر، مانند repos.app.requird: Unknown field. Did you mean "required"?. یک $schema در سطح بالا مجاز است.

برای نگه داشتن تعریف در مخزن، از پیوند فایل مخزن استفاده کنید. Control Center فایل را فقط از شاخهٔ پیش‌فرض می‌خواند و فقط نسخه‌ای را اجرا می‌کند که تأیید شده باشد: توسط مدیر فضای کاری، یا توسط مالک سرور وقتی تعریف روی میزبان اجرا می‌شود. نسخهٔ جدیدتر به‌روزرسانی موجود است را نشان می‌دهد و تا تأیید نشود چیزی را تغییر نمی‌دهد.

یک تعریف محیط می‌تواند فرمان‌هایی را روی میزبان سرور به‌عنوان کاربر خود سرور اجرا کند. این تصمیم مالک سرور است، نه نقش فضای کاری:

  • تعریفی روی میزبان اجرا می‌شود که جایگذاری میزبان، بررسی‌ای که فرمانی را اجرا می‌کند، یا وظیفهٔ provision یا archive داشته باشد. این وظایف، هرچه جایگذاری باشد، در worktree فضا روی میزبان اجرا می‌شوند.
  • فقط مالک سرور می‌تواند تعریفی را که روی میزبان اجرا می‌شود ذخیره یا تأیید کند. این شامل تأیید نسخهٔ جدید یک فایل مخزن پیوندی هم می‌شود. مدیر فضای کاری که تلاش کند این پیام را می‌بیند: «فقط مالک سرور می‌تواند محیطی را که روی میزبان سرور اجرا می‌شود ذخیره یا تأیید کند. مدیر فضای کاری می‌تواند از محیطی استفاده کند که داخل Rig اجرا می‌شود.»
  • مدیر فضای کاری می‌تواند تعریفی را که کاملاً داخل یک rig اجرا می‌شود ذخیره و تأیید کند: "placement": "rig"، بدون فرمان بررسی و بدون وظیفهٔ provision یا archive.
  • اعضا در هر حال محیط‌ها را شروع، متوقف و استفاده می‌کنند.
  • تعریفی که روی میزبان اجرا می‌شود فقط بعد از آنکه مالک فعلیِ سرور آن را ذخیره یا تأیید کرده اجرا می‌شود. سرور این تأیید را خودش ثبت می‌کند و پیش از هر شروع، بررسی، وظیفه و همگام‌سازی سر PR آن را بررسی می‌کند. تعریفی که مالک فعلی تأیید نکرده، مثلاً تعریفی که مالک پیشین ذخیره کرده، زیر ردیفش در فهرست محیط‌ها و در ویرایشگر منتظر می‌ماند. مالک سرور پیام «روی این سرور اجرا می‌شود. برای اینکه شروع شود آن را تأیید کنید.» را همراه با تأیید می‌بیند که آن را بدون تغییر ذخیره می‌کند؛ بقیه پیام «روی این سرور اجرا می‌شود. پیش از شروع، مالک سرور باید آن را تأیید کند.» را می‌بینند.
  • محیطی که برای این تأیید نگه داشته شده می‌گوید: «مالک سرور هنوز این محیط را تأیید نکرده است، پس نمی‌تواند روی این سرور اجرا شود.» مالک سرور به‌جای آن این را می‌بیند: «هنوز این محیط را تأیید نکرده‌اید. روی این سرور اجرا می‌شود، پس وقتی تعریفش را تأیید کنید شروع می‌شود.» همراه با بازبینی و تأیید که تعریف را باز می‌کند.
  • ترمینال‌های فرایندهای محیط، و ترمینالی که شروع وقتی به شما نیاز دارد باز می‌کند، روی میزبان سرور اجرا می‌شوند. تایپ در آن‌ها، تغییر اندازه یا بستنشان به دسترسی نوشتن روی هر مخزنی که فضا در اختیار می‌گذارد نیاز دارد، که با ورود خودتان به forge خوانده می‌شود: همان چیزی که برای شروع محیط لازم است. هر کس دیگری اصلاً به آن ترمینال‌ها نمی‌رسد.

یک مخزن compose ساده فقط به این نیاز دارد:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

بقیه چیزها پیش‌فرض دارند: فایل compose پیدا می‌شود، همهٔ سرویس‌ها اجرا می‌شوند، درگاه‌ها تخصیص می‌یابند، نقطه‌های پایانی HTTP شناسایی می‌شوند و نام محیط از شاخه گرفته می‌شود.

محیط فهرستی مرتب از مؤلفه‌هاست. هر مؤلفه منتظر آماده شدن قبلی می‌ماند، مگر آنکه after مؤلفه‌های دیگری را نام ببرد، و توقف برعکس انجام می‌شود. enabledWhen مؤلفه را به یک گزینه یا نقش وابسته می‌کند، مثلاً opt.seed، !opt.seed یا repo.web. مؤلفه‌ای که نقشش اختیاری است و در فضا وجود ندارد به همین شیوه کنار گذاشته می‌شود، بدون نیاز به enabledWhen: شروع نمی‌شود و {port.*} یا {url.*} ندارد، پس مؤلفهٔ دیگری که آن‌ها را می‌خواند شروع را با شکست مواجه می‌کند.

نوع چه کسی اجرا می‌کند کاربرد
compose درایور compose در Control Center هر فایل compose، یکی برای هر محیط
cli ابزار شما. Control Center فعل‌های نگاشت‌شده را صدا می‌زند و JSON می‌خواند ابزاری که چرخهٔ عمر، دامنه‌ها و داده‌هایش را خودش مدیریت می‌کند
process Control Center، در نشست پایانهٔ تحت نظارت سرورهای توسعه و workerها
task Control Center، یک بار برای هر محرک نصب، مهاجرت، آزمون
app Control Center، وقتی کسی روی راه‌اندازی برنامه کلیک کند برنامهٔ دسکتاپ

مؤلفه‌های task یک فهرست when می‌گیرند:

محرک زمان اجرا
provision هنگام ساخته شدن worktree (وظایف worktree را در ادامه ببینید)
create یک بار برای هر محیط و دوباره پس از بازنشانی
start در هر آغاز
change پس از همگام‌سازی، وقتی مسیر تغییریافته با onChange مطابقت داشته باشد
manual در صورت درخواست: اجرا، cc-env run <id> یا environment_run_task
archive درست پیش از نابودی worktree

وظیفه‌ای که در شروع کاری برایش نیست، وضعیت بیکار را دارد و در فهرست گام‌هایی که هنگام شروع محیط نشان داده می‌شود نمی‌آید: وظیفهٔ manual یا change، یا وظیفهٔ create که قبلاً اجرا شده است.

فرمانی که به‌صورت آرایه داده شود argv است، پس مقدار گزینه‌ها هرگز از پوسته عبور نمی‌کند. یک رشته، یا script با آرایه‌ای از خطوط، زیر bash -lc اجرا می‌شود. جای‌نگهدارهایی مانند {name}، {branch}، {stateDir}، {repo.<role>}، {port.<key>}، {opt.<key>} و {url.<role>} فقط در argv گسترش می‌یابند. فرمان‌های پوسته همان مقادیر را به‌صورت متغیرهای CC_ENV_* مانند $CC_ENV_PORT_WEB می‌خوانند. یک جای‌نگهدار ناشناخته در مؤلفه‌ای که در شروع شرکت دارد، پیش از اجرای هر چیزی، شروع را متوقف می‌کند.

هر فرمان و پایانهٔ فضا همچنین CC_ENV_NAME، CC_ENV_STATE_DIR، CC_ENV_URL، CC_SPACE_ID، CC_ENV_REPO_<ROLE> و در فضاهای PR، CC_PR_NUMBER و CC_PR_IS_FORK را می‌گیرد. با مؤلفهٔ compose، COMPOSE_PROJECT_NAME و COMPOSE_FILE هم داده می‌شوند، پس docker compose exec در یک وظیفه به پروژهٔ درست می‌رسد.

تعریف نقش‌ها را به مخزن‌های فضای کاری پیوند می‌دهد، پس یک پشته می‌تواند چند مخزن را در بر بگیرد:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: فضا وقتی می‌تواند محیط را آغاز کند که دست‌کم یک نقش لنگر داشته باشد. اگر دو تعریف مطابقت داشته باشند، آغازکننده انتخاب می‌کند.
  • required: پشته بدون این مخزن اجرا نمی‌شود.
  • whenMissing: آنچه هنگام نبود نقش در فضا رخ می‌دهد. addToSpace مخزن را روی شاخهٔ پیش‌فرض اضافه می‌کند و پیش‌فرض نقش‌های required است. useSource چک‌اوت ثبت‌شدهٔ شما را می‌دهد که باید فقط‌خواندنی در نظر بگیرید. skip متغیر را تنظیم‌نشده می‌گذارد و در بقیهٔ موارد پیش‌فرض است.
  • آغاز کردن به مجوز write روی یک مخزن لنگر در فضا و دسترسی خواندن به همهٔ مخزن‌های پیوندخوردهٔ دیگر نیاز دارد.

فرمان در در نخستین نقشی اجرا می‌شود که در repos اعلام شده، نه در نقش دیگری که فضا تصادفاً دارد، پس تعریف تک‌مخزنی هرگز به آن اشاره نمی‌کند. هر مؤلفه می‌تواند با "cwd": { "role": "e2e", "path": "packages/ui" } آن را تغییر دهد. هر دو فیلد اختیاری‌اند. وقتی ممکن است نخستین نقش در یک فضا نباشد، چون نه required است و نه تنها لنگر است، هر مؤلفه باید نقش خود را نام ببرد.

Control Center پیش از آغاز هر چیز، درگاه‌های میزبان را از بازه‌ای مشترک برای کل میزبان تخصیص می‌دهد (پیش‌فرض ۴۲۰۰۰ تا ۴۹۹۹۹، در بلوک‌های ۳۲تایی). درگاه در تمام عمر محیط ثابت می‌ماند و درگاه‌های compose فقط به 127.0.0.1 مقید می‌شوند.

  • درگاه‌های compose نیازی به اعلام ندارند. آن‌ها را با {port.postgres.5432} یا CC_ENV_PORT_POSTGRES_5432 بخوانید.
  • درگاه‌های دیگر جایی که استفاده می‌شوند با "port": "web" یا "ports": ["web", "hmr"] اعلام و با {port.web} خوانده می‌شوند. فرایندی که درگاه دارد PORT و HOST=127.0.0.1 را هم می‌گیرد.

نقطه‌های پایانی HTTP یک URL روی مسیریاب سرور می‌گیرند که روی یک درگاه loopback گوش می‌دهد:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> شاخه به‌صورت slug است، یا در فضای PR مقدار pr-<n>. <project> همان naming.project است، وگرنه نام تعریف.
  • نام‌های *.localhost به loopback اشاره می‌کنند، پس به ورودی hosts یا DNS نیاز ندارند و نام میزبان کوکی‌ها را میان محیط‌ها جدا نگه می‌دارد.
  • درگاه‌های compose که به HTTP پاسخ می‌دهند شناسایی می‌شوند و http روی مؤلفه این حدس را جایگزین می‌کند. فرایند به "endpoint": { "role": "web", "primary": true } نیاز دارد که {url.web} را هم در دسترس می‌گذارد.
  • در مرورگر (VM)، از باز کردن در Browser (VM) استفاده کنید. آنجا https://web--fix-login--shop.localhost/ به همان مسیر می‌رسد.
  • کل برچسب در ۶۳ نویسه می‌ماند، پس نام‌های بلند با یک هش کوتاه می‌شوند.
  • دو نقطهٔ پایانی دامنهٔ والد مشترک ندارند. برنامه‌ای که یک کوکی برای هر دو می‌خواهد باید آن‌ها را از یک نقطهٔ پایانی ارائه کند.

برای URLهایی که باید از پیش ثبت شوند، مانند تغییرمسیرهای OAuth، "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } مجموعه‌ای ثابت از نام‌ها می‌دهد.

policy تعیین می‌کند محیط‌ها چه زمانی اجرا شوند. autoCreate مقدار off، prSpaces یا allSpaces دارد، پیش‌فرض idleStopMinutes عدد ۲۴۰ است، followPrHead با جابه‌جایی head محیط PR را همگام می‌کند و با maxRunning (پیش‌فرض ۶) دکمهٔ شروع پیشنهاد می‌کند محیطی که از همه دیرتر استفاده شده متوقف شود.

یک برنامهٔ وب و Postgres از یک فایل compose، با .env نادیده‌گرفته‌شده در git، مهاجرت‌ها و یک وظیفهٔ آزمون. seedFiles فایل‌های نام‌برده را از چک‌اوت ثبت‌شدهٔ شما به هر worktree تازه کپی می‌کند.

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks به سرویسی که بررسی سلامت خودش را ندارد اجازه می‌دهد مؤلفهٔ بعدی را نگه دارد. بدون آن، کانتینر در حال اجرا آماده شمرده می‌شود و مهاجرت‌ها ممکن است از پایگاه‌داده‌ای که هنوز بالا نیامده جلو بزنند.

هر شروع و تازه‌سازی با up همراه با --remove-orphans اجرا می‌شود، پس سرویسی که از فایل compose حذف شده متوقف می‌شود و پورتش آزاد می‌شود. تصاویر هنگام شروع و هنگام تازه‌سازی ساخته می‌شوند، مگر آنکه مؤلفه "build": false را تنظیم کرده باشد.

ابزار فرضی acme که کانتینرها، دامنه‌ها و TLS خودش را مدیریت می‌کند. Control Center مقدار {name} را می‌دهد و بقیه را از status می‌فهمد. هرگز نام میزبان ابزار را حدس نمی‌زند و هرگز /etc/hosts را ویرایش نمی‌کند.

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • create، status و destroy الزامی‌اند. Control Center از روی وضعیتی که می‌خواند create یا start را انتخاب می‌کند. هر فعل می‌تواند به‌جای argv مقدار { "shell": "…" } باشد.
  • interactive فعل‌هایی را نام می‌برد، از میان create، start و reset، که می‌توانند آنچه لازم دارند را در یک ترمینال بخواهند. وقتی چنین فعلی با کد ۳ خارج شود، برای کسی که شروع را زده، Control Center همان فعل را دوباره روی یک زبانهٔ ترمینال اجرا می‌کند و شروع پس از خروج با کد ۰ ادامه می‌یابد. آنجا شرط interactive درست است و CC_ENV_INTERACTIVE=1 تنظیم می‌شود، بنابراین { "if": "!interactive", "args": ["--json"] } خروجی ماشینی را برای لولهٔ پردازش نگه می‌دارد. شروعی که عامل یا خودکار انجام دهد هرگز ترمینالی باز نمی‌کند: محیط نیاز به اقدام را نشان می‌دهد و منتظر می‌ماند.
  • اگر destroy شکست بخورد، باز هم محیط حذف می‌شود، وقتی status پس از آن missing را گزارش کند؛ به این ترتیب محیطی که ابزار دیگر ندارد همیشه قابل حذف است.
  • list به Control Center امکان می‌دهد محیطی را که ابزار آن را از دست داده تشخیص دهد. محیط فقط وقتی گم‌شده علامت می‌خورد که نامش در list نباشد و status پس از آن missing بگوید. خروجی‌ای که نتوان آن را به‌صورت فهرست خواند چیزی را تغییر نمی‌دهد.
  • {service} در logs و exec باید یک واژه باشد که با - شروع نشود، و یکی از سرویس‌هایی باشد که ابزار آخرین بار گزارش کرده، وقتی گزارشی داده است.
  • statusMap JSON خود ابزار را با اشاره‌گرهای JSON می‌خواند و * با هر مورد مطابقت دارد. قواعد وضعیت مرتب‌اند و نخستین تطابق برنده است. شرط یا path با equals است، یا any یا none با where.
  • keepsDataOnStop: false توقف هنگام بیکاری را خاموش می‌کند و به توقف هشدار از دست رفتن داده می‌افزاید. وقتی توقف داده را از بین می‌برد آن را تنظیم کنید.
  • routing.mode: "tool" نام میزبان‌های ابزار را به مرورگر (VM) و عامل‌ها وصل می‌کند. دامنه باید به .test، .localhost یا .internal ختم شود و URL گزارش‌شدهٔ بیرون از آن کنار گذاشته می‌شود.

ابزاری که مال خودتان است می‌تواند statusMap را کنار بگذارد و قرارداد وضعیت توصیف‌شده در پایان این صفحه را چاپ کند.

فقط فرایندها و وظایف، بدون کانتینر. برنامهٔ وب API را از طریق {url.api} پیدا می‌کند.

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • هر فرایند یک زبانهٔ پایانه است که اگر دسترسی نوشتن به هر مخزن فضا را داشته باشید می‌توانید بازش کنید، بخوانید و در آن بنویسید (ببینید چه کسی چه چیزی را ذخیره می‌کند). بستن زبانه فرایند را متوقف نمی‌کند.
  • ready مقادیر http (یک URL کامل)، tcp (host:port) یا logMatch (عبارت منظم) را می‌گیرد. restart برابر on-failure (پیش‌فرض)، always یا never است. restartOn با تطابق مسیر تغییریافته فرایند را بازراه‌اندازی می‌کند.
  • options به فرمی روی شروع تبدیل می‌شوند و agentDefault برای اجراهایی است که عامل آغاز می‌کند.

یک برنامهٔ دسکتاپ با گام ساخت. برنامه با هر فناوری که ساخته شده باشد یکسان کار می‌کند، چون Control Center در سطح پنجره‌های سیستم‌عامل کار می‌کند و به هیچ hook یا SDK در برنامه نیاز ندارد.

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

برنامه با محیط آغاز نمی‌شود. کسی روی راه‌اندازی برنامه کلیک می‌کند و نخست prepare اجرا می‌شود. ساخت و راه‌اندازی دوباره این جفت را دوباره اجرا می‌کند. enabledWhen روی برنامه و روی وظیفهٔ prepare آن اعمال می‌شود، و تا وقتی هرکدام خاموش باشد راه‌اندازی برنامه رد می‌شود. برنامه تا وقتی هر فرایندی در گروه فرایندش اجرا شود در حال اجراست، پس اگر راه‌انداز برنامه را شروع کند و خارج شود، اشکالی ندارد. اگر همهٔ آن‌ها ظرف حدود ۵ ثانیه پس از راه‌اندازی برنامه از بین بروند، برنامه با آخرین خطوط گزارشش خطادار نشان داده می‌شود. پس از آن، خروج تمیز به‌صورت بسته و خرابی با آخرین خطوط گزارش نشان داده می‌شود و هیچ‌کدام دوباره اجرایش نمی‌کنند. بازراه‌اندازی سرور برنامه را می‌بندد و هرگز دوباره اجرایش نمی‌کند، و توقف هنگام بیکاری به برنامهٔ در حال اجرا کاری ندارد.

مجوزها و محدودیت‌های برنامهٔ دسکتاپ

بخش با عنوان “مجوزها و محدودیت‌های برنامهٔ دسکتاپ”
  • در macOS یک بار در تنظیمات سیستم به Control Center مجوز ضبط صفحه و دسترس‌پذیری بدهید. میزبان سرور به یک نشست گرافیکی نیاز دارد: سرور بدون رابط از اجرای برنامه خودداری می‌کند.
  • فایل دودویی را مستقیم اجرا کنید. open -a برنامه را به LaunchServices می‌سپارد و برنامه از درخت فرایندی که Control Center دنبال می‌کند خارج می‌شود، پس برنامه بلافاصله بعد از اجرا با خطا نشان داده می‌شود.
  • پنجره‌ها روی نمایشگر می‌مانند. macOS پنجره‌ای را که بیرون از همهٔ نمایشگرها باشد ضبط نمی‌کند، پس برنامه‌ای که عامل استفاده می‌کند روی صفحهٔ سرور دیده می‌شود. نیازی به فوکوس ندارد.
  • "isolate": "home" از طریق HOME، XDG_* و CFFIXED_USER_HOME یک پوشهٔ خانگی خصوصی به برنامه می‌دهد تا نسخه‌های دو فضا کنار هم اجرا شوند. NSUserDefaults جدا نمی‌شود، پس ترجیحات Cocoa و shared_preferences در Flutter میان نسخه‌ها مشترک می‌مانند.
  • isolate فقط روی فرایند اجراشده اثر دارد. اجراکنندهٔ زنجیرهٔ ابزار مانند flutter run به پوشهٔ خانگی واقعی نیاز دارد، پس isolate را با فایل دودویی ساخته‌شده به کار ببرید. اگر برنامه تنظیم خودش را دارد، مانند --user-data-dir، آن را ترجیح دهید.
  • عامل‌ها پنجره را با app_use می‌رانند که فقط به درخت فرایند این محیط می‌رسد. عامل پنجره را می‌بیند، نه دسکتاپ را. اجراهای عامل از سیاست کنش‌ها می‌گذرند و به‌طور پیش‌فرض می‌پرسند، و ورودی عامل تا زمانی که انسان کنترل را دارد متوقف می‌شود.
  • "input": "background" (پیش‌فرض) رویدادها را به فرایند می‌فرستد. "foreground" پنجره را فعال می‌کند و نشانگر را در اختیار می‌گیرد.

وظایف provision و archive اسکریپت راه‌اندازی و بایگانی هر مخزن را همراه با worktree آن اجرا می‌کنند. نماد روی ردیف مخزن در تنظیمات → فضای کاری → مخزن‌ها تعریف آن مخزن را باز می‌کند.

این وظایف از worktree پیروی می‌کنند، نه از محیط، پس در فضاهایی هم که کسی روی شروع نمی‌زند اجرا می‌شوند:

provision archive
اجرا هنگام ساخته شدن worktree نقش، در هر فضایی درست پیش از نابودی آن worktree
هنگام شکست آماده‌سازی شکست می‌خورد و worktree نابود می‌شود ثبت می‌شود و هرگز جلوی حذف را نمی‌گیرد
مهلت پیش‌فرض ۵ دقیقه ۲ دقیقه
می‌بیند CC_WORKSPACE_PATH، CC_ROOT_PATH، CC_SPACE_*، CC_REPO_NAME همان

مخزن بدون پشته فقط به تعریفی نیاز دارد که وظایفش را نگه دارد. چون چیزی برای آغاز نیست، نقش لنگر لازم نیست:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • هنوز محیطی وجود ندارد، پس این وظایف نمی‌توانند از {name}، {port.*}، {url.*}، {opt.*} یا enabledWhen استفاده کنند و env تعریف را نمی‌گیرند.
  • فقط یک تعریف می‌تواند وظایف provision و archive یک مخزن را داشته باشد. تعریف‌های دیگر همچنان می‌توانند برای کارهای دیگر آن را پیوند دهند.
  • "when": ["provision", "change"] هنگام تغییر فایل قفل هم دوباره نصب می‌کند.
  • وظیفه برای worktree نقش cwd خود اجرا می‌شود، پس تعریف چندمخزنی می‌تواند هر مخزن را جداگانه راه‌اندازی کند.
  • اجرای آزمایشی CC_SCRIPT_TEST=1 را تنظیم می‌کند. تلاش دوباره از worktree تمیز آغاز می‌شود، پس وظایفی بنویسید که اجرای دوباره را تاب بیاورند.

عامل‌ها هرگز سوکت Docker را نمی‌گیرند. در فضایی با تعریف واجد شرایط، هر اجرا cc-env را روی PATH خود دارد. فضا از اجرا می‌آید، پس عامل فقط روی محیط خودش می‌تواند عمل کند و هر فرمان از سیاست کنش‌ها می‌گذرد.

پنجرهٔ ترمینال
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

با مؤلفهٔ compose، یک shim برای docker همچنین docker compose را با ps، logs، exec، port، restart و top مجاز می‌کند، و فقط علیه پروژهٔ compose خود این محیط. پیش از فعل هیچ پرچمی نمی‌آید و هر فعل فهرست کوتاهی از گزینه‌ها دارد: logs نمی‌تواند خروجی را دنبال کند و exec فقط -T (یا --no-tty) را می‌پذیرد. گزینه‌هایی که compose را به فایل یا پروژهٔ دیگری می‌فرستند (-f، -p، --project-directory، --env-file، --profile) در هر جایی که بیایند رد می‌شوند. هر چیز دیگری با کد ۵ و پیام «not available in Control Center agent runs» پایان می‌یابد.

مخزنی که مهارت‌هایش ابزار خودش را صدا می‌زنند می‌تواند به این کار ادامه دهد. بلوک agentPassthrough روی مؤلفهٔ cli اعلام می‌کند عامل‌ها کدام فرمان‌ها را می‌توانند اجرا کنند. فقط فرمان‌هایی که تعریف تأییدشده اعلام می‌کند عبور داده می‌شوند، و هرکدام روی میزبان اجرا می‌شود، پس قاعدهٔ اجرای فرمان روی میزبان را دارد که به‌طور پیش‌فرض اول می‌پرسد:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps عملیاتی را نام می‌برد که سیاستش اعمال می‌شود. positionalName آن آرگومان را به محیط این فضا تحمیل می‌کند، nameFilter خروجی JSON را به آن محدود می‌کند و هر مقدار pathFlags باید به درون worktreeهای اجرا برسد. فرمانی که با هیچ قاعده‌ای مطابقت نداشته باشد با کد ۵ پایان می‌یابد.

همین عملیات به‌صورت ابزار هم هستند: environment_status، environment_up، environment_down، environment_reset، environment_destroy، environment_restart، environment_exec، environment_logs، environment_run_task، environment_launch_app و environment_stop_app. عامل‌های درون سندباکس مستقیم به درگاه‌هایشان و از طریق پراکسی اجرا به نام میزبان‌های محیطشان می‌رسند، پس بخواهید نقطه‌های پایانی را از environment_status بخوانند و URL را حدس نزنند.

کد یک PR از fork قابل اعتماد نیست و در جای‌گیری روی میزبان با کاربر سیستم‌عامل سرور اجرا می‌شود. policy.forkPrs تعیین می‌کند چه رخ دهد:

مقدار اثر پیش‌فرض برای
rig فایل compose بدون پرسش در VM اجرا می‌شود تعریف‌هایی که فقط مؤلفه‌های compose و task دارند
approval هر آغاز به مدیر نیاز دارد همهٔ تعریف‌های دیگر
deny رد می‌شود هیچ‌کدام
  • seedFiles هرگز برای fork کپی نمی‌شوند، چون معمولاً رازند. فایل compose که یکی از آن‌ها را مقید کند فایل گم‌شده را با نام گزارش می‌دهد.
  • وظایف provision و archive نادیده گرفته می‌شوند، مگر آنکه سیاست rig باشد که در این صورت در VM اجرا می‌شوند.
  • در جای‌گیری روی میزبان، privileged، فضای نام میزبان، مقیدسازی سوکت Docker، devices و مقیدسازی‌های بیرون از worktreeهای فضا روی fork رد می‌شوند. در فضاهای مورد اعتماد فقط هشدار می‌دهند.

"placement": "rig" مؤلفه‌های compose و task را در یک microVM اختصاصی اجرا می‌کند. تعریف‌هایی با مؤلفه‌های process، cli یا app واجد شرایط نیستند. فایل compose بدون تغییر اجرا می‌شود، بدون سوکت Docker میزبان و بدون اعتبارنامهٔ گرداننده، و دسترسی شبکه به رجیستری‌های موردنیاز ایمیج‌هایش محدود است. worktree به‌صورت زنده سوار می‌شود.

  • میهمان‌های arm64. میهمان‌ها روی Apple Silicon از نوع arm64 هستند، پس ایمیج‌های فقط amd64 اجرا نمی‌شوند.
  • رجیستری‌های خصوصی رد می‌شوند. میهمان‌ها اعتبارنامهٔ رجیستری ندارند، پس ایمیجی روی رجیستری بیرون از رجیستری‌های عمومی شناخته‌شده پیش از بوت VM رد می‌شود. مخزن خصوصی روی رجیستری عمومی هنگام دریافت میهمان شکست می‌خورد.
  • ۱۶ GiB فضا. همهٔ ایمیج‌ها و ولوم‌های پشته یک دیسک ۱۶ GiB را شریک‌اند و قابل افزایش نیست.
  • بوت نخست کند است. لایه‌های ایمیج برای هر VM جداست، پس بوت نخست همه‌چیز را دریافت می‌کند. rig متوقف‌شده دیسکش را نگه می‌دارد.
  • ایمیج پایه باید خواندنی باشد. Dockerfile که ایمیج پایه را با یک متغیر نام می‌برد قابل برنامه‌ریزی نیست، چون دسترسی شبکه هنگام بوت ثابت می‌شود.
  • طول عمر. policy.rigTtlHours به VM پایان می‌دهد، به‌طور پیش‌فرض پس از ۲۴ ساعت.

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

بخش با عنوان “قرارداد وضعیت برای سازندگان ابزار”

مؤلفهٔ cli بدون statusMap قرارداد بومی، cc-env/1، را انتظار دارد. فعل status این شیء را روی stdout چاپ می‌کند:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state یکی از ready، starting، stopped، failed یا missing است. missing به create می‌انجامد و stopped و failed به start. missing را با کد خروج ۰ گزارش کنید: status ناموفق failed حساب می‌شود.
  • فقط state لازم است. فیلدهای ناشناخته نادیده گرفته می‌شوند و خروجی غیرقابل تجزیه به‌صورت تنزل‌یافته نمایش داده می‌شود و متن خام جزئیات آن است.
  • URL باید loopback، *.localhost یا زیر routing.domain باشد، وگرنه کنار گذاشته می‌شود.
  • needsRecreate: true گزینهٔ ساخت دوباره را نشان می‌دهد که داده را دور می‌ریزد. Control Center هرگز خودسرانه بر اساس آن عمل نمی‌کند.
  • فعل list یک آرایهٔ JSON از نام‌ها، یا اشیایی با name چاپ می‌کند.

کدهای خروج برای همهٔ فعل‌ها معتبرند:

کد معنا
0 موفق
3 پاسخی در ترمینال لازم است، مانند رمز عبور sudo. فعلی که در interactive آمده دوباره روی یک زبانهٔ ترمینال برای کسی که شروع را زده اجرا می‌شود. وگرنه اجرا در ترمینال پایانهٔ فضایی را باز می‌کند که فرمان command ابزار در آن تایپ‌شده اما اجرا نشده، سپس تلاش مجدد دوباره تلاش می‌کند. Control Center هرگز sudo را اجرا نمی‌کند و به هیچ درخواستی پاسخ نمی‌دهد.
4 ورود به حساب لازم است. فرمان command ابزار نشان می‌دهد چگونه
5 چیزی که به آن وابسته است در دسترس نیست، مانند یک زمان‌اجرای کانتینر که در حال اجرا نیست
دیگر شکست

کدهای ۳، ۴ و ۵ شکست نیستند. محیط نیاز به اقدام را نشان می‌دهد و منتظر می‌ماند، و شروع بعدی از همان جایی ادامه می‌دهد که آن شروع متوقف شد. وظیفه‌ای که با یکی از آن‌ها خارج شود همین معنا را دارد.

پیشرفت به‌صورت JSON خط‌به‌خط به stderr می‌رود:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

هنگام شروع محیط، پنل مؤلفه‌هایی را که شروع از آن‌ها می‌گذرد فهرست می‌کند، هر کدام با یک چرخنده، تیک یا ضربدر. خط step نشان می‌دهد ابزار اکنون چه کاری انجام می‌دهد و label آن زیر ردیف خود ابزار دیده می‌شود؛ گام‌ها هرگز ردیف جدید اضافه نمی‌کنند. state یک گام pending، running، done یا failed است و گامی که state ندارد در حال اجراست. گامی که دوباره با همان id (رشته یا عدد، یا با همان label اگر شناسه نداشته باشد) گزارش دهد، جایگزین گفتهٔ قبلی‌اش می‌شود، پس ابزاری با یک چرخنده می‌تواند یک id را نگه دارد و فقط label را عوض کند. بدون شناسه، گام‌ها پشت سر هم می‌آیند: گام جدید گام قبلی را تمام می‌کند. وقتی فرمان خارج می‌شود، گامی که هنوز در حال اجراست همان‌طور پایان می‌یابد که فرمان پایان یافت.

خط log یک خط خروجی ابزار را که در JSON پیچیده شده دارد و مانند خروجی ساده خوانده می‌شود. خط note به خروجی اجرا می‌رود، و اگر "level": "warn" داشته باشد، به‌عنوان هشدار روی محیط هم می‌ماند. آخرین خط از نوع error به خطای ساختاریافته تبدیل می‌شود و command برای کپی پیشنهاد می‌شود، و ۱۲ خط آخر خروجی زیر message آن نشان داده می‌شود. بدون آن، Control Center آخرین ۲۰ خط stderr را نشان می‌دهد. هر چیزی که JSON نباشد خروجی گزارش عادی است.