Egységes Docker-fejlesztés

A gyökér Compose deployment checkoutonként egy elszigetelt MailGen-példányt futtat. Egy közös Nginx Proxy Manager (NPM) külön életciklussal és állandó állapottal rendelkezik. Ez egygépes Docker Compose, nem Docker Swarm.

Az első setuptól a napi munkáig

A parancsokat a motherrepo gyökerében futtasd. Kezdd az első fejlesztői setuppal és a környezeti konfigurációval. A tmux a meglévő konténerterminálokat jeleníti meg. Nem indít másik host-alkalmazást.

Elhelyezés

Gyökérkiválasztás	Helyi szolgáltatások	Felhasználás
Hiányzó kiválasztók vagy fulllocal / false	Alkalmazások és a kiválasztott összes infrastruktúra	Teljes helyi indítás
partialRemote / true	Valódi helyi infrastruktúra és helyi értékek	A remote konfigurációs útvonal gyakorlása
partialRemote / false	Alkalmazások, PostgreSQL, SeaweedFS/S3, OpenSearch, Dragonfly, proxy és kulcsok	Előkészített remote Kafka, ClamAV, Collabora, Tika és Qdrant

A szimuláció nem mock és nem memóriatakarékos remote deployment. A fulllocal a true szimulációs értékkel érvénytelen. Az inaktív remote beállítások nem aktiválnak távoli szolgáltatásokat. A runtime az aktív fogyasztói beállításokat memóriában származtatja.

Az elhelyezés nem választja ki a development vagy a production végrehajtást. Nem mozgatja a Kafka-offseteket és a Qdrant-pontokat. A meglévő célok módosítása előtt töltsd ki a remote szerződést.

Első setup

Végezd el az első installation útmutatót, beleértve a repository-jogosultságokat, a Dockert, a gyökérkonfigurációt, a provider-callbacket és a titkosfájlokat.

Hideg bootstrap előtt nézd meg a terhelést:

free -h
uptime
docker ps
tmux list-sessions
bash memmonitor.sh

A free -h Linuxra és WSL-re vonatkozik. macOS-en a Docker Desktop erőforrásait és az Activity Monitort nézd. A tmux-session hiánya nem jelenti, hogy az alkalmazás hibás. A monitorból a Ctrl+C billentyűvel lépj ki.

Hideg bootstrap vagy reset előtt válassz ki egy aktív, teljes példányt. Csak a kiválasztott példányt állítsd le a saját checkoutjából, és őrizd meg a volume-jait. A nem kapcsolódó szolgáltatások maradjanak futva. A különálló hálózatok nem jelentenek külön fizikai RAM-ot.

bash 0daysetup.sh
bash devstack.sh status

A setup hiányzó származtatott értékeket ad hozzá, ellenőrzi a konfigurációt, a tulajdonost és a memóriát, előkészíti a közös proxyt és a kliensroutingot, majd production végrehajtással indít. A FormGen és a docs-mcp kifejezetten van kiválasztva. A Google-választás a provider-jelölőktől függ. Ha a setup leáll, javítsd a jelentett előfeltételeket. Ne törölj adatot.

Napi életciklus

Cél	Parancs	Eredmény
Konfiguráció ellenőrzése	bash devstack.sh validate	Érvénytelen bemenetet utasít el a titkok megjelenítése nélkül
Images építése	bash devstack.sh build	Images-eket épít, de nem bizonyítja az alkalmazás készenlétét
Új teljes development indítás	bash startDevServers.sh	Függőség-előkészítés, inicializálás és development folyamatok
Ennek a példánynak a leállítása	bash stopDevServer.sh	Leállítja a kezelt alkalmazásokat és a helyi infrastruktúrát, megőrzi a volume-okat és a kulcsokat
Konfiguráció alkalmazása production-újraépítés nélkül	bash restartDevServers.sh	Újra létrehozza a szolgáltatásokat a mentett módokkal. A lefordított artifactok változatlanok.
Lefordított production kiválasztása	bash startDevServers.sh --prod vagy bash restartDevServers.sh --prod	Lefordított kimenetet épít, és production végrehajtást választ
Változatlan konténerek folytatása	bash quickStarter.sh	Elindítja a kompatibilis, leállított meglévő konténereket build, újralétrehozás, Prisma vagy bootstrap nélkül

A normál újraindítás nem futtat inicializáló jobokat vagy sémamigrációt. Nem építi újra a production artifactokat. A módosított, lefordított kódot a bash restartDevServers.sh --prod paranccsal publikáld, külön szükséges séma- vagy függőség-előkészítés után. Egy szolgáltatáshoz használd a célzott hotfix eljárást.

A gyors indítás korábbi sikeres előkészítést igényel. Elutasítja az elavult konfigurációt vagy az inkompatibilis konténereket. Ne szerkeszd a fingerprint-értékeket az elutasítás megkerüléséhez. Konfigurációs vagy forrásváltozás után használd a sima újraindítást.

Célzott helyreállítás és profilok

bash devstack.sh restart bff
bash devstack.sh start bff
bash devstack.sh start bff --prod

A célzott start és restart a mentett végrehajtást folytatja. A start SERVICE --prod kifejezetten production módot választ az adott szolgáltatásra. A célzott restart elutasítja a --prod opciót. A mentett állapot nélküli új szolgáltatás folytatáskor alapértelmezés szerint development módot kap. Lásd a végrehajtási módokat.

A célzott starthoz előkészített függőségek kellenek. Nem bootstrapel hiányzó infrastruktúrát, és nem aktivál letiltott providert. A globális endpoint-, hitelesítő-adat- vagy elhelyezésváltozáshoz teljes sima újraindítás kell.

A választható profilok további szolgáltatásokat adnak hozzá. A tools az inicializáló segédeket, a lab a Kafka-laboratóriumi eszközöket, a docs-mcp a dokumentációs MCP-t adja hozzá. A FormGen- és a Google-profilok a saját alkalmazásaikat választják ki. A provider-jelölők származtatják a Google OAuth-, szinkronizálási és figyelési kiválasztást.

Böngésző- és megfigyelhető ellenőrzések

Nyisd meg a kiírt Account- és BFF HTTPS-címeket. Végezd el az első bejelentkezést, csatlakoztass vagy válassz egy engedélyezett mailboxot, és oldd fel a megfelelő személyes e-mail-kulcsot. Új bejelentkezés nem állítja helyre a régi kulcsot.

Ellenőrizd az üzenettörzseket, a keresést, az érintett funkciót és a művelet megerősítését. Az elfogadott vagy awaiting_confirmation állapotú írások nem megerősített provider-állapotok. Nézd meg a műveletet és egy későbbi kanonikus olvasást.

Naplók és terminálok

bash devstack.sh status
bash devstack.sh logs bff
bash devServerAttach.sh

A Ctrl+C a naplónézést fejezi be. Csatolt szolgáltatásterminálban a szolgáltatást is leállíthatja. A Ctrl+P, majd a Ctrl+Q lecsatolja a terminált leállítás nélkül. Ne indíts duplikált Node- vagy .NET-folyamatot. Az interaktív start és prod az adott szolgáltatás development vagy lefordított végrehajtását választja ki.

Konfiguráció és indítási sorrend

Az egységes stack a gyökér .env fájlt olvassa. A környezeti referencia leírja az összes megtartott változócsoportot. Soha ne tegyél közzé nyers docker compose config kimenetet, mert a feloldott értékek titkokat tartalmazhatnak.

Bemenet	Felelősség
BETTER_AUTH_URL, NEXT_PUBLIC_BETTER_AUTH_URL	Egymásnak megfelelő, külső Account HTTPS-originek
BFF_MICROSOFT_CLIENT_ID, BFF_MICROSOFT_CLIENT_SECRET, BFF_MICROSOFT_TENANT_ID	Alkalmazásbejelentkezés
BACKEND_CLIENT_ID, BACKEND_CLIENT_SECRET, BACKEND_TENANT_ID	Backend/.NET app-only Graph-hozzáférés
DATABASE_URL, BETTERAUTH_DATABASE_URL, POSTGRES_CONNECTION_STRING	Egymással konzisztens, belső adatbázis-kapcsolatok
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD	Új adatbázis-inicializálás
S3_*, SEAWEEDFS_ADMIN_USER, SEAWEEDFS_ADMIN_PASSWORD	Objektum-hozzáférés és külön tárolási adminisztráció
KAFKA_UI_USER, KAFKA_UI_PASSWORD	UI-bejelentkezés, a broker SASL-jától elkülönítve
GRAPH_WEBHOOK_URL, GRAPH_LIFECYCLE_WEBHOOK_URL	Ennek a példánynak a nyilvános értesítési callbackjei
CLOUDFLARE_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_ZONE_ID	DNS- és tunnel-automatizálás
PROXY_ADMIN_BIND_IP, ECS_PROXY_STATE_DIR	Közös proxy-adminisztráció és állapot
ECS_CPUSET, ECS_BUILD_CPUSET	Runtime- és build-CPU-listák

A csak szerveren használt BFF API_URL és SORTER_SERVER_URL Docker DNS-t használ. Nem böngészőből elérhető nyilvános endpointok. Az alkalmazásbejelentkezési és a Graph-hitelesítő adatokat tartsd szét. Lásd a Microsoft Graph setupot.

Az indítás ellenőrzi a konfigurációt, a tulajdonost, a megtartott visszagörgetési állapotot és a memóriát. Leállítja a régi alkalmazásírókat, előkészíti az állapotot és a tunnelt, buildeli az images-eket, előkészíti a függőségeket, és buildeli a .NET-segédprogramokat. Az adatbázis- és mailboxinicializálás előtt megvárja az infrastruktúrát. A Kafka- és függőség-előellenőrzés megelőzi az alkalmazásindítást. Ezt proxy-egyeztetés és webhook-ellenőrzések követik. A Stack ready az indítás befejezését jelzi, nem sikeres mailboxba írást.

A setup támogatja a meglévő konfigurációt, az archívumjelszót vagy a chip '<passphrase>' '<token>' --decrypt formát. A régi --chbranch és --pinned viselkedés nem része ennek a belépési pontnak.

Szolgáltatások és élő fejlesztés

Az alkalmazás-szolgáltatások külön konténerekben futnak, példányspecifikus bind mountokkal és cache volume-okkal. A development watcherek betöltik a forrásváltozásokat. A függőségváltozások újra igényelhetik a teljes, szabályozott előkészítési útvonalat. Egyedül a restart nem futtatja ezt az útvonalat. A production lefordított artifactokat használ, a kódkiadáshoz pedig explicit build kell. A production docs-hoz a megfelelő build kell. A development npm start a forrást figyeli.

A backend, a BFF, a dokumentáció és a .NET függőség- és build-jobok a függő szolgáltatások előtt lefutnak. A generált kliensek és az adatbázissémák maradjanak kompatibilisek. Őrizd meg a leképezett táblákat, a kulcsokat és az idegen kulcs-műveleteket. A destruktív sémakülönbség leállási feltétel, nem ok arra, hogy --accept-data-loss opciót adj hozzá.

A gyökér életciklus-szkriptek kezelik a Docker indítását és leállítását. A régebbi host-folyamat- és tmux-szkriptek nem alapértelmezett alternatívák. A leállítás megőrzi a tartós volume-okat. A reset kifejezett adattörlési szándékot igényel.

Átnézett forrás meglévő adatokkal

Az ECS_APPLICATION_SOURCE_ROOT egy meglévő fizikai forráskönyvtárat vagy átnézett pillanatképet választ az alkalmazás- és runtime-mountokhoz, valamint a FormGen image-forrásokhoz. Hiányzó, üres vagy . érték az aktuális checkoutot tartja meg.

A kiválasztott útvonalnak léteznie kell a Docker-hoston, és olvashatónak kell lennie. A forrásválasztás nem változtatja meg a Compose-projektet, a klón tulajdonosát, a gyökér .env fájlt, az alkalmazás-volume-okat, az engedélyezési kulcsokat, a Graph-tanúsítványokat vagy a közös proxyt. A generált kliensek és build-kimenetek az eredeti példány cache volume-jaiban maradnak.

Ha a munkamásolat szerkesztéseit nem szabad a megtartott adatokon futtatni, használj azonosított repository-revíziót. Indítás előtt ellenőrizd a pillanatkép-manifestet. A választó nem hoz létre és nem hitelesít pillanatképet. Az életciklus-parancsokat az eredeti checkoutban tartsd. Soha ne mutasd egy másik példány konfigurációs vagy adatkönyvtárára.

Az újraindítás továbbra is a rögzített forrást futtathatja, nem a szerkesztett checkoutot. A production rögzítéseket csak egyeztetett kódkiadással cseréld le. Lásd az átnézett forrású hotfixeket.

Közös proxy és HTTPS

Az NPM a klónok ingress-hálózataihoz csatlakozik, és a hosztneveket példányonkénti aliasokra irányítja. Az alkalmazáshálózatok és az adatvolume-ok elkülönülnek. Az alkalmazás-konténereknek nincs szükségük nyilvános host-portra. A közös proxy állapota túléli az alkalmazás leállítását.

Példa aliasok a beni példányhoz:

Böngészős hosztnév	NPM-cél	Belső port
bff.beni.ecas.local	beni-bff	5173
kafka.beni.ecas.local	beni-kafka	8080
seaweed.beni.ecas.local	beni-seaweed	5600
docs.beni.ecas.local	beni-docs	3000
prisma.beni.ecas.local	beni-prisma	5555

Ezek példák. Használd a saját példányod generált URL-jeit, beleértve az Account-címet és a kiválasztott FormGen-hosztot.

Automatikus NPM-beállítás és ismétlődés elleni védelem

Az automatizálás a hostok létrehozása előtt újra ellenőrzi az erőforrásokat. Megőrzi a meglévő hostokat, tanúsítványokat, hozzáférési listákat és adminisztrátori hitelesítő adatokat. Az NPM nem kínál kötegelt tranzakciót. Ha egy későbbi művelet sikertelen, a korábban létrehozott erőforrások megmaradnak, azonosítóikkal együtt a helyreállításhoz. A proxyhiba jelentést kap anélkül, hogy egy egyébként futó stacket megsemmisítene.

Tanúsítványok megkeresése és megbízhatóvá tétele a kliensen

bash configureNpmProxyHosts.sh --show

Ez abszolút tanúsítványútvonalakat és kliensutasításokat mutat, NPM-bejelentkezés vagy stack-módosítás nélkül. A generált tanúsítványok auto-* könyvtárakban lehetnek. Az újrahasznosított nyilvános tanúsítványok .docker-state/certs/npm-ID.crt néven exportálhatók.

Bízz meg abban a nyilvános tanúsítványban, amelyet az alkalmazásod NPM-hosztja ténylegesen használ. Csak .crt fájlokat másolj a kliensekre. A privát .key fájlokat tartsd a szerveren.

WSL-ből nyisd meg a helyi tanúsítványkönyvtárat:

explorer.exe "$(wslpath -w "$PWD/.docker-state/certs")"

Windowson másold a nyilvános tanúsítványt a Letöltések mappába proxy.crt néven. PowerShellben:

certutil.exe -user -addstore Root "$env:USERPROFILE\Downloads\proxy.crt"

Ez az aktuális Windows-felhasználóra nézve bízik meg a tanúsítványban. macOS-en nyisd meg a Keychain Access → login → File → Import Items menüpontot (a macOS angol menüneveivel). Válaszd ki a nyilvános tanúsítványt. Nyisd meg a Trust részt, és állítsd a Secure Sockets Layer (SSL) → Always Trust értékre. Ha kéri, hitelesítsd magad.

Indítsd újra a böngészőt, és nyisd meg a teljes HTTPS-URL-t, általában a :8443 porttal. A --show kiírja az utasításokat, de nem módosítja a kliens megbízhatósági tárolóját. Az öntanúsított tanúsítványokat lejárat előtt újítsd meg. Őrizd meg a fájljaikat és a közös NPM-állapotot a helyreállításhoz.

A szabványos Force SSL átirányítás elvesztheti a nem szabványos HTTPS-portot, és a klienseket 443-ra küldheti. Tartsd letiltva, hacsak egy ellenőrzött átirányítás meg nem őrzi a tényleges portot. Az Account OAuth-callbacket külön regisztráld. A tanúsítvány megbízhatósága nem helyettesíti a callback-regisztrációt. Soha ne tiltsd le az alkalmazás TLS-ellenőrzéseit a megbízhatóság javítására.

WebSockets és sütiszinkronizáció

Az automatikus setup a docker/proxy/websocket.conf.example fájlt alkalmazza a klón BFF-aliasával. Ez a /ws és a /ws/... útvonalat fedi le. Ne adj mellé duplikált GUI/Advanced helyeket.

A fő BFF-útvonal az oldalakhoz és a Next HMR-hez az 5173 portot használja. A WebSocket-útvonal a 6589 portra mutat. A /ws előtagot pontosan egyszer távolítsd el HTTP-átirányítás nélkül. Őrizd meg a $http_host értéket, benne a :8443 porttal, a böngésző Origin fejlécét, a sütiket, valamint az Upgrade és Connection fejlécet.

A példában szereplő példány egyenértékű kézi útvonala:

location = /ws {
    proxy_pass http://beni-bff:6589/;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}
location /ws/ {
    proxy_pass http://beni-bff:6589/;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

A böngésző a wss://bff.beni.ecas.local:8443/ws címet használja. A sütiszinkronizáció a /ws/zilaws/cookieSync útvonalat használja, amelynek a belső /zilaws/cookieSync útvonalhoz kell érnie. Ellenőrizd a hitelesített RPC-t, a sütiszinkronizációt, az újracsatlakozást, a munkamenet lejáratát és a provider újracsatlakozását. Egyedül a 101 válasz nem elegendő.

Ha a docs-mcp ki van választva, irányítsd a docs /mcp/ útvonalat a beni-docs-mcp:3456 címre, és távolítsd el az előtagot egyszer. Állítsd be a tényleges nyilvános MCP-URL-t. Ha nem fut endpoint, a vezérlés maradjon letiltva.

Nyilvános Graph webhook-bemenet

Indítás előtt végezd el a Cloudflare-bemeneti előfeltételeket és a tulajdonosi mentést. Mindkét Graph-callbackhez használd a saját nyilvános HTTPS-doménedet és tunneledet. Ezeket a WebhookCatcherre irányítsd, nem az IUDG-re. A GRAPH_WEBHOOK_CLIENT_STATE értéke legyen stabil. A Microsoft nem éri el a localhostot. Lásd a Graph-kulcsokat és tanúsítványokat.

Sikertelen feliratkozási kihívás esetén ellenőrizd a nyilvános DNS-t, a TLS-t, a proxy-útvonalat és a WebhookCatcher-naplókat úgy, hogy közben nem feded fel a validációs titkot.

Memória, elszigetelés és adatmegőrzés

A támogatott ECS_MEMORY_GIB profilok: 8, 12, 16, 30, 35, 40 és 44. Ha nincs megadva, a 30 a választott. A kiválasztott szolgáltatások határozzák meg a szükséges minimumokat. Az ezek alatti profil leállítja az indítást. A teljes standard kiválasztás 40 GiB-ot, a teljes Google/Microsoft/FormGen kiválasztás 44 GiB-ot használ. A host- és build-tartalékok ezen felül vannak.

A bounded szolgáltatáskorlátokat alkalmaz. A hybrid Docker systemd cgroups v2-t és nem interaktív sudo-t igényel. Az ECS_SWAP_GIB állítja be a további swap-keretet. Lásd a környezeti referenciát.

A konténerek alapértelmezés szerint legfeljebb 20 logikai CPU-ból álló, beállítható készletet osztanak meg. A nem megadott runtime- és build-listák külön, a Dockerből látható CPU-kból származnak. A megadott listáknak létező CPU-kat kell tartalmazniuk. A CPU, a RAM és a swap a klónok között megosztott.

Az egyedi példányazonosítók elkülönítik a hálózatokat, a volume-okat és a tulajdonlást. Másik klón azonosítójának újrahasználata tulajdonosi ellenőrzésen bukik el. Ez nem teszi biztonságossá két teljes hideg indítást. A szolgáltatás cgroup-memóriahibája célzott korlátkorrekciót és újraindítást igényel. A host-szintű RAM- vagy swap-kimerüléshez host-bizonyíték kell. Az OOMKilled=true önmagában nem elegendő.

Adatmegőrzés helyreállítás közben

A normál leállítás és újraindítás megőrzi a volume-okat. A projekt reset a meghatározott, saját adat-volume-ok egy részét törli. Olvasd el a pontos reset-határt. A sima down -v egy másik, szélesebb hatókörű művelet. A remote elhelyezés a reset és a cleanup kérést akkor is elutasítja, ha szimuláció fut. Ne változtass elhelyezést a védelem megkerülésére. A konfiguráció, az adatbázis, az objektumtároló és a titkosítási kulcsok mentéseit külön tartsd meg.

Ellenőrzés és hibaelhárítás

Tünet	Ellenőrzendő
A konténer Up, az alkalmazás nem elérhető	A szolgáltatás készenléte és a tényleges worker/alkalmazás-folyamat
502 újralétrehozás után	Ingress-hálózat, alias, készenlét és a proxy upstream DNS-frissítése
A bejelentkezés 443-ra tér vissza	A pontos nyilvános origin és a :8443 portot megőrző átirányítás
A gyors indítás elavult állapotot utasít el	Sima újraindítás a helyes forrással és konfigurációval, nem fingerprint-szerkesztéssel
A Graph-szinkronizálás megakad	Provider setup, partícióhozzárendelés, webhook-életciklus, delta-projekció és S3-hozzáférés
Memóriahiba	A kiválasztott profil, a tényleges host- és Docker-tartalék, valamint a szolgáltatás- vagy host-OOM-bizonyíték

Átadás előtt ellenőrizd az érintett böngészős folyamatot, a WebSocket- és sütiútvonalat, a fájlhozzáférést és az adatmegőrzést a ténylegesen támogatott gépen. Egyedül a konfigurációvalidálás nem igazolja ezeket az eredményeket.