Байршуулалт¶

Платформыг Docker Compose + edge nginx-ээр байршуулна. Стек: PostgreSQL 16 (pgvector) + Redis 7 + Go API + Next.js BFF.

Хостын нарийн мэдээлэл энд байхгүй

Сервер хаяг, зам, credential зэрэг нь репо доторх deploy/HOST.md runbook-д амьдарна — энэ сайт нийтэд нээлттэй тул тэдгээрийг агуулахгүй.

Топологи¶

Интернэт ──► edge nginx (80/443, Let's Encrypt)
   │           conf.d/geregeapp.mn.conf   ← энэ репо эзэмшинэ
   ▼
gerege-app-web (Next.js BFF)
   │  BACKEND_URL
   ▼
дотоод compose сүлжээ (public портгүй): api ──► db + redis

Edge nginx нь тусдаа compose төсөл. Апп-ын web контейнер нь хуваалцсан docker сүлжээгээр түүнд холбогдоно.

Vhost-ийн эзэмшлийн загвар¶

Экосистемийн олон домэйн нэг дундын edge nginx-ээр үйлчлэгддэг. Түүний conf.d хавтас нь өөр репо-гийн ажлын хуулбараас mount хийгддэг ба тэр репо-гийн deploy нь git reset --hard ажиллуулдаг.

git reset --hard нь tracked файлыг л сэргээдэг — untracked файлыг хөнддөггүй. Тиймээс энэ репо өөрийн vhost-оо тэр хавтас руу бүртгэлгүй файлаар суулгаж, конфигоо бүрэн эзэмшинэ.

bash deploy/edge/install.sh    # зөвхөн vhost-ыг шинэчлэх (build-гүй)

Скрипт юу хийдэг вэ:

Edge контейнерийн /etc/nginx/conf.d mount-аас хостын замыг автоматаар олно.
Өмнөх хувилбарыг backup-лана.
Шинэ файлыг суулгана (эзэмшлийг хадгална, 0644).
nginx -t — унавал өмнөх хувилбарыг буцааж, reload хийхгүй.
nginx -s reload.

Env	Default
`EDGE_CONTAINER`	`gerege-nginx`
`EDGE_CONF_D`	Автоматаар (контейнерийн mount-аас)
`SKIP_EDGE`	`deploy.sh`-д `1` өгвөл алгасна

Env файлууд (gitignored)¶

Файл	Юу	Эзэмшил
`.env`	Compose interpolation (Postgres/Redis нууц, порт, origin)	хост дээр `root`, `0600`
`backend.env`	API-ийн тохиргоо (JWT, eID, SSO, OIDC…)	uid 65532, `0600`

backend.env-ийн эзэмшил

api ба migrate контейнер нь distroless nonroot (uid 65532) хэрэглэгчээр ажиллана. backend.env нь тэдэнд /app/.env болж mount хийгддэг тул root-ийн эзэмшилтэй 0600 файлыг уншиж чадахгүй — migrate шууд failed to load config file гэж унана.

sudo chown 65532:65532 <репо>/backend.env
sudo chmod 600 <репо>/backend.env

Секрет deployment хооронд хуваалцахгүй

Deployment бүр өөрийн JWT_SECRET, SSO_STATE_KEY, INTEGRATION_ENC_KEY, RP креденшлтэй байна. Бүгдийг хост дээр openssl rand-аар үүсгэ — git, CI, чатанд хэзээ ч гаргахгүй.

Deploy¶

cd <репо-гийн зам>
git fetch --prune origin && git reset --hard origin/main
bash deploy/deploy.sh          # build → up → healthy хүлээх → edge суулгах

deploy.sh-ийн шинж чанарууд:

No-op хамгаалалт — юу ч өөрчлөгдөөгүй бол огт хөдлөхгүй (.deployed-sha).
Migration тусдаа алхам — ингэснээр deploy бүрийн 502 арилсан.
db-г дахин build хийхгүй.

CI/CD¶

main руу push хийхэд .github/workflows/ci.yml ажиллана:

Job	Юу
Backend	`gofmt -l .` хоосон · `go vet` · `go test -race` · build
Frontend	`npm run lint` · `npm run test` · `npm run build`
Secrets	gitleaks
Deploy	Гуравуулаа давсны дараа SSH-ээр `git reset --hard <sha>` + `deploy/deploy.sh`

Шаардлагатай repo secrets: DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY, DEPLOY_PATH. CI-ийн SSH түлхүүр нь операторын хувийн түлхүүрээс тусдаа.

TLS¶

Let's Encrypt, webroot горим. Гэрчилгээ нь edge-ийн эзлэхүүнд; cron нь өдөрт хоёр удаа шинэчлэлт оролдож, амжилттай бол nginx reload хийнэ.

Vhost нь өөрийн listen 80 блоктой (ACME challenge + HTTPS redirect) — дундын default server-ээс хамаарахгүй тул гэрчилгээний шинэчлэлт бие даан ажиллана.

Оношилгоо¶

docker compose ps
docker compose logs api --tail 50
docker compose logs migrate --tail 20     # "migration [up] success"

docker exec gerege-nginx nginx -t          # конфиг зөв эсэх
curl -s -o /dev/null -w '%{http_code}\n' https://geregeapp.mn/

Шинж тэмдэг	Шалтгаан	Засвар
`444` / холболт тасрах	Vhost файл устсан (`git clean -fd`)	`bash deploy/edge/install.sh`
`502 Bad Gateway`	`web` контейнер унтарсан эсвэл edge сүлжээнд ороогүй	`docker compose up -d`; override файлыг шалга
`conflicting server name`	Дундын конфигт vhost давхардсан	Тэндээс хас — эзэмшигч нь энэ репо
nginx асахгүй	Гэрчилгээ байхгүй	Certbot-оор гэрчилгээ ав
migrate `failed to load config`	`backend.env`-ийн эзэмшил	`chown 65532:65532`

Хостын compose override¶

Апп-ын web контейнерийг edge сүлжээнд холбож container_name өгдөг docker-compose.override.yml нь хост дээр л амьдарна (untracked).

Репо-д tracked байвал хөгжүүлэгч бүрийн локал орчинд прод тохиргоо албадан хэрэгжинэ.
Ignore хийхгүй орхивол git clean -fd түүнийг устгаж, контейнер edge сүлжээнээс салж vhost 502 өгнө.

Алдагдвал сэргээх:

cp deploy/host-override.example.yml docker-compose.override.yml
docker compose up -d

Энэ баримтын сайт¶

Баримт нь тусдаа статик сайт бөгөөд docs.gerege.mn/app/ дор үйлчилнэ:

Интернэт ──► gerege-nginx (docs.gerege.mn vhost)
               ├─ /       ─► docs-gerege-web     (экосистемийн баримт)
               └─ /app/   ─► gerege-app-docs-web (ЭНЭ баримт)

bash docs-site/deploy/deploy.sh      # build → хуулах → контейнер шинэчлэх

Дэлгэрэнгүй runbook: репо доторх docs-site/deploy/README.md.