websitedev/docs/mozd_it_weboldal_kovetelmeny_dokploy_deploy_specifikacio_mvp.md

mozdIT Bt. — Weboldal követelmény + Dokploy deploy specifikáció (MVP)

0) Rövid összefoglaló

Cél: minimális, de komplett, mobil‑első, gyors és biztonságos bemutatkozó weboldal a mozdIT Bt.-nek, kiemelt Webmail linkkel és rövid, egyedi bemutatkozással. A később készülő admin aloldal (szerver‑monitoring/menedzsment) helye előkészítve. Deployment és tesztelés: Dokploy környezetben.

---

1) MVP oldalak és funkciók

Oldalak

• Kezdőlap: rövid, egyedi bemutatkozó szöveg; CTA: Webmail link (külső URL); szolgáltatások rövid dobozai.
• Rólunk: rövid történet, működés óta, személyes ügyfélkezelés, megbízhatóság.
• Szolgáltatások: web hosting, email szolgáltatás, DNS adminisztráció (rövid leírás + kapcsolat CTA).
• Kapcsolat: űrlap (név, email, üzenet, GDPR checkbox); cég e‑mail, telefonszám (ha lesz), cégnév, székhely.
• Admin (előre jelzett aloldal): /<admin> route fenntartva; tartalom később.

Funkciók (MVP)

• Reszponzív navigáció (hamburger mobilon, sticky header desktopon).
• Űrlapvalidáció (frontend: required + e‑mail forma; backend: spam‑védett endpoint).
• SEO alapok (title/description per oldal, OG, sitemap, robots).
• Analytics: Plausible (cookieless) vagy GA4 (cookie‑consenttel).

---

2) Nem‑funkcionális követelmények

• Reszponzivitás: mobile‑first; töréspontok: 360 / 640 / 768 / 1024 / 1280+ px.
• Teljesítmény: Lighthouse (mobil/desktop) ≥ 90; képek WebP/AVIF; lazy‑load; kritikus CSS minimalizálás.
• A11y: WCAG 2.1 AA (fókusz, ARIA, kontraszt ≥ 4.5:1, logikus heading).
• Biztonság: HTTPS, alap CSP, XSS/CSRF védelem, input szűrés a backend felé.
• Megfigyelhetőség: Sentry (client) + alap logok; uptime healthcheck.

---

3) Technológiai stack

• Frontend: Next.js (React + TypeScript) — SSG/SSR vegyes; App Router.
• UI: Tailwind CSS + egyszerű saját komponensek (később: shadcn/ui opcionális).
• Űrlapok: React Hook Form + Zod.
• State: minimális local state + SWR (ha kell fetch).
• Teszt: Jest + Testing Library (unit), Playwright (E2E — smoke a fő flow‑kra).
• CMS (opcionális később): Strapi/Sanity; MVP‑ben statikus tartalom JSON/MDX.

Projekt‑struktúra (rövid):

/src
  /app (Next.js routes)
  /components
  /styles
  /lib
  /tests (unit + e2e cfg)
/public

---

4) Tartalom (MVP) — copy irány

• Hero cím (Kezdőlap): „Megbízható web‑ és email‑szolgáltatás személyre szabott támogatással.”
• Alcím: „Kis ügyfélkör, nagy figyelem: stabil tárhely, üzembiztos levelezés és DNS adminisztráció — gyors reakcióval.”
• USP bullet‑ek: személyes ügyfélkezelés; gyors reagálás; stabil háttér; rugalmas támogatás.
• Webmail gomb: „Ugrás a Webmailre”.
• Rólunk rövid: mióta működtök; miért a kicsi ügyfélkör; megbízhatóság/folyamatos támogatás.
• Szolgáltatás dobozok: Web Hosting / Email / DNS Admin (1–2 mondat/elem, Kapcsolat CTA).

(Megjegyzés: a végleges szöveg a review során finomhangolható.)

---

5) Dokploy környezet — architektúra és folyamat

5.1 Környezetek

• Staging: staging.mozdit.hu (pl. alap auth / IP‑korlátozás, ha kell)
• Production: mozdit.hu (www → apex redirect vagy fordítva)

5.2 Alap komponensek

• Reverse proxy/ingress: Dokploy beépített (Traefik/Nginx környezet — a dokploy stack szerint).
• App konténer: Next.js app (Node 20) — SSG build + Node futtatás (vagy statikus export + Nginx).
• Opció: CDN (Cloudflare) a statikus assetekhez.

5.3 Environment változók (példa)

• NEXT_PUBLIC_WEBMAIL_URL=https://webmail.mozdit.hu
• COMPANY_NAME=mozdIT Bt.
• SITE_URL=https://mozdit.hu
• ANALYTICS_PROVIDER=plausible|ga4
• PLAUSIBLE_DOMAIN=mozdit.hu (ha Plausible)
• GA4_ID=G-XXXXXXX (ha GA4)
• CONTACT_API_URL=https://api.mozdit.hu/contact (ha külön backend)

5.4 Healthcheck & readiness

• HTTP GET /api/health → {status:"ok"}
• Staging/prod deploy csak zöld health esetén; rollback automatikus szabály (utolsó zöld image).

---

6) Docker & build

6.1 Next.js multi‑stage Dockerfile (Node 20)

# 1) Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
RUN npm ci --prefer-offline --no-audit --legacy-peer-deps || npm ci
COPY . .
RUN npm run build

# 2) Run stage (Node server)
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./package.json
RUN npm ci --omit=dev --prefer-offline --no-audit || true
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=5 CMD wget -qO- http://localhost:3000/api/health || exit 1
CMD ["npm","start"]

Megjegyzés: Ha statikus export (SSG only) elegendő, választható Nginx runtime is.

6.2 Dokploy app (magas szint)

• Repository link + branch per environment (main → prod, develop → staging) vagy tag‑alapú deploy.
• Build & deploy: Dockerfile alapján; port 3000; domain mapping staging/prod; env‑ek UI‑ból/secret store‑ból.
• Zero‑downtime: rolling frissítés (legalább 2 replika prod‑on, ha erőforrás engedi).

---

7) CI/CD (példa: GitHub Actions)

Workflow: lint → unit → build → e2e (smoke, staging) → Dokploy deploy → Lighthouse check (staging) → prod release

.github/workflows/ci.yml (részlet):

name: CI
on:
  push:
    branches: ["main", "develop"]
jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run lint && npm run test -- --ci
      - run: npm run build
  docker:
    needs: build-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build & push image
        uses: docker/build-push-action@v5
        with:
          push: true
          context: .
          tags: registry.example.com/mozdit/site:${{ github.sha }}
  deploy-staging:
    needs: docker
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Dokploy staging deploy
        run: |
          curl -X POST "$DOKPLOY_STAGING_HOOK" -H "Authorization: Bearer $DOKPLOY_TOKEN" \
               -d '{"image":"registry.example.com/mozdit/site:${{ github.sha }}"}'
    environment: staging
  lighthouse:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - name: Lighthouse CI
        run: npx @lhci/cli autorun --collect.url=https://staging.mozdit.hu
  deploy-prod:
    if: github.ref == 'refs/heads/main'
    needs: lighthouse
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Dokploy prod deploy
        run: |
          curl -X POST "$DOKPLOY_PROD_HOOK" -H "Authorization: Bearer $DOKPLOY_TOKEN" \
               -d '{"image":"registry.example.com/mozdit/site:${{ github.sha }}"}'
    environment: production

Megjegyzés: a Dokploy‑oldali webhook/API URL és token a platform beállításától függ; ha Git integrációt használtok, a "Trigger" lépés helyett auto‑deploy szabály is beállítható.

---

8) Tesztelés a Dokploy stagingen

• Smoke E2E (Playwright): 3 alap flow → kezdőlap betölt, Webmail link működik, Kapcsolat űrlap hibakezelés OK.
• Vizsgálatok: Lighthouse (mobil & desktop), A11y ellenőrző (axe), 404/500 oldal viselkedés.
• Megfigyelés: Sentry DSN kapcsolva; health endpoint figyelése.

---

9) Biztonság & adatvédelem

• HTTPS (Let’s Encrypt / Dokploy integráció), HSTS.
• CSP baseline (script‑src 'self' + szükséges 3rd party); Referrer‑Policy, X‑Frame‑Options (SAMEORIGIN), X‑Content‑Type‑Options.
• GDPR: cookie banner ha GA4; Plausible esetén banner elhagyható.
• Kapcsolat űrlap: captcha/light rate‑limit, backend input validáció, e‑mail küldés queue‑val (ha szükséges).

---

10) Rollback, backup, verziózás

• Release tag (semver) + image tag; Dokploy‑ban korábbi image visszagörgetés.
• Konfig backup: env‑ek és Dokploy app export; infra‑as‑code (Dockerfile, workflow‑k) GIT‑ben.

---

11) Elfogadási kritériumok (MVP)

• Kezdőlap, Rólunk, Szolgáltatások, Kapcsolat elérhető és reszponzív.
• Webmail link jól működik (új lapon, nofollow opcionális).
• Lighthouse ≥ 90 minden fő mérőszámon stagingen.
• Űrlap hibák/fókuszállapotok a11y‑konformak.
• CI pipeline zöld, staging deploy automatikus; prod deploy csak zöld staging után.

---

12) Kezdő feladatlista (ticket sablonok)

1. Repo & Next.js bootstrap — Acceptance: app indul dev módban; TS, ESLint, Prettier beállítva.
2. Tailwind + alap layout — Acceptance: reszponzív header/footer; tipográfia, színek.
3. Kezdőlap (Hero + USP + Webmail CTA) — Acceptance: 1s alatt festődik mobilon; link működik.
4. Rólunk oldal — Acceptance: heading‑hierarchia helyes; szövegek MDX‑ből tölthetők.
5. Szolgáltatások oldal — Acceptance: 3 doboz + CTA → Kapcsolat.
6. Kapcsolat űrlap + API stub — Acceptance: validáció, hibák; egyszerű spam‑védelem.
7. /api/health endpoint — Acceptance: {status:"ok"} JSON.
8. Dockerfile + Dokploy staging app — Acceptance: buildel, deployol, domain él.
9. CI (lint, unit) + Staging deploy trigger — Acceptance: PR‑re fut; stagingre pushol.
10. Playwright smoke E2E + Lighthouse CI — Acceptance: fut stagingen, riport mentve.
11. Prod app + domain + HTTPS — Acceptance: élő site; automatikus HTTPS; monitoring bekapcsolva.

---

13) Későbbi bővítések

• Blog/Újdonságok; többnyelvűség; admin aloldal funkciói; CDN cache; képgenerálás; CMS integráció.

---

Megjegyzés: A végleges Dokploy beállítások (webhook/API, auto‑deploy, replika szám, storage) a rendelkezésre álló szerver erőforrásoktól és a Dokploy verziójától függően finomhangolandók.