Repo-szintű dev-szerverek
A Codumentor képes elindítani, nyilvántartani és leállítani hosszan
futó dev-szervereket az általa ismert repositorykhoz — legyen szó a
saját Django/Node/stb. projektedről, vagy magáról a Codumentorról
dogfooding közben. Egy deklaratív konfigurációs blokk, egy CLI
parancs (codumentor dev), egy közös nyilvántartás, amelyet a
codumentor dev status listáz.
Ez az oldal azoknak szól, akik a Codumentor konfigurációját
szerkesztik, és azoknak a fejlesztőknek, akik a .codumentor/
mappát huzalozzák be a repo-jukba. Az indító egygépes és
egyfelhasználós; a több gépre szétosztott ütemezés tudatosan kimaradt
a hatókörből.
Mikor használd
- Meg akarsz "nyitni" egy repót úgy, hogy közben a dev-szervere is felálljon mellé.
- Magán a Codumentoron iterálsz, és tiszta, URL-en elérhető előnézetre van szükséged worktree-nként.
Ha a dev-szervered rövid életű (egy parancs, egy terminál, te
Ctrl-C-zed le, amikor végeztél), nincs erre szükséged — maradj a
megszokott munkafolyamatnál.
Konfiguráció
Vegyél fel egy dev_server blokkot a meglévő, repo-szintű
project_setup bejegyzés alá (vagy a legfelső szintű
project_setup alá, ha csak egy repód van):
project_setup:
setup_script: .codumentor/setup.sh # opcionális; már támogatott
watch: # opcionális; már támogatott
- requirements.txt
dev_server:
command: "python -m myapp serve --port ${PORT}"
health_path: "/health" # opcionális; GET-nek 2xx-et kell adnia
open_url: "http://127.0.0.1:${PORT}/"
ready_timeout_seconds: 30 # opcionális; alap: 30
env: # opcionális, extra env a gyermek processznek
MYAPP_CONFIG: dev.yaml
Mező-hivatkozás
| Mező | Kötelező | Jelentés |
|---|---|---|
command | igen | Shell-szerű parancssor. A ${PORT} és minden más ${VAR} hivatkozás indításkor kerül behelyettesítésre. A gyermek processz örökli a szülő környezetét, plusz megkapja a PORT-ot és az env: alatt felsorolt változókat. |
health_path | nem | Ha meg van adva, az indító addig pollozza a GET http://127.0.0.1:${PORT}<health_path>-ot, amíg 2xx-et nem kap (vagy lejár az időkorlát). Enélkül csak a TCP-accept jelzi a készenlétet. |
open_url | nem | Az URL, amelyet az indító sikeres indítás után kiír, és amelyet a codumentor dev status is mutat. Alapértelmezés: http://127.0.0.1:${PORT}/. Ugyanúgy templatelhető, mint a command. |
ready_timeout_seconds | nem | Hány másodpercig várjon az indító, mielőtt sikertelennek nyilvánítja az indulást (alap: 30). |
env | nem | Extra környezeti változók a gyermek processznek. Az értékek templatelhetők. |
${VAR} templatelés
Az indító a Codumentor szokásos ${VAR} behelyettesítését használja.
Kétszer fut le:
- Betöltéskor: a valós env változók — pl.
${HOME}— feloldódnak a konfigurációs fájl beolvasásakor. A${PORT}literálként marad, mert ekkor még nincs beállítva a szülő környezetben. - Indításkor: egy második menet a
dev_serverblokkon, immárPORT=<lefoglalt>injektálással. Acommand,open_urlés azenv:alatti értékek itt kerülnek behelyettesítésre.
Ezért bátran keverheted a ${HOME}, ${VIRTUAL_ENV} és ${PORT}
hivatkozásokat bármelyik mezőben, és működni fog.
Port-foglalás
Az indító a :0-ra köt, kiolvassa a kernel által kiosztott portot,
majd elengedi az indítás előtt. Olcsó, és nem lehet vele
tartomány-kimerülést okozni. A portok nem stabilak az újraindítások
között — minden indítás új portot és új instance-azonosítót kap.
CLI: codumentor dev
Négy parancs. Mindegyik ugyanúgy értelmezi a --repo NAME
kapcsolót, mint a codumentor setup. Ha a --repo elmarad, az
indító a jelenlegi munkakönyvtárból következteti ki a repót.
codumentor dev [--repo NAME] [--no-wait]
Lefoglal egy portot, biztosítja a project_setup naprakészségét,
elindítja a dev_server.command-ot, regisztrálja az instance-t,
megvárja a healthcheck-et. A --no-wait átugorja a várakozást,
de továbbra is regisztrál.
codumentor dev status [--json]
Felsorolja a futó instance-okat. Először kireconcileálja a
halott PID-eket. A --json géppel feldolgozható kimenetet ad,
amely az árva processzeket is tartalmazza.
codumentor dev stop [--repo NAME | --id ID | --all]
SIGTERM-et küld a megfelelő instance-oknak, vár, majd időtúllépés
esetén SIGKILL következik; a registry-bejegyzéseket eltávolítja.
A három kapcsoló közül egyet meg kell adni — alapértelmezett
viselkedés szándékosan nincs.
codumentor dev logs [--repo NAME | --id ID] [-f/--follow] [-n N]
Kiírja vagy nyomon követi azt a logfájlt, amelybe egy instance ír.
A -f kapcsolóval addig streameli az új sorokat, amíg meg nem
szakítod, vagy le nem áll a szerver. A -n megadja, hány sort
írjon ki kezdéshez; a -n 0 a teljes fájlt kiírja.
Logok és hogy hol találod őket
Az elindított szerver stdout és stderr kimenete a
~/.codumentor/dev-logs/<instance-id>.log fájlba kerül. A fájl
csak-hozzáfűzésű; az indító soha nem rotálja és nem üríti. Minden
indítás új azonosítót (és így új fájlt) kap, ezért a lemezhasználat
indításonként egy fájllal nő.
A codumentor dev logs -f a szokásos módja a kimenet megnézésének:
$ codumentor dev logs -f
==> /home/me/.codumentor/dev-logs/codumentor-main-58231-a1b2c3.log [id=codumentor-main-58231-a1b2c3, repo=Codumentor, pid=12345, port=58231] (following — Ctrl-C to stop)
INFO: Started server process [12345]
INFO: Uvicorn running on http://127.0.0.1:58231 (Press CTRL+C to quit)
…
A follow-ciklus tisztán kilép, amint a szerver PID-je megszűnik —
így egy összeomlott szerverre futtatott logs -f visszatér ahelyett,
hogy lefagyna.
Instance kiválasztása
Ha csak egy előnézet fut, a CLI azt használja. Ha többet futtatsz,
válassz a --repo NAME (bármely egyedi repo) vagy a --id ID
kapcsolóval (a dev status listázza az azonosítókat). A hibaüzenet
felsorolja az érvényes lehetőségeket.
Árva processzek
A codumentor dev status külön szekcióban listázza azokat az élő
processzeket, amelyek hordozzák az indító belső markerét, de nincsenek
a registry-ben. Ezt akkor látod, ha törölték a registry-fájlt,
miközben a szerverek még futottak. Mindegyikhez kézi kill <pid>
tipp jár; a Codumentor szándékosan soha nem öli meg őket
automatikusan.
Korlátok, soft cap és erőforrás-igény
Minden előnézet egy teljes szerverprocessz — venv, sqlite, és bármi,
amit az alkalmazásod még behúz. Az indító figyelmeztetést ír az
stderr-re, ha 3 fölötti futó instance-od van. Kemény limit nincs;
a CI és a szkriptes hívók soha nem akadnak el, csak figyelmeztetést
kapnak.
Selfdev (a Codumentor saját dev_server-e)
A codumentor-localdev.yaml (a repository helyi fejlesztői konfigja a
Codumentor checkoutból történő fejlesztéséhez; nem része a kiadott
Codumentornak) egy működő dev_server blokkot tartalmaz, hogy magán a
Codumentoron is dogfoodolhasd az indítót:
project_setup:
dev_server:
command: "${VIRTUAL_ENV}/bin/codumentor -c codumentor-localdev.yaml api --port ${PORT}"
health_path: "/health"
open_url: "http://127.0.0.1:${PORT}/"
A scripts/setup-worktree.sh --dev felépít egy worktree-t (saját
venv + UI build), majd execcel egy codumentor dev-et benne. Ezután a
codumentor dev status worktree-nként egy sort mutat az URL-lel, a
codumentor dev stop --all pedig egyszerre leállítja mindet, amikor
végeztél.
Dev-szerverek és a sandbox
A codumentor dev a hoston fut, a workspace isolation sandboxon kívül. A
konfigurált checkoutot (vagy azt a worktree-t, amelyből futtatod) indítja
el, nem egy beszélgetés sandboxát, ezért nem látszanak benne az ügynök
sandboxban lévő, nem commitolt változásai.
Izolált beszélgetésben ugyanez a dev_server blokk **a beszélgetés
sandboxában** is futhat, és az Előnézetben nyílik meg. Ehhez kell az
előnézet saját sandbox originje (api.app_preview.sandbox_origin, az
előnézet app szintje) és a háttérfolyamatok.
- A chat fejlécéből: Előnézet → Fejlesztői szerver indítása. A Codumentor elindítja a szervert, megvárja a health checket, és megnyitja az előnézetet. Amíg fut, ugyanez a menü Fejlesztői szerver leállítása pontot kínál, az előnézet eszköztárán pedig van egy ■ Stop gomb.
- Az ügynöktől: az ügynök
dev_server_start/dev_server_stopeszközpárt kap. A háttérfolyamat azonosítóját, a health állapotot és a log útvonalát tudja meg; siker esetén az előnézet a chathez tűzve, kártyával jelenik meg.
Így használja a blokkot:
| Mező | A sandboxban |
|---|---|
command | A repository könyvtárából fut, hálózat nélküli háttérfolyamatként. A PORT értéke 5173 (minden folyamatnak saját hálózati névtere van, így a port mindig szabad). A CODUMENTOR_PREVIEW_BASE az az URL-útvonal, amely alatt az előnézet kiszolgálja; állítsd erre a szerver base path-ját (vite --port ${PORT} --base ${CODUMENTOR_PREVIEW_BASE}, Astro base, Next basePath). |
env | A folyamat környezetéhez adódik. |
health_path | Az előnézet forwarderén át kérdezi le, előbb a base path alatt, aztán anélkül. Nélküle bármilyen HTTP-válasz elég. |
ready_timeout_seconds | Meddig vár az indítás a health checkre (alapértelmezés 30). Az addig nem egészséges szerver tovább fut; ilyenkor is kitűzi és megnyitja, így látod az állapotjelzőjét és a logját, az ügynök pedig megkapja az állapotát és a log útvonalát. |
open_url | Nem használja: az előnézetnek saját URL-je van. |
Az indításkori ${VAR} kör csak a PORT-ot és a CODUMENTOR_PREVIEW_BASE-t
látja. A hostváltozókat (pl. ${HOME}) már a konfig betöltésekor
feloldotta, a megmaradt hivatkozásokat pedig a sandbox shellje bontja ki. A
szerver a megengedett leghosszabb futásidővel indul
(background_processes.default_max_runtime_seconds), és nem éli túl a
Codumentor újraindítását. Az a kitűzött előnézet, amelynek a szervere már
nem fut, Dev server not running üzenetet mutat, és újra felkínálja az
indítást. Ha innen semmi nem tudja elindítani — az ügynök saját előnézeti
porttal indította, vagy nincs dev_server blokk —, ezt jelzi: kérd meg az
ügynököt, hogy indítsa el újra.
Állapotjelző és log
Az előnézet eszköztárán, a ■ Stop mellett látszik, hogy áll a szerver:
| Jelzés | Jelentés |
|---|---|
| Running | A folyamat fut, és átmegy a health checken (health_path; ha nincs, bármilyen HTTP-válasz elég). |
| Starting… | A folyamat fut, de még nem válaszol, és fiatalabb a ready_timeout_seconds-nál. |
| Unhealthy | A folyamat fut, de ennél régebben nem válaszol. A buborék megnevezi a sikertelen ellenőrzést. |
| Exited (code N) | A folyamat véget ért. |
A jelzés néhány másodpercenként frissül, amíg az előnézet nyitva van
(gyakrabban, amíg a szerver nem egészséges), és azonnal, amikor a folyamat
véget ér.
A ≡ Log az előnézet fölötti panelen mutatja a szerver kimenetének utolsó
200 sorát, és nyitva tartva frissíti. Ugyanaz a kimenet, mint a háttérfolyamat
kártyáján, és csak te olvashatod.
Hibaelhárítás
| Tünet | Valószínű ok |
|---|---|
No repo … has a dev_server.command | A használt konfiguban nincs dev_server blokk, vagy --repo-val olyan repót adtál meg, amelyikben nincs. |
| Health check 30 másodperc után meghiúsul | Növeld a ready_timeout_seconds értékét, vagy nézd meg a codumentor dev logs-ot — lehet, hogy a processz nem tud bindelni. |
A dev status halott instance-t mutat | A következő CLI-hívás reconcile-passza eldobja; a codumentor dev status futtatása is kikényszeríti. |
Árva processz a dev status-ban | A registry-t törölték (vagy a CODUMENTOR_DEV_REGISTRY átírásával máshová mutattak), miközben egy gyermek tovább futott. Kézzel öld meg a felsorolt PID-et — a Codumentor nem teszi. |
| Nincs Fejlesztői szerver indítása az Előnézet menüben | Egyik repositoryban sincs dev_server.command, az előnézetnek nincs sandbox originje, vagy ki vannak kapcsolva a háttérfolyamatok. |
| Az indítás időtúllépést jelez | A szerver nem adott időben 2xx választ a health_path-ra. Az előnézet így is megnyílik, Unhealthy jelzéssel: nyisd meg a ≡ Log-ot. A CODUMENTOR_PREVIEW_BASE-t figyelmen kívül hagyó szervert a base alatt nélküle is megtalálja. |
| A jelzés Exited | A szerver összeomlott vagy leállították. A ≡ Log mutatja az utolsó kimenetét; a Fejlesztői szerver indítása (vagy az ügynök) újat indít. |
Lásd még
- Design dokumentum — a teljes terv, beleértve a fázisokat és azt, ami szándékosan kívül esik a hatókörön.