Konfigurera miljöer
En miljö är den körande stacken för en yta: tjänsterna en gren behöver, isolerade från alla andra ytor, synliga i sidofältet och nåbara för agenter. Pull requests får också en, eftersom en PR redan har en egen yta.
En administratör för arbetsytan skriver en definition en gång. Medlemmar klickar sedan på Starta i avsnittet Miljö i sidofältet för en yta eller PR. Definitioner finns i arbetsytans databas, så en funktionsgren ändrar aldrig vad Control Center kör, även om verktygen fortfarande kör grenens kod.
Skapa en definition
Avsnitt med rubriken “Skapa en definition”- Öppna Inställningar → Arbetsyta → Miljöer. Bara administratörer för arbetsytan kan ändra definitioner, och bara serverägaren kan spara en som körs på serverns värd (se Vem kan spara vad).
- Klicka på Ny definition och sedan på Tom definition eller Utkast från repo. Ett utkast söker igenom repot efter compose-filer, en
Procfileochpackage.json-skript, och du granskar resultatet. - Fyll i formuläret eller använd fliken JSON. Exemplen på den här sidan är den JSON:en.
- Klicka på Kör test. Det startar en engångsmiljö, väntar tills den är klar och förstör den.
Spara kontrollerar en definition strikt. Ett okänt fält, ett värde av fel typ eller ett felstavat val avvisas, med sin sökväg och det närmaste giltiga namnet, till exempel repos.app.requird: Unknown field. Did you mean "required"?. Ett $schema på översta nivån är tillåtet.
Använd Länka en repofil för att ha en definition i ett repo. Control Center läser filen bara från standardgrenen och kör bara den version som godkänts: av en arbetsytadministratör, eller av serverägaren när definitionen körs på värden. En nyare version visar Uppdatering tillgänglig och ändrar inget förrän den godkänns.
Vem kan spara vad
Avsnitt med rubriken “Vem kan spara vad”En miljödefinition kan köra kommandon på serverns värd som serverns egen användare. Det är serverägarens beslut, inte en arbetsytaroll:
- En definition körs på värden när den har värdplacering, en kontroll som kör ett kommando, eller en
provision- ellerarchive-uppgift. De uppgifterna körs i ytans worktree på värden oavsett placering. - Bara serverägaren kan spara eller godkänna en definition som körs på värden. Det gäller även att godkänna en ny version av en länkad repofil. En arbetsytadministratör som försöker ser “Bara serverägaren kan spara eller godkänna en miljö som körs på serverns värd. En arbetsytadministratör kan använda en som körs i en rigg.”
- En arbetsytadministratör kan spara och godkänna en definition som helt körs i en rigg:
"placement": "rig", ingen kontrollkommando och ingenprovision- ellerarchive-uppgift. - Medlemmar startar, stoppar och använder miljöer i båda fallen.
- En definition som körs på värden körs först efter att den nuvarande serverägaren har sparat eller godkänt den. Servern registrerar godkännandet själv och kontrollerar det före varje start, kontroll, uppgift och synkning av PR:ens huvud. En definition som den nuvarande ägaren inte har godkänt, till exempel en som en tidigare ägare sparade, väntar under sin rad i miljölistan och i redigeraren. Serverägaren ser “Körs på den här servern. Godkänn den för att låta den starta.” med Godkänn, som sparar den oförändrad; alla andra ser “Körs på den här servern. Serverägaren måste godkänna den innan den kan starta.”
- En miljö som hålls för det godkännandet säger “Serverägaren har ännu inte godkänt den här miljön, så den kan inte köras på den här servern.” Serverägaren ser i stället “Du har ännu inte godkänt den här miljön. Den körs på den här servern och startar när du godkänner dess definition.” med Granska och godkänn, som öppnar definitionen.
- En miljös processterminaler, och terminalen som en start öppnar när den behöver dig, körs på serverns värd. Att skriva i en, ändra dess storlek eller stänga den kräver skrivåtkomst till varje repo som ytan exponerar, läsbar via din egen forge-inloggning: samma krav som för att starta miljön. Andra når inte de terminalerna alls.
Den minsta definitionen
Avsnitt med rubriken “Den minsta definitionen”Ett enkelt compose-repo behöver bara detta:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Allt annat har ett standardvärde: compose-filen hittas, alla tjänster körs, portar tilldelas, HTTP-slutpunkter upptäcks och miljön får namn efter grenen.
Komponenttyper
Avsnitt med rubriken “Komponenttyper”En miljö är en ordnad lista med komponenter. Varje komponent väntar tills den föregående är klar, om inte after anger andra, och stopp sker i omvänd ordning. enabledWhen gör en komponent beroende av ett alternativ eller en roll, till exempel opt.seed, !opt.seed eller repo.web. En komponent vars roll är valfri och saknas i ytan utelämnas på samma sätt, utan att någon enabledWhen behövs: den startar inte och har varken {port.*} eller {url.*}, så en annan komponent som läser dem gör att starten misslyckas.
| Typ | Vem som kör den | Används till |
|---|---|---|
compose |
Control Centers compose-drivrutin | Alla compose-filer, en per miljö |
cli |
Ditt verktyg. Control Center anropar mappade verb och läser JSON | Ett verktyg som äger sin livscykel, sina domäner och data |
process |
Control Center, i en övervakad terminalsession | Utvecklingsservrar och workers |
task |
Control Center, en gång per utlösare | Installationer, migreringar, tester |
app |
Control Center, när någon klickar på Öppna | En skrivbordsapp |
task-komponenter tar en when-lista:
| Utlösare | Körs |
|---|---|
provision |
När worktree skapas (se worktree-uppgifter nedan) |
create |
En gång per miljö, och igen efter en återställning |
start |
Vid varje start |
change |
Efter en synkronisering, när en ändrad sökväg matchar onChange |
manual |
På begäran: Kör, cc-env run <id> eller environment_run_task |
archive |
Precis innan worktree förstörs |
En task som inte har något att göra vid en start visar Overksam och utelämnas från listan över steg som visas medan miljön startar: en manual- eller change-task, eller en create-task som redan har körts.
Ett kommando som anges som en array är argv, så alternativvärden går aldrig genom ett skal. En sträng, eller script med en array av rader, körs under bash -lc. Platshållare som {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} och {url.<role>} expanderas bara i argv. Skalkommandon läser samma värden som CC_ENV_*-variabler, till exempel $CC_ENV_PORT_WEB. En okänd platshållare i en komponent som deltar stoppar starten innan något körs.
Varje kommando och ytterminal får också CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> och, i PR-ytor, CC_PR_NUMBER och CC_PR_IS_FORK. Med en compose-komponent får de även COMPOSE_PROJECT_NAME och COMPOSE_FILE, så att docker compose exec i en uppgift når rätt projekt.
Roller och arbetskatalog
Avsnitt med rubriken “Roller och arbetskatalog”En definition binder roller till arbetsytans repon, så att en stack kan omfatta flera repon:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: en yta kan starta miljön när den har minst en ankarroll. Om två definitioner matchar väljer den som startar.required: stacken kan inte köras utan det här repot.whenMissing: vad som händer när ytan saknar rollen.addToSpacelägger till repot på standardgrenen och är standard förrequired-roller.useSourceskickar din registrerade utcheckning, som du bör behandla som skrivskyddad.skiplämnar variabeln tom och är annars standard.- För att starta krävs en
write-behörighet på ett ankarrepo i ytan och läsåtkomst till alla andra bundna repon.
Ett kommando körs i den första rollen som deklareras i repos, aldrig i någon annan roll som ytan råkar ha, så en definition med ett repo nämner det aldrig. Alla komponenter kan åsidosätta det med "cwd": { "role": "e2e", "path": "packages/ui" }. Båda fälten är valfria. Om den första rollen kan saknas i en yta, eftersom den varken är required eller den enda ankaren, måste varje komponent ange sin roll.
Portar och URL:er
Avsnitt med rubriken “Portar och URL:er”Control Center tilldelar värdportar innan något startar, från ett intervall för hela värden (42000 till 49999 som standard, i block om 32). En port förblir densamma under miljöns hela livstid, och compose-portar binder bara till 127.0.0.1.
- Compose-portar behöver inte deklareras. Läs dem som
{port.postgres.5432}ellerCC_ENV_PORT_POSTGRES_5432. - Andra portar deklareras där de används, med
"port": "web"eller"ports": ["web", "hmr"], och läses som{port.web}. En process med en port får ocksåPORTochHOST=127.0.0.1.
HTTP-slutpunkter får en URL på serverns router, som lyssnar på en enda loopback-port:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>är grenen som slug, ellerpr-<n>i en PR-yta.<project>ärnaming.project, annars definitionens namn.*.localhost-namn pekar på loopback, så de behöver varken hosts-poster eller DNS, och värdnamnet håller isär cookies mellan miljöer.- Compose-portar som svarar på HTTP upptäcks, och
httppå komponenten åsidosätter gissningen. En process behöver"endpoint": { "role": "web", "primary": true }, som också gör{url.web}tillgänglig. - Använd Öppna i Browser (VM) i webbläsaren (VM).
https://web--fix-login--shop.localhost/når samma väg där. - Hela etiketten håller sig inom 63 tecken, så långa namn kortas med en hash.
- Två slutpunkter delar ingen överordnad domän. En app som behöver en cookie över båda måste servera dem från en slutpunkt.
För URL:er som måste registreras i förväg, till exempel OAuth-omdirigeringar, ger "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } en fast uppsättning namn.
policy avgör när miljöer körs. autoCreate är off, prSpaces eller allSpaces, idleStopMinutes är 240 som standard, followPrHead synkroniserar en PR-miljö när dess head flyttas, och med maxRunning (standard 6) erbjuder Starta att stoppa den miljö som använts minst nyligen.
Exempel: compose-app
Avsnitt med rubriken “Exempel: compose-app”En webbapp och Postgres från en compose-fil, med en git-ignorerad .env, migreringar och en testuppgift. seedFiles kopierar namngivna filer från din registrerade utcheckning till varje ny 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" } ]}Med healthchecks kan en tjänst utan egen hälsokontroll hålla tillbaka nästa komponent. Utan den räknas en körande container som klar, och migreringar kan hinna före en databas som fortfarande startar.
Varje start och uppdatering kör up med --remove-orphans, så att en tjänst som tagits bort från compose-filen stoppas och frigör sin port. Images byggs vid start och uppdatering om inte komponenten sätter "build": false.
Exempel: egen CLI
Avsnitt med rubriken “Exempel: egen CLI”Ett påhittat verktyg acme som äger sina containrar, domäner och TLS. Control Center ger {name} och får veta resten från status. Det härleder aldrig ett verktygs värdnamn och redigerar aldrig /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,statusochdestroykrävs. Control Center väljercreateellerstartutifrån statusen det läser. Alla verb kan vara{ "shell": "…" }i stället för argv.interactiveanger vilka verb, avcreate,startochreset, som kan be om det de behöver i en terminal. När ett sådant verb avslutas med kod 3 för en person som tryckte på Starta, kör Control Center samma verb igen i en terminalflik, och starten fortsätter när det avslutas med 0. Där är villkoretinteractivesant ochCC_ENV_INTERACTIVE=1är satt, så att{ "if": "!interactive", "args": ["--json"] }behåller maskinutdata för det icke-interaktiva läget. En start av en agent, eller en automatisk start, öppnar aldrig en terminal: miljön visar Åtgärd krävs och väntar.- Ett
destroysom misslyckas tar ändå bort miljön närstatussedan rapporterarmissing, så att en miljö som verktyget inte längre har alltid kan tas bort. listlåter Control Center upptäcka en miljö som verktyget har tappat bort. Den markeras som borta först när dess namn saknas ilistochstatusdå sägermissing. Utdata som inte kan läsas som en lista ändrar ingenting.{service}ilogsochexecmåste vara ett enda ord som inte börjar med-, och en av de tjänster som verktyget senast rapporterade, när det rapporterade några.statusMapläser verktygets egen JSON med JSON-pekare, där*matchar varje objekt. Tillståndsregler är ordnade och den första träffen vinner. Ett villkor ärpathmedequals, elleranyellernonemedwhere.keepsDataOnStop: falsestänger av stopp vid inaktivitet och lägger till en varning om dataförlust på Stoppa. Ange det när stopp förlorar data.routing.mode: "tool"kopplar verktygets värdnamn till webbläsaren (VM) och agenter. Domänen måste sluta på.test,.localhosteller.internal, och en rapporterad URL utanför den släpps.
Ett verktyg du äger kan hoppa över statusMap och skriva ut statuskontraktet som beskrivs i slutet av den här sidan.
Exempel: pnpm-monorepo
Avsnitt med rubriken “Exempel: pnpm-monorepo”Bara processer och uppgifter, inga containrar. Webbappen hittar API:et via {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"] } ]}- Varje process är en terminalflik som du kan öppna, läsa och skriva i, om du har skrivåtkomst till varje repo i ytan (se Vem kan spara vad). Att stänga fliken stoppar inte processen.
readytarhttp(en fullständig URL),tcp(host:port) ellerlogMatch(ett reguljärt uttryck).restartäron-failure(standard),alwaysellernever.restartOnstartar om processen när en ändrad sökväg matchar.optionsblir ett formulär vid Starta, ochagentDefaultgäller körningar som en agent startar.
Exempel: skrivbordsapp
Avsnitt med rubriken “Exempel: skrivbordsapp”En skrivbordsapp med ett byggsteg. En app fungerar likadant oavsett vad den är byggd med, eftersom Control Center arbetar på operativsystemets fönsternivå och inte behöver någon hook eller SDK i appen.
{ "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" } ]}En app startar inte med miljön. Någon klickar på Öppna, och prepare körs först. Bygg om och öppna igen kör det paret igen. enabledWhen gäller för appen och för dess prepare-uppgift, och Öppna nekas så länge något av dem är avstängt. En app räknas som körande så länge någon process i dess processgrupp kör, så en startare som startar appen och avslutas är okej. Om allt är borta inom cirka 5 sekunder efter Öppna visas appen som misslyckad med dess sista loggrader. Därefter visas en ren avslutning som stängd och en krasch visar de sista loggraderna, och ingetdera startar om den. En omstart av servern stänger appen och startar den aldrig om, och stopp vid inaktivitet lämnar en körande app i fred.
Behörigheter och begränsningar för skrivbordsappar
Avsnitt med rubriken “Behörigheter och begränsningar för skrivbordsappar”- På macOS ger du Control Center Skärminspelning och Hjälpmedel en gång i Systeminställningar. Servervärden behöver en grafisk session: en headless-server vägrar starta en app.
- Starta binärfilen direkt.
open -alämnar över appen till LaunchServices och den lämnar processträdet som Control Center följer, så att appen visas som misslyckad direkt efter starten. - Fönster stannar på en skärm. macOS fångar inte ett fönster som ligger utanför alla skärmar, så en app som en agent använder syns på serverns skärm. Den behöver inte fokus.
"isolate": "home"ger appen en privat hemkatalog viaHOME,XDG_*ochCFFIXED_USER_HOME, så att kopior från två ytor kan köras sida vid sida.NSUserDefaultsisoleras inte, så Cocoa-inställningar och Fluttersshared_preferencesförblir delade mellan kopior.isolategäller bara den startade processen. En verktygsstartare somflutter runbehöver den riktiga hemkatalogen, så kombineraisolatemed en byggd binärfil. Om appen har en egen inställning, som--user-data-dir, är den att föredra.- Agenter styr fönstret med
app_use, som bara når den här miljöns processträd. En agent ser fönstret, inte skrivbordet. Agentstarter går genom åtgärdspolicyn och frågar som standard, och agentinmatning stoppas medan en person har kontrollen. "input": "background"(standard) skickar händelser till processen."foreground"aktiverar fönstret och tar över markören.
Worktree-uppgifter
Avsnitt med rubriken “Worktree-uppgifter”provision- och archive-uppgifter kör ett repos uppsättning och nedmontering tillsammans med dess worktree. Ikonen på ett repos rad under Inställningar → Arbetsyta → Arkiv öppnar repots definition.
De här uppgifterna följer worktree, inte miljön, så de körs i ytor där ingen klickar på Starta:
provision |
archive |
|
|---|---|---|
| Körs | När rollens worktree skapas, i vilken yta som helst | Precis innan den worktree förstörs |
| Vid fel | Provisioneringen misslyckas och worktree förstörs | Registreras, blockerar aldrig borttagning |
| Standardtidsgräns | 5 minuter | 2 minuter |
| Ser | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Samma |
Ett repo utan stack behöver bara en definition med sina uppgifter. Eftersom det inte finns något att starta behövs ingen ankarroll:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Det finns ingen miljö ännu, så de här uppgifterna kan inte använda
{name},{port.*},{url.*},{opt.*}ellerenabledWhen, och de får inte definitionensenv. - Bara en definition får ha
provision- ocharchive-uppgifter för ett repo. Andra får ändå binda det för allt annat. "when": ["provision", "change"]installerar också om när en låsfil ändras.- En uppgift körs för worktree i sin
cwd-roll, så en definition med flera repon kan konfigurera varje repo separat. - En testkörning sätter
CC_SCRIPT_TEST=1. Ett nytt försök börjar från en ren worktree, så skriv uppgifter som tål att köras om.
Agenter får aldrig Docker-socketen. I en yta med en lämplig definition får en körning cc-env på sin PATH. Ytan kommer från körningen, så en agent kan bara agera på sin egen miljö, och varje kommando går genom åtgärdspolicyn.
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>Med en compose-komponent tillåter en docker-shim också docker compose med ps, logs, exec, port, restart och top, och bara mot den här miljöns egna compose-projekt. Inga flaggor får stå före verbet, och varje verb tar en kort lista med alternativ: logs kan inte följa, och exec tar bara -T (eller --no-tty). Alternativ som pekar compose mot en annan fil eller ett annat projekt (-f, -p, --project-directory, --env-file, --profile) nekas var de än står. Allt annat avslutas med kod 5 och “not available in Control Center agent runs”.
Ett repo vars skills anropar ett eget verktyg kan fortsätta med det. Ett agentPassthrough-block på en cli-komponent anger vilka kommandon agenter får köra. Bara kommandon som den godkända definitionen deklarerar passerar igenom, och varje ett körs på värden, så det bär regeln Kör kommandon på värden, som frågar först som standard:
"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 anger vilken operations policy som gäller. positionalName tvingar det argumentet till den här ytans miljö, nameFilter filtrerar JSON-utdata till den och varje pathFlags-värde måste leda in i körningens worktrees. Ett kommando som inte matchar någon regel avslutas med kod 5.
Samma operationer finns som verktyg: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app och environment_stop_app. Agenter i sandlåda når sina portar direkt och miljöns värdnamn via körningens proxy, så be dem läsa slutpunkter från environment_status i stället för att gissa en URL.
Pull requests från forkar
Avsnitt med rubriken “Pull requests från forkar”Koden i en fork-PR är inte betrodd, och vid värdplacering körs den som serverns OS-användare. policy.forkPrs avgör vad som händer:
| Värde | Effekt | Standard för |
|---|---|---|
rig |
Compose-filen körs i en VM utan fråga | Definitioner med bara compose- och task-komponenter |
approval |
Varje start kräver en administratör | Alla andra definitioner |
deny |
Nekas | Inga |
seedFileskopieras aldrig för en fork, eftersom de oftast är hemligheter. En compose-fil som binder en sådan rapporterar den saknade filen med namn.provision- ocharchive-uppgifter hoppas över om inte policyn ärrig, då de körs i VM:en.- Vid värdplacering nekas
privileged, värdens namnrymder, en bindning av Docker-socketen,devicesoch bindningar utanför ytans worktrees på en fork. I betrodda ytor ger de bara en varning.
Rig-placering
Avsnitt med rubriken “Rig-placering”"placement": "rig" kör compose- och task-komponenter i en dedikerad microVM. Definitioner med process-, cli- eller app-komponenter är inte lämpliga. Compose-filen körs oförändrad, utan värdens Docker-socket och utan operatörens autentiseringsuppgifter, och nätverksåtkomsten begränsas till de register som dess avbildningar behöver. Worktree monteras direkt.
- arm64-gäster. Gäster är arm64 på Apple Silicon, så avbildningar som bara finns för amd64 körs inte.
- Privata register nekas. Gäster har inga registeruppgifter, så en avbildning på ett register utanför de kända offentliga nekas innan VM:en startar. Ett privat repository på ett offentligt register misslyckas när gästen hämtar det.
- 16 GiB lagring. Alla avbildningar och volymer i stacken delar en disk på 16 GiB, och den går inte att utöka.
- Första starten är långsam. Avbildningslager är per VM, så första starten hämtar allt. En stoppad rig behåller sin disk.
- Basavbildningar måste gå att läsa. En Dockerfile som anger sin basavbildning via en variabel kan inte planeras, eftersom nätverksåtkomsten bestäms vid start.
- Livslängd.
policy.rigTtlHoursavslutar VM:en, som standard efter 24 timmar.
Statuskontrakt för verktygsförfattare
Avsnitt med rubriken “Statuskontrakt för verktygsförfattare”En cli-komponent utan statusMap förväntar sig det inbyggda kontraktet, cc-env/1. Verbet status skriver ut det här objektet på 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ärready,starting,stopped,failedellermissing.missingleder tillcreate,stoppedochfailedleder tillstart. Rapporteramissingmed slutkod 0: en misslyckadstatusräknas somfailed.- Bara
statebehövs. Okända fält ignoreras, och utdata som inte kan tolkas visas som försämrad, med råtexten som detalj. - En URL måste vara loopback,
*.localhosteller underrouting.domain, annars släpps den. needsRecreate: truevisar Återskapa, vilket kastar data. Control Center agerar aldrig på det på egen hand.- Verbet
listskriver ut en JSON-array med namn, eller med objekt som har ettname.
Slutkoder gäller för alla verb:
| Kod | Betydelse |
|---|---|
| 0 | OK |
| 3 | Ett svar krävs i en terminal, till exempel ett sudo-lösenord. Ett verb som står i interactive körs igen i en terminalflik för personen som tryckte på Starta. Annars öppnar Kör i terminal en ytterminal med verktygets command inskrivet men inte kört, och Försök igen försöker sedan igen. Control Center kör aldrig sudo och svarar aldrig på en fråga |
| 4 | Inloggning krävs. Verktygets command anger hur |
| 5 | Något som den är beroende av är inte tillgängligt, till exempel en containerkörning som inte är igång |
| Annan | Fel |
Koderna 3, 4 och 5 är inte fel. Miljön visar Åtgärd krävs och väntar, och nästa start fortsätter där den förra stannade. En uppgift som avslutas med någon av dem betyder samma sak.
Förlopp går till stderr som radavgränsad JSON:
{"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"}Medan en miljö startar visar panelen de komponenter som starten går igenom, var och en med en snurrande indikator, en bock eller ett kryss. En step-rad anger vad verktyget gör just nu, och dess label visas under verktygets egen rad; steg lägger aldrig till rader. Ett stegs state är pending, running, done eller failed, och ett steg utan state körs. Ett steg som rapporterar igen under samma id (en sträng eller ett tal, eller samma label om det saknas) ersätter det det sa tidigare, så ett verktyg med en enda snurrande indikator kan behålla samma id och ändra label. Utan id följer stegen på varandra: ett nytt avslutar det föregående. När kommandot avslutas avslutas ett steg som fortfarande körs på samma sätt som kommandot.
En log-rad innehåller en rad utdata som verktyget paketerat i JSON och läses som vanlig utdata. En note-rad går till körningens utdata, och en rad med "level": "warn" finns också kvar på miljön som en varning. En sista rad av typen error blir ett strukturerat fel, där command erbjuds för kopiering, och de sista 12 raderna utdata visas under dess message. Utan den visar Control Center de sista 20 stderr-raderna. Allt som inte är JSON är vanlig loggutdata.