Codumentor logo Codumentor Enterprise

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

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
commandigenShell-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_pathnemHa 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_urlnemAz 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_secondsnemHány másodpercig várjon az indító, mielőtt sikertelennek nyilvánítja az indulást (alap: 30).
envnemExtra 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:

  1. 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.
  2. Indításkor: egy második menet a dev_server blokkon, immár PORT=<lefoglalt> injektálással. A command, open_url és az env: 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.

Így használja a blokkot:

MezőA sandboxban
commandA 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).
envA folyamat környezetéhez adódik.
health_pathAz 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_secondsMeddig 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_urlNem 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ésJelentés
RunningA 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.
UnhealthyA 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ünetValószínű ok
No repo … has a dev_server.commandA 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úsulNö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 mutatA következő CLI-hívás reconcile-passza eldobja; a codumentor dev status futtatása is kikényszeríti.
Árva processz a dev status-banA 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übenEgyik 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 jelezA 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 ExitedA 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