MailGen setup új gépen

Végezd el a MailGen setupját új macOS- vagy Debian-gépen. Utána jelentkezz be, és nyiss meg egy csatlakoztatott postafiókot. Ez az útmutató az egységes Docker Compose-t használja. A BFF szolgálja ki a böngészős munkaterületet. Az Account kezeli a bejelentkezést. A háttérworkerek és a .NET-szolgáltatások dolgozzák fel a postafiók-adatokat.

A kezdő útvonal

Az alábbi sorrend egy teljes helyi setupot állít be a következőkkel:

Választás	Ez az útvonal
Infrastruktúra	ECS_DEPLOYMENT_MODE=fulllocal, ECS_REMOTE_SIMULATION=false
Alkalmazásbejelentkezés	Microsoft az Account szolgáltatáson keresztül
Postafiókok	Microsoft és személyes Gmail
Gmail-frissítések	Előzménylekérdezés: OAuth és szinkronizáció bekapcsolva, watch kikapcsolva
Végrehajtás	Fordított production-kód a 0daysetup.sh szerint
További alkalmazások	FormGen és docs-mcp, a setup választása szerint
Alkalmazásmemória	ECS_MEMORY_GIB=44, plusz gép- és build-tartalék
Forrás és konfiguráció	Ez a checkout (.), új gyökér .env, üres tárolók

Microsoft kiválasztása előtt nézd meg az Egy postafiók csatlakoztatása és előkészítése részt. A Microsoft-bejelentkezéshez és a postafiók-csatlakoztatáshoz létező, megmaradt bérlőkapcsolat kell, megadott hozzájárulással és használható hitelesítő adatokkal. Környezeti hitelesítő adatok önmagukban nem jelenítik meg ezeket a műveleteket üres adatbázisban. Ez az útmutató nem ad teljes Microsoft-bootstrapet üres adatbázishoz, és nem ad első kapcsolatot létrehozó parancsot. A Microsoft-útvonalat csak akkor kövesd, ha ez a kapcsolat már létezik. Az onboarding worker később, az identitás-összekapcsolás és a jóváhagyott indítási kérés után hozza létre a postafiókot.

Kövesd a számozott sorrendet ezekkel a választásokkal. Az indítás előtt teljesítsd a csatolt Microsoft- és Gmail-előfeltételeket. Ehhez az útvonalhoz nincs szükség Google-alkalmazásbejelentkezésre, mert a felhasználók Microsofttal jelentkeznek be.

Archívum-migráció, csak Google, valódi távoli infrastruktúra, Gmail push és production forrás-rögzítés alternatívák. Ezeket a megfelelő szakaszok írják le, nem kötelező köztes lépések. Megőrzött adatokhoz használd a konfiguráció visszaállítását, és őrizd meg az eredeti azonosítókat és kulcsokat. Ne generálj helyettük újakat.

Az oldal teljes hosszában ugyanazt az operációsrendszer-fület válaszd. Másold a parancsokat a Terminálba, nyomj Entert, és várd meg a promptot, mielőtt folytatod. A későbbi projektparancsokat a t42-motherrepo gyökérkönyvtárából futtasd.

Meglévő deploymenthez használd a napi parancsokat. Ne ismételd meg az új gépes setupot csak az infrastruktúra-elhelyezés módosításához.

A komponensek megértése

A Docker elkülönített konténerekben futtat programokat. A tartós kötetek tárolják az adataikat. A program újraindítása és a kötet törlése más hatású.

Komponens	Feladat	Valódi partialRemote helye
BFF	Böngészős felület és szerveroldali böngészőkérések	Helyi
Account	Alkalmazásbejelentkezés és munkamenetek	Helyi
Backend és .NET szolgáltatások	Feldolgozás, szinkronizáció, keresés	Helyi
PostgreSQL	Felhasználók, beállítások, postafiók-rekordok, előzmények	Helyi
SeaweedFS/S3	Törzsek, mellékletek, egyéb fájlok	Helyi
OpenSearch	Keresési indexek	Helyi
Dragonfly	Cache és ideiglenes koordináció	Helyi
Kafka, három broker	Parancsok és események a szolgáltatások között	Távoli Coolify
ClamAV	Feltöltött fájlok ellenőrzése	Távoli Coolify
Collabora	Office-dokumentum-előnézetek	Távoli Coolify
Tika / knowledge-extractor	Dokumentumszöveg-kinyerés	Távoli Coolify
Qdrant	Tudásbázis-lekérdezési vektorok	Távoli Coolify

A Coolify kezeli a távoli erőforrásokat. A távoli deployment itt nem mozgatja át az egész alkalmazást. A fulllocal módban az utolsó öt sorban szereplő infrastruktúra is helyben fut. Lásd az architecture-áttekintést.

0. Olvasd el a setupot a teljes alkalmazás nélkül

Ha a repository le van töltve és a Docker fut:

bash docsStarter.sh

Futtasd a motherrepo gyökeréből vagy egy önálló Architecture-checkoutból. Nincs szüksége gyökér .env-re vagy alkalmazásbeállításra. Nyisd meg a kiírt localhost-URL-t. A Ctrl+C eltávolítja a saját eldobható dokumentációs konténerét. A statikus build működéséhez olvasd el az önálló dokumentációt.

1. Szerezz hozzáférést és őrizd meg az adatokat

A setup előtt szerezd meg:

• GitHub-hozzáférés a t42-hu/t42-motherrepo repository-hoz és minden szükséges privát submodule-repository-hoz.
• Értékek egy új, üres gyökérkonfigurációhoz. Megőrzött setuphoz az archívum egy alternatíva. A jelszavát külön kell megkapnod.
• Account-bejelentkezési hitelesítő adatok és callback-regisztráció.
• Microsoft Graph alkalmazás-jogosultságok és adminisztrátori hozzájárulás, ha a Microsoft van kiválasztva.
• Google OAuth-kliensek és opcionális Pub/Sub-útvonal, ha a Google van kiválasztva.
• Saját nyilvános HTTPS webhook-domain és Cloudflare-kezelőtoken és tulajdonjog-beállítás.
• Valódi távoli szolgáltatásokhoz ellenőrzött endpointok, külön tokenek és jelszavak, a Kafka-fürt azonosítója és a Tailscale-hozzáférés.

A Coolify-irányítópult jelszava nem pótolja a szolgáltatói hitelesítő adatokat. A .local hosztnév nem fogadhat felhőszolgáltatói webhookokat.

Megőrzött adatokhoz szerezd meg az adatbázis- és objektumtároló-mentéseket, valamint a meglévő titkosítási, aláírási és hozzáférési kulcsokat. Őrizd meg a deployment példány- és bérlőazonosítóit. Új gép és új konfiguráció nem állítja vissza a régi postafiók-adatokat.

Az onboarding létrehozza a kezdeti helyi postafiók-adatokat, a fájlobjektumokat, a keresési adatokat és a szinkronizációs állapotot. A szolgáltatói postafiók a Gmailnél vagy a Microsoftnál marad.

Gépkapacitás

Kiválasztott terhelés	Explicit alkalmazás-keret
Standard teljes stack Google-worker profil nélkül	ECS_MEMORY_GIB=40
Teljes Microsoft + Google + FormGen stack	ECS_MEMORY_GIB=44

Ez az útmutató a teljes 44 GiB-os választást követi. Az alkalmazás-keret nem a teljes gép RAM-ja. A futásidejű admisszió a kért alkalmazás-kereten kívül legalább 3 GiB-ot tart fenn. A build-admisszió a kért build- és szolgáltatásmemórián túl szintén 3 GiB-ot tart fenn. Egy 3 GiB-os kezdeti build-kérés ezért legalább 6 GiB szabad memóriát igényel. Production build több memóriát igényelhet.

A kihagyott keret alapértelmezése 30 GiB. Sem a 30, sem a 35 GiB nem fér bele a teljes standard választás jelenlegi minimumaiba. Ne csökkentsd a szolgáltatási alsó határokat csak azért, hogy átjusson az admisszión. Kisebb, szándékosan kiválasztott terhelésnek saját allokátor- és gépkapacitás-ellenőrzés kell. A swap nem pótolja a RAM-ot.

macOS-en állíts be elegendő RAM-ot a Docker Desktop → Settings → Resources menüben a kerethez és a tartalékhoz. A kisebb gép- vagy Docker VM-kapacitás dönt. Debianon számolj a többi gépi terheléssel.

A helyi szimuláció valódi helyi infrastruktúrát tart meg, és nem csökkenti a kapacitást. A valódi távoli mód megváltoztatja a helyi kiválasztást, de mért helyi és távoli kapacitást igényel.

2. Végezd el a Terminal-eszközök setupját

macOS

Nyisd meg a Terminal alkalmazást a Spotlighton keresztül. Végezd el a Homebrew setupját a hivatalos paranccsal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Futtasd a setup által kiírt Next steps lépéseit, hogy elérhető legyen a brew. Utána:

brew install git gh python openssl@3 unzip zip tmux
brew install --cask docker
open -a Docker

Várd meg, amíg a Docker Desktop fut. Állíts be elegendő erőforrást, majd alkalmazd a változtatásokat.

Debian

Használj Debian 12 vagy 13 rendszert sudo jogosultsággal:

sudo apt-get update
sudo apt-get install -y ca-certificates curl git python3 openssl unzip zip tmux

A következő blokk hozzáadja a Docker hivatalos Debian-tárolóját. Meglévő Docker-gépen előbb nézd meg a szállító ütköző csomagokra vonatkozó utasításait.

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF_DOCKER
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF_DOCKER
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Jelentkezz ki a gépből, majd jelentkezz be újra, hogy érvényesüljön a Docker-csoporttagság. A Docker-csoport adminisztratív hozzáférést ad. Csak az üzemeltetői fióknak add meg.

Ellenőrizd az eszközöket:

git --version
python3 --version
docker version
docker compose version

A Dockernek mutatnia kell a Client és a Server részt is. Kapcsolódási hiba azt jelenti, hogy a Docker még nem érhető el. Az alkalmazásszolgáltatások konténerekben futnak, ezért ez az útvonal nem igényel külön hoszt-Next.js vagy .NET setupot.

Más Linux-disztribúciók a Docker-útvonalat használhatják, ha a Debian-csomagok setupját az adott disztribúció hivatalos utasításaival helyettesítik.

3. Töltsd le az alkalmazást

Használj olyan GitHub-fiókot, amely hozzáfér az összes privát repositoryhoz. A gh auth login egyszer használatos kódot ír ki, és megnyitja a GitHubot. Add meg a kódot, jelentkezz be, hagyd jóvá a GitHub CLI-t, és szükség esetén végezd el a szervezeti SSO-t. Ha a böngésző nem nyílik meg, használd a kiírt URL-t. Várd meg, amíg a Terminal sikert jelez.

A submodule-URL-ek SSH-t használnak. Ez az új gépes útvonal HTTPS-re írja át őket, hogy a GitHub CLI külön SSH-kulcs nélkül adhasson hitelesítő adatot. A globális átírás az operációsrendszer-felhasználó összes GitHub-repositoryját érinti. SSH-ra szándékosan beállított gépen előbb egyezz meg a változtatásról az üzemeltetővel.

Soha ne írj személyes hozzáférési tokent vagy jelszót parancsba, klónozási URL-be vagy a shell-előzményekbe. A GitHub CLI kezeli a hitelesítő adatokat. Ha a GitHub CLI titkosítatlan szöveges fájlban történő tárolás jelzését adja, nézd át a hitelesítő adatok védelmét az üzemeltetővel. Az URL-átírás nem ad repository-hozzáférést.

macOS

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com
git config --global url."https://github.com/".insteadOf 'git@github.com:'
mkdir -p "$HOME/dev"
cd "$HOME/dev"
git clone --recurse-submodules https://github.com/t42-hu/t42-motherrepo.git
cd t42-motherrepo

Debian

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /etc/apt/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list >/dev/null
sudo apt-get update
sudo apt-get install -y gh
gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com
git config --global url."https://github.com/".insteadOf 'git@github.com:'
mkdir -p "$HOME/dev"
cd "$HOME/dev"
git clone --recurse-submodules https://github.com/t42-hu/t42-motherrepo.git
cd t42-motherrepo

A további projektparancsokat mindig a t42-motherrepo könyvtárból futtasd. Új terminálban a cd "$HOME/dev/t42-motherrepo" paranccsal térj vissza. Ha egy fájl hiányzik, előbb ellenőrizd ezt a könyvtárat.

4. Készítsd elő a gyökérkonfigurációt

Ehhez az új, üres setup-útvonalhoz hozd létre a gyökérfájlt a sablonból:

cp .env.example .env
chmod 600 .env

Ne futtasd ezt a másolást működő konfiguráció fölé. Nyisd meg a .env fájlt egyszerű szövegszerkesztőben. Ez egy rejtett szövegfájl, nem shell-szkript. Ne fűzz hozzá .txt kiterjesztést, és ne futtasd source-szal.

A kötelező üres értékeket neked kell megadnod: bootstrap-adminisztrátori hitelesítő adatok 32–64 karakteres jelszóval, egyedi ECS_INSTANCE_ID, PostgreSQL-, S3- és SeaweedFS-hitelesítő adatok, Kafka-azonosító és jelszavak, belső proxy- és KeyStore-tokenek, Dragonfly- és viewer-jelszavak, Cloudflare-kezelőhitelesítő adatok, valamint az aktív szolgáltatói beállítások.

A setup kiszámolja a böngésző-URL-eket, a PostgreSQL-kapcsolati stringeket és az alapértelmezett proxy-útvonalakat. Megőrzi a megadott auth-, proxy- és FormGen-titkokat, vagy generálja a hiányzókat. Nem generálja a KAFKA_CLUSTER_ID-t, a szolgáltatói hitelesítő adatokat, az explicit Graph delta-kulcsot vagy a Google-grant és kliens-titok fájljait. Ezeket az alábbi lépésekben a setup előtt állítsd be. Állítsd be az ECS_MEMORY_GIB=44 értéket ennek az útmutatónak a teljes választásához. A teljes listát a környezeti táblázatokban találod.

A devbox példa példánynév. Cseréld le a saját kisbetűs nevedre. Adatok áthelyezésekor őrizd meg a meglévő azonosítókat és kulcsokat. Soha ne futtass külön másolatokat ugyanazzal a példányazonosítóval.

Hozd létre az új, üres Kafka-fürt azonosítóját

Csak olyan új fürthöz, amelynek nincs megőrzött broker-adata, generálj UUID-t a Kafka URL-biztos Base64-ábrázolásában:

python3 -c 'import base64, uuid; print(base64.urlsafe_b64encode(uuid.uuid4().bytes).decode("ascii").rstrip("="))'

Másold a kiírt 22 karakteres értéket a gyökér KAFKA_CLUSTER_ID mezőbe. Mind a három új broker ezt az értéket használja. A Python setupja a 2. lépésben már elkészült. Ez a 16 bájtos UUID-kódolást használja, amelyet a Kafka Uuid implementációja elfogad. A Kafka saját disztribúciója is ad bin/kafka-storage.sh random-uuid parancsot.

Megőrzött fürt esetén pontosan a megőrzött azonosítót használd. Ne generálj cserét, ne formázd a meglévő tárolót, és ne módosítsd az azonosítót tulajdonosi hiba törléséhez. Ha az azonosító nem ismert, állj meg, és állítsd helyre a helyes konfigurációt.

Válaszd ki az infrastruktúra-elhelyezést

A kezdő útvonal maradjon teljesen helyi:

ECS_DEPLOYMENT_MODE=fulllocal
ECS_REMOTE_SIMULATION=false

Alternatíva: előkészített valódi távoli infrastruktúra. Ez nem tartozik a kötelező kezdő sorrendhez:

ECS_DEPLOYMENT_MODE=partialRemote
ECS_REMOTE_SIMULATION=false

A hiányzó kiválasztók megtartják a teljes helyi működést. A partialRemote / true helyi szimuláció. Opcionális, valódi helyi értékeket használ, és nem takarít meg memóriát. A fulllocal / true érvénytelen.

A valódi távoli indítás előtt töltsd ki a távoli blokkot és a callback-szerződést. Mind a három Kafka-hirdetett endpointnak működnie kell. A natív Kafka nem HTTPS-URL. A hitelesített scanner- és extractor-átjárókhoz külön tokenek kellenek. A Collabora korlátozott callbacket kér a helyi BFF-re.

A setup kiválasztja a kapcsolatokat, előkészíti a helyi alkalmazásokat és a proxyt, és ellenőrzi az előfeltételeket. Nem biztosít és nem indít újra Coolify-erőforrásokat. Nem lép csendben helyi szolgáltatásokra. Kafka-offseteket, eseményeket vagy Qdrant-pontokat sem visz át. Lásd a részleges távoli deploymentet.

Őrizd meg a kulcsokat és a forrásválasztást

Ne generálj új delta-, postafiók-hozzáférési, e-mail- vagy szolgáltatókulcsot meglévő titkosított adatokhoz. Egy adatbázisjelszó-érték szerkesztése nem változtatja meg a meglévő adatbázisjelszót.

ECS_APPLICATION_SOURCE_ROOT=. ezt a checkoutot használja. Egy abszolút, átnézett pillanatkép rögzíthet production-alkalmazáskódot. Az útvonal gépspecifikus, és nem menti a pillanatképet. Meglévő production-rögzítést ne távolíts el egy egyeztetett kiadás nélkül.

5. Állítsd be a bejelentkezési és postafiók-szolgáltatókat

Microsoft

Az app-only backend-hozzáféréshez és a pontos jogosultságokhoz kövesd a Microsoft Graph beállítást. A külön bejelentkezési alkalmazáshoz kövesd az account-beállítást.

Gyökérbeállítás	Forrás
MICROSOFT_CONNECTOR_ENABLED	true Microsofthoz, explicit false csak Google esetén. A kihagyás alapértelmezetten engedélyez.
BFF_MICROSOFT_CLIENT_ID, BFF_MICROSOFT_CLIENT_SECRET, BFF_MICROSOFT_TENANT_ID	Bejelentkezési Entra-alkalmazás
BACKEND_CLIENT_ID, BACKEND_CLIENT_SECRET, BACKEND_TENANT_ID	Külön app-only Graph-alkalmazás adminisztrátori hozzájárulással
GRAPH_WEBHOOK_URL, GRAPH_LIFECYCLE_WEBHOOK_URL	A nyilvános bejövő útvonal támogatott értesítési és életciklus-útvonalai
GRAPH_WEBHOOK_CLIENT_STATE	Stabil, privát validációs titok
DELTA_LINK_ENCRYPTION_KEY	Új, 32 bájtos Base64-kulcs ehhez az üres setuphoz. Az egységes runtime a local-dev-v1 referenciát használja. A megőrzött adatokhoz az eredeti, kompatibilis kulcs és referenciaszerződés kell.

Regisztráld a pontos Account Web callbacket, például https://account.devbox.ecas.local:8443/api/auth/callback/microsoft. Meglévő deploymentnél tartsd meg a tényleges hosztot és portot, ne cseréld példára.

Csak új, üres setuphoz generáld a delta-kulcsot:

openssl rand -base64 32

Tartsd a kulcsot privátan. A jelenlegi gyökér Compose a kulcsot adja tovább, nem a DELTA_LINK_ENCRYPTION_KEY_REFERENCE mezőt. A futásidejű referencia local-dev-v1. A gyökér .env-ben egy tetszőleges referenciaérték-hozzárendelésnek nincs hatása. Más referenciával létrehozott megőrzött állapothoz ellenőrzött, kompatibilis folyamatkonfiguráció vagy explicit migráció kell. A runtime-inicializálás a certgen.sh segítségével készíti elő a Graph-tanúsítványfájlokat. A /runtime/graph/... alatti Compose-útvonalak konténerútvonalak, nem macOS- vagy Windows-útvonalak. Lásd a Graph-kriptográfiát.

Személyes Gmail

Ehhez az útvonalhoz a postafiók-klienshez, az API-hozzáféréshez és a privát fájlokhoz végezd el a Google Cloud beállítást. A nem kötelező alkalmazásbejelentkezési klienst és a Pub/Sub-részeket hagyd ki. Tartsd meg a GOOGLE_APP_LOGIN_ENABLED=false, GOOGLE_MAILBOX_OAUTH_ENABLED=true, GOOGLE_MAILBOX_SYNC_ENABLED=true és GOOGLE_MAILBOX_WATCH_ENABLED=false értékeket. Az alábbi három Google JSON-listát állítsd [] értékre. A Microsoft engedélyezve marad.

A workerek engedélyezése előtt végezd el a Google-előfeltételeket. A leírás kitér az API-engedélyezésre, a hozzájárulásra, a külön bejelentkezési és postafiók-Web-kliensekre, a titokfájlokra és a Pub/Sub-ra. A személyes Gmail nem igényel Workspace-adminisztrációt vagy domain-szintű delegálást.

Gyökérbeállítás	Szükséges érték
GOOGLE_APP_LOGIN_ENABLED	true csak akkor, ha a külön alkalmazásbejelentkezési kliens és a nyilvános callback készen áll
BFF_GOOGLE_LOGIN_CLIENT_ID, BFF_GOOGLE_LOGIN_CLIENT_SECRET	Teljes alkalmazásbejelentkezési kliens-pár
GOOGLE_APP_LOGIN_CALLBACK_URL, GOOGLE_APP_LOGIN_PROXY_SECRET	Pontos nyilvános HTTPS /api/auth/callback/google és külön belső titok
GOOGLE_MAILBOX_OAUTH_ENABLED, GOOGLE_MAILBOX_SYNC_ENABLED	Mindkettő true a postafiók-csatlakoztatáshoz és a háttérszinkronizáláshoz
ECAS_DEPLOYMENT_TENANT_ID	Stabil deployment UUID, nem e-mail, domain vagy név
GOOGLE_MAILBOX_CLIENT_ID	Dedikált postafiók-Web-kliensazonosító
GOOGLE_MAILBOX_CALLBACK_URL	Regisztrált nyilvános HTTPS /v1/oauth/callback
GOOGLE_MAILBOX_BFF_COMPLETION_URL	BFF /api/google-mailbox/complete, nem Google-átirányítási regisztráció
GOOGLE_MAILBOX_SECRET_DIRECTORY	./.docker-state/google
GOOGLE_MAILBOX_GRANT_KEY_REFERENCE	Stabil referencia, például google-mailbox-grant-v1
GOOGLE_MAILBOX_WATCH_ENABLED	false, amíg a hitelesített Pub/Sub-útvonal nincs kész
GOOGLE_PUBSUB_CONFIG_JSON	[] watch nélkül, teljes útvonal-tömb watch-csal
GOOGLE_WORKSPACE_CREDENTIALS_JSON, GOOGLE_DIRECTORY_POLICIES_JSON	[] személyes Gmailhez

A privát Google-könyvtárban az oauth-client-secret a nyers postafiók-kliens-titok szövegét tartalmazza, nem exportált OAuth JSON-t. A mailbox-grant.key 32 véletlen bájt Base64-kódolását tartalmazza. Megőrzött grantnél állítsd vissza mindkét eredeti fájlt. Ezek különülnek el a személyes e-mail-kulcs mentésétől. A könyvtár jogosultsága 700, a fájlé 600.

Ha a felhasználók Microsofttal jelentkeznek be, és a Gmailt külön csatlakoztatják, a Google-alkalmazásbejelentkezés kikapcsolva is maradhat. A bejelentkezés önmagában nem aktiválja a postafiók-szinkronizálást.

A Gmail-push egyszeri Cloud-témakör-, feliratkozás- és IAM-előkészítést igényel. A MailGen ezután ehhez a témakörhöz hoz létre és újít meg postafiók-watcheket. A Cloud-feliratkozás és a postafiók-watch külön erőforrások. A Workspace által kezelt fiókokhoz ezen felül jóváhagyott domain-szintű delegálás és explicit regisztráció kell. Lásd a Workspace-beállítást.

Cloudflare bejövő-útvonal előfeltétel

Indítás előtt hozz létre kezelő API-tokent a kiválasztott Cloudflare-fiókhoz és DNS-zónához. Hatókörét állítsd be account Cloudflare Tunnel Write és zone DNS Edit/Read plus Zone Read értékre. Mentsd CLOUDFLARE_TOKEN néven. A CLOUDFLARE_ACCOUNT_ID és a CLOUDFLARE_ZONE_ID mezőbe a kiválasztott 32 hexadecimális karakteres azonosítókat írd.

Minden engedélyezett Microsoft-webhook- és Google-callback/push-host ehhez a zónához kell tartozzon. Olyan hosztneveket használj, amelyeket a Cloudflare edge-tanúsítványa lefed. Mélyebb aldomainekhez további lefedés kellhet. A szolgáltatói callback-útvonalaknak pontosan egyezniük kell a beállított bejövő útvonallal.

Teljes setup/indítás közben a tunnel-egyeztetés létrehozza vagy újrahasználja a távolról kezelt ecs-INSTANCE tunnelt és a saját DNS-rekordjait. A meglévő tunnel újrahasználatához egyező .docker-state/tunnel/ownership.json kell. Egyező tunnelnév vagy visszaállított .env önmagában nem elég. Idegen DNS-célpontot a rendszer a módosítás előtt elutasít.

Megőrzött deploymentnél a konfigurációval, kulcsokkal és adatokkal együtt a tulajdonjog-metaadatokat is mentsd és állítsd vissza. Ha a metaadat elveszett, állítsd helyre a mentésből, vagy az üzemeltető egyértelműen oldja meg a régi tunnelt. Soha ne töröld az idegen DNS-t, és ne bővítsd a tokenjogosultságot az elutasítás megkerülésére. A helyi connector-token privát marad, a kezelőtoken pedig nem kerül az alkalmazáskonténerekbe. A normál leállítás és reset megőrzi a tunnel tulajdonjogát, és nem töröl felhőerőforrást.

6. Futtasd az első beállítást

Mielőtt hideg bootstrapet végzel, ellenőrizd a meglévő terhelést:

uptime
docker ps
tmux list-sessions
bash memmonitor.sh

Linuxon/WSL-en használd a free -h parancsot is. macOS-en nézd meg a Docker Desktop erőforrásait és az Activity Monitort. Válassz egy teljes, aktív stacket. A nem kapcsolódó konténereket hagyd érintetlenül. A setup leáll, ha másik MailGen-példány fut.

A konfiguráció és a szolgáltatói előfeltételek teljesítése után:

bash 0daysetup.sh
bash devstack.sh status

A setup előkészíti a gazdagép-eszközöket és a submodule-okat, kitölti a hiányzó számított beállításokat és generált titkokat, ellenőrzi a tulajdonjogot és a memóriát, előkészíti a proxy- és kliensútvonalakat, és elindítja a lefordított production-szolgáltatásokat. Kiválasztja a FormGen/docs-mcp és a szolgáltatófüggő profilokat. A meglévő adatokat megőrzi.

Várd meg a Setup complete / Stack ready üzenetet. Ha a setup leáll, javítsd a jelentett előfeltételt, és futtasd újra. Ne reseteld a köteteket. Ehhez az útvonalhoz nincs szükség kézi háttérindításra vagy kötelező certgen.sh hívásra.

7. Bízz meg a HTTPS-ben és jelentkezz be

Futtasd a bash configureNpmProxyHosts.sh --show parancsot a kiválasztott nyilvános tanúsítvány megkereséséhez. Kövesd a kliens-tanúsítvány utasításait. Csak a nyilvános .crt fájlt importáld. Soha ne másolj privát kulcsot a böngészőgépre.

A WSL-megbízhatóság nem állítja be automatikusan a Windowst. Más böngészőgépeknek saját névfeloldás és megbízhatóság kell. Nyisd meg a teljes Account-URL-t, a beállított helyen a :8443 porttal együtt. Egy szabványos Force SSL átirányítás elveszítheti ezt a portot. Ne kapcsold ki a TLS-ellenőrzést.

Végezd el az első bejelentkezést. Az alkalmazásazonosító, a postafiók-azonosító és a jogosultsági szereplő külön dolgok. Egy címtárbejegyzés vagy sikeres bejelentkezés nem bizonyítja a postafiók-onboardingot.

8. Napi indítás, leállítás és újraindítás

Cél	Parancs
Leállás után a változatlan, előkészített konténerek folytatása	bash quickStarter.sh
Ez a példány leállítása az adatok megőrzésével	bash stopDevServer.sh
Konfiguráció alkalmazása production-artifactok újraépítése nélkül	bash restartDevServers.sh
Lefordított production-végrehajtás explicit kiválasztása	bash restartDevServers.sh --prod
Új teljes fejlesztői indítás kiválasztása	bash startDevServers.sh
Állapot és naplók vizsgálata	bash devstack.sh status / bash devstack.sh logs bff

A gyors indítás nem épít újra, nem generál újra Prismát, nem hoz létre újra hiányzó konténereket, és nem tölt be újra módosított .env-t. A normál újraindítás a mentett szolgáltatásmódokat folytatja, production-artifactok újraépítése nélkül. Sem a normál, sem a --prod újraindítás nem futtat sémainicializálást. A módosított production-kódot a bash restartDevServers.sh --prod paranccsal publikáld, az esetleg külön szükséges előkészítés után. Egy szolgáltatásra a célzott hotfix-publikációt használd. Lásd a végrehajtási mód referenciát.

Infrastruktúra-mód váltása meglévő adatokkal

Őrizd meg a konfigurációt, az adatokat és a kulcsokat, és egyezz meg az állásidőben. Állítsd le az eredeti példányt az eredeti beállításokkal. Az üzemeltető az író folyamatok leállított állapotában vigye át és ellenőrizze a Kafka- és Qdrant-állapotot. Ezután módosítsd a kiválasztókat és a távoli bemeneteket, validáld őket, és használj szokásos újraindítást.

Helyi módba való visszatérés előtt ellenőrizd az újabb távoli állapotot és a szükséges visszairányú másolást. A régi helyi kötetek elavultak lehetnek. A kiválasztó módosítása nem adatmigráció és nem folyamatos replikáció. Lásd a teljes módosítási eljárást.

A távoli leállítás nem kezeli a Coolify-erőforrásokat. A távoli mód elutasítja a resetet és a takarítást, még szimulációban is. A projekt reset csak a felsorolt saját adatköteteket törli. A gazdagép-konfiguráció, a kulcsok és a többi névvel ellátott kötet megmarad. A puszta down -v más, szélesebb törlőparancs. Ne helyettesítsd vele. Rutinszerű hibakereséshez soha ne használd, és ne kerüld meg a távoli védelmet az elhelyezés módosításával.

9. Vizsgáld a hibákat

A Ctrl+C kilép a naplónézetből. A devServerAttach.sh használatakor a tényleges szolgáltatást is leállíthatja. A Ctrl+P, majd Ctrl+Q lecsatolja a terminált. Ne indíts másolatfolyamatot.

Tünet	Következő lépés
Docker-socket jogosultsági hiba	Debian-csoportváltozás után jelentkezz ki és be. Ne hozz létre másik stack-azonosítót sudo alatt.
Hiányzó gyökérkonfiguráció	Pótold a megnevezett gyökérmezőt. A jelentésekből zárd ki a titkos értékeket.
Hiányos Pub/Sub-útvonal	Ellenőrizd a teljes JSON-t és a Cloud OIDC-beállításokat. Tartsd a watch értéket false-on, amíg kész nem lesz. A lekérdezés bekapcsolva maradhat.
Google SERVICE_DISABLED	Engedélyezd az API-t a postafiók-kliens projektjében, és indítsd újra a hozzájárulást. Ne játszd le a régi OAuth-állapotot.
EMAIL_KEY_NOT_PROVISIONED	Végezd el a postafiók-tulajdonos kulcsbeállítását és a mentés megerősítését. Tartsd meg a titkosítási kaput.
502 / 503	Vizsgáld az érintett szolgáltatás állapotát, naplóit és a proxy-útvonalat.
Visszatér a rossz hosztra vagy 443-ra	Egyeztesd a tényleges origint és callbacket, és őrizd meg a HTTPS-portot.
Memória- vagy build-hiba	Ellenőrizd a kiválasztott 40/44 GiB-os keretet, a gép- és Docker-tartalékot, valamint a többi stacket. Őrizd meg a szolgáltatási alsó határokat és az adatokat.
Gmail-üzenet hiányzik	Ellenőrizd a szinkronizálás és az előzménylekérdezés készenlétét, majd a watch- és Pub/Sub-kézbesítést. A push csak trigger, nem maga a projekció.
A gyors indítás szerint nincs előkészítve vagy elavult	Használj szokásos újraindítást. Ne módosítsd az ujjlenyomatokat, és ne töröld a köteteket.
Távoli identitás-, endpoint- vagy hitelesítési hiba	Ellenőrizd az összes broker metaadat-endpointját és a szerepkör-hitelesítő adatokat. Nincs helyi visszalépés.
Üres Office-előnézet vagy socket-hiba	Vizsgáld a BFF és a Collabora állapotát, valamint a korlátozott WOPI-fájlolvasásokat. Tartsd meg a callback-korlátozásokat.
Tudásbázis-vizsgálat, kinyerés vagy vektorhiba	Vizsgáld a fájl állapotát és az érintett szolgáltatást. Normálisan állítsd helyre, ellenőrizetlen feltöltések és automatikus Qdrant-újraépítés nélkül.

10. Ellenőrizd az alkalmazást a setup után

Használj saját eldobható tartalmat és jóváhagyott címzetteket. Ellenőrizd a postafiókváltást, a Beérkezett üzenetek, Sent (elküldött üzenetek) és Piszkozatok mappákat, a törzsbetöltést, a piszkozat mentését és újranyitását, valamint a megengedett küldést és választ. Ellenőrizd az olvasottsági állapotot, a támogatott archiválást, a kukát és a visszaállítást, a címkéket és mappákat, valamint a keresést az egyes szolgáltatók dokumentált korlátain belül.

Ha a fájl integritása számít, hasonlítsd össze a letöltött melléklet bájtjait. Ellenőrizd, hogy a szolgáltató által létrehozott levél helyben megérkezik. Az elfogadottként vagy awaiting_confirmation állapotban jelölt módosítás nincs megerősítve. Várd meg a megerősítését és egy független kanonikus visszaolvasást. A beállítás igazolásához ne törölj meglévő leveleket.

Ezek az ellenőrzések a tényleges gépre és konfigurációra vonatkoznak. Önmagában a konténer-állapot nem elég.

A konfiguráció megőrzése a beállítás után

Sikeres beállítás után használd a titkos adatok mentését. A Google-hitelesítő adatok és grant-fájlok, valamint a személyes és szolgáltatókulcsok mentését külön végezd. A környezeti archívum ezeket nem tartalmazza automatikusan.

Az átnézett forrásgyökér útvonala gépspecifikus. Deployment áthelyezésekor őrizd meg a kiválasztott kódrevíziót. Az új setupok rendszerint a . útvonalat használják. A meglévő production-forrásrögzítéseket csak egyeztetett kiadással változtasd.

Hivatalos setup-hivatkozások: Docker macOS, Docker Debian, GitHub CLI bejelentkezés, Git credential helper és Git-konfiguráció.