245 lines
9.8 KiB
Markdown
245 lines
9.8 KiB
Markdown
# Deployment — zmienne środowiskowe i produkcja
|
|
|
|
Jedno źródło prawdy o zmiennych środowiskowych (wszystkie, co znaczą, wymagane
|
|
czy nie) oraz jak wdrożyć projekt na produkcję spójnie. Env jest częścią
|
|
deploymentu — te same zmienne w dev (.env) i na produkcji (runtime hostingu).
|
|
|
|
Powiązane: [getting-started.md](./getting-started.md), [storage.md](./storage.md)
|
|
(R2), [email.md](./email.md) (Graph), [security.md](./security.md).
|
|
|
|
---
|
|
|
|
## 1. ZMIENNE ŚRODOWISKOWE — pełna lista
|
|
|
|
### Rdzeń (WYMAGANE — projekt bez nich nie wstanie)
|
|
|
|
```bash
|
|
# Baza danych (Mongo albo Postgres — zależnie od projektu)
|
|
DATABASE_URI=mongodb://... # albo postgres://... / file:./dev.db (dev)
|
|
|
|
# Sekret Payload (podpisywanie sesji/tokenów) — losowy, długi
|
|
PAYLOAD_SECRET=<losowy-ciąg-min-32-znaki>
|
|
|
|
# Publiczny URL serwisu (canonical, hreflang, OG, manifest)
|
|
NEXT_PUBLIC_SERVER_URL=https://klient.pl # dev: http://localhost:3000
|
|
```
|
|
|
|
### Email — Graph (OPCJONALNE, agencyjne, gdy transport = Graph)
|
|
|
|
```bash
|
|
GRAPH_TENANT_ID=<azure-tenant-id>
|
|
GRAPH_CLIENT_ID=<azure-app-client-id>
|
|
GRAPH_CLIENT_SECRET=<azure-app-secret>
|
|
GRAPH_SENDER=[email protected] # wspólna skrzynka
|
|
```
|
|
Bez nich transport Graph nie zadziała (fallback SMTP). Patrz email.md.
|
|
|
|
### Storage — R2 (OPCJONALNE, gdy media w R2)
|
|
|
|
```bash
|
|
R2_BUCKET=<nazwa-bucketa>
|
|
R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
|
|
R2_ACCESS_KEY_ID=<access-key>
|
|
R2_SECRET_ACCESS_KEY=<secret-key>
|
|
R2_PUBLIC_URL=https://media.klient.pl # custom domena (obrazy publiczne)
|
|
```
|
|
Brak → fallback na lokalny dysk. Patrz storage.md.
|
|
|
|
### Tabela — wszystkie zmienne
|
|
|
|
| Zmienna | Wymagana | Warstwa | Opis |
|
|
|---|---|---|---|
|
|
| `DATABASE_URI` | ✅ | infra | połączenie z bazą |
|
|
| `PAYLOAD_SECRET` | ✅ | infra | sekret Payload |
|
|
| `NEXT_PUBLIC_SERVER_URL` | ✅ | infra | publiczny URL (canonical, OG) |
|
|
| `GRAPH_TENANT_ID` | ⬜ | email | Azure tenant (Graph) |
|
|
| `GRAPH_CLIENT_ID` | ⬜ | email | Azure app id |
|
|
| `GRAPH_CLIENT_SECRET` | ⬜ | email | Azure secret |
|
|
| `GRAPH_SENDER` | ⬜ | email | skrzynka nadawcza |
|
|
| `R2_BUCKET` | ⬜ | storage | bucket R2 |
|
|
| `R2_ENDPOINT` | ⬜ | storage | endpoint S3 R2 |
|
|
| `R2_ACCESS_KEY_ID` | ⬜ | storage | klucz R2 |
|
|
| `R2_SECRET_ACCESS_KEY` | ⬜ | storage | sekret R2 |
|
|
| `R2_PUBLIC_URL` | ⬜ | storage | custom domena mediów |
|
|
|
|
**Zasada:** wszystkie sekrety to zmienne agencyjne/infrastrukturalne — w `.env`
|
|
(dev) i runtime hostingu (prod), NIGDY w repo. Dane per-projekt edytowalne przez
|
|
redaktora idą do PANELU, nie do env (patrz architektura-tresci.md).
|
|
|
|
### .env.example — zawsze w repo
|
|
|
|
Każdy projekt ma `.env.example` z listą zmiennych (bez wartości/sekretów) —
|
|
szablon dla następnej osoby. Commituj go; `.env` (z wartościami) NIGDY.
|
|
|
|
---
|
|
|
|
## 2. PRZED DEPLOYEM — checklist
|
|
|
|
- [ ] `pnpm build --webpack` przechodzi LOKALNIE (nie tylko dev)
|
|
- [ ] Wszystkie wymagane env ustawione na hostingu (runtime)
|
|
- [ ] `NEXT_PUBLIC_SERVER_URL` = produkcyjny URL (nie localhost)
|
|
- [ ] `PAYLOAD_SECRET` inny niż w dev (produkcyjny sekret)
|
|
- [ ] Baza produkcyjna (nie dev/SQLite)
|
|
- [ ] HSTS włączony (buildSecurityHeaders hsts: production)
|
|
- [ ] Media: R2 z custom domeną (jeśli używane) — obrazy publiczne
|
|
- [ ] Migracja mediów lokalne→R2 (jeśli przełączasz)
|
|
- [ ] Strony polityk + baner cookies (patrz wymagania-prawne.md)
|
|
|
|
---
|
|
|
|
## 3. BUDOWANIE NA PRODUKCJĘ
|
|
|
|
### Build script (Next 16 + Payload)
|
|
|
|
```json
|
|
// package.json — --webpack KONIECZNE (Turbopack konfliktuje z withPayload)
|
|
"build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" next build --webpack"
|
|
```
|
|
|
|
`--max-old-space-size` — Payload + Next bywają pamięciożerne przy buildzie;
|
|
3072 MB zapobiega OOM na mniejszych maszynach.
|
|
|
|
### Kolejność build → migracje → start
|
|
|
|
```bash
|
|
pnpm install --frozen-lockfile # dokładnie z lockfile (powtarzalny build)
|
|
pnpm generate:types # typy z kolekcji
|
|
pnpm build # --webpack
|
|
# migracje bazy (jeśli Postgres z migracjami):
|
|
pnpm payload migrate
|
|
pnpm start # produkcyjny serwer
|
|
```
|
|
|
|
---
|
|
|
|
## 3a. Pułapka: metadata w <body> zamiast <head> (htmlLimitedBots)
|
|
|
|
Next 16 streamuje metadata dynamicznych stron do `<body>` (przenosi do head
|
|
skryptem JS). Crawlery bez JS widzą canonical/hreflang/title/favicon poza head →
|
|
utrata SEO. **Każdy projekt** tego potrzebuje w next.config:
|
|
|
|
```ts
|
|
const nextConfig: NextConfig = {
|
|
htmlLimitedBots:
|
|
/Googlebot|Google-InspectionTool|Bingbot|Yandex|DuckDuckBot|Screaming Frog|AhrefsBot|SemrushBot/i,
|
|
// ...
|
|
}
|
|
```
|
|
|
|
Weryfikacja: `curl -A "Googlebot" URL | grep canonical` — musi być w `<head>`.
|
|
Szczegóły i objawy: seo.md (sekcja htmlLimitedBots).
|
|
|
|
## 3a2. ISR — cache stron (metadata w head + szybkość)
|
|
|
|
Dla stron contentowych (page.tsx) użyj ISR: `export const revalidate = 3600`.
|
|
Cache'uje całą stronę z gotowym `<head>` → metadata zawsze w head (nie body,
|
|
brak race condition streamingu), TTFB ~20ms, brak 503 (cold start).
|
|
|
|
```ts
|
|
// app/(frontend)/[locale]/[[...slug]]/page.tsx
|
|
export const revalidate = 3600 // 1h; albo krócej, albo on-demand
|
|
```
|
|
|
|
UWAGA: ISR i `force-dynamic` się WYKLUCZAJĄ. Strony → ISR (revalidate).
|
|
sitemap/robots → force-dynamic (bo generują przy żądaniu). Nie mieszaj na jednej
|
|
trasie. Treść z panelu: ISR = redaktor czeka do rewalidacji; rozważ on-demand
|
|
revalidation (hook afterChange → revalidatePath). Patrz seo.md, HOOKS.md.
|
|
|
|
## 3a3. SSG a dostęp do bazy przy buildzie (WAŻNE dla SEO)
|
|
|
|
`generateStaticParams` (z lib/content) prerenderuje strony jako SSG — head
|
|
synchroniczny, SEO 100/100. ALE żeby prerenderować, **build musi mieć dostęp do
|
|
bazy** (generateStaticParams czyta strony z bazy w czasie buildu).
|
|
|
|
- **Build MA dostęp do bazy** (baza w tej samej sieci Docker, dostępna w build
|
|
stage) → strony prerenderowane jako SSG (`●`), head synchroniczny → SEO OK ✓
|
|
- **Build NIE MA dostępu** (izolowany build stage) → generateStaticParams zwraca
|
|
`[]` (plugin łapie błąd, build nie pada), ale strony renderują się on-demand
|
|
(dynamicznie) → head może streamować do body → problem SEO wraca ✗
|
|
|
|
Plugin zabezpiecza build przed CRASHEM (try/catch → `[]`), ale to NIE zastępuje
|
|
dostępu do bazy. **Dla pełnego SSG/SEO zapewnij, że build kontenerowy widzi bazę.**
|
|
|
|
W Coolify/Docker: baza (Mongo/Postgres) powinna być dostępna podczas `pnpm build`,
|
|
nie tylko w runtime. Jeśli build jest w izolowanej sieci — rozważ:
|
|
- uruchom bazę w tej samej sieci Docker co build stage, albo
|
|
- build z DATABASE_URI wskazującym na dostępną bazę (nie wewnętrzny host niedostępny w buildzie).
|
|
|
|
Weryfikacja: po buildzie `pnpm build` pokazuje trasy jako `●` (SSG), nie `ƒ`
|
|
(Dynamic). Jeśli `ƒ` mimo generateStaticParams → build nie miał dostępu do bazy.
|
|
|
|
## 3b. Pułapka: prerender tras zależnych od bazy (KONIECZNE)
|
|
|
|
Next domyślnie **prerenderuje** trasy typu `sitemap.ts` w czasie `next build` —
|
|
traktuje je jako statyczne. Jeśli taka trasa czyta bazę (sitemap → Payload →
|
|
Mongo/Postgres), build **próbuje połączyć się z bazą**. A kontener budujący
|
|
(Coolify/Docker/Railway/CI) zwykle NIE ma dostępu do sieci bazy → połączenie
|
|
pada (`ENOTFOUND`, `MongooseServerSelectionError`) → **build się wywala**.
|
|
|
|
**Rozwiązanie — `force-dynamic` na trasach zależnych od bazy:**
|
|
```ts
|
|
// app/sitemap.ts
|
|
export { sitemap as default } from '@/lib/content'
|
|
export const dynamic = 'force-dynamic' // generuj w runtime, nie w buildzie
|
|
```
|
|
|
|
To mówi Next: nie prerenderuj w buildzie, generuj w runtime (gdy baza jest
|
|
dostępna). Dotyczy KAŻDEJ trasy czytającej bazę podczas renderowania:
|
|
- `app/sitemap.ts` → `force-dynamic`
|
|
- inne trasy/strony czytające bazę w prerenderze → rozważ `force-dynamic` albo
|
|
obsłuż błąd bazy (try/catch z fallbackiem)
|
|
|
|
Plugin dodatkowo zabezpiecza handler sitemap (łapie błąd bazy, zwraca pustą
|
|
mapę), więc build nie padnie nawet bez `force-dynamic` — ale to siatka
|
|
bezpieczeństwa, nie właściwe rozwiązanie. Zawsze dodawaj `force-dynamic`.
|
|
|
|
**Strona 404** (`not-found.tsx`) czytająca ustawienia z bazy — ten sam problem.
|
|
Opakuj `getCachedPayload()` w try/catch, żeby brak bazy w buildzie nie wywalił
|
|
prerenderu 404 (fallback na statyczne teksty).
|
|
|
|
**Weryfikacja lokalna** (symuluj brak bazy):
|
|
```bash
|
|
DATABASE_URI=mongodb://invalid-host:27017/test pnpm build
|
|
# build musi przejść (kod 0), mimo niedostępnej bazy
|
|
```
|
|
|
|
## 4. HOSTING (Coolify / Docker)
|
|
|
|
### Zmienne runtime, nie build
|
|
|
|
Zmienne środowiskowe ustaw w **runtime** hostingu (Coolify → Environment
|
|
Variables), nie zapiekaj w build. `NEXT_PUBLIC_*` są wyjątkiem — wchodzą w build
|
|
(bo publiczne, w bundlu klienta), więc muszą być dostępne PODCZAS buildu.
|
|
|
|
### Persystencja mediów
|
|
|
|
Jeśli media lokalne (nie R2) — potrzebują **wolumenu** (inaczej znikną przy
|
|
redeployu). Dlatego R2 jest zalecane na produkcji: media poza kontenerem,
|
|
przetrwają redeploy. Patrz storage.md.
|
|
|
|
### Health check
|
|
|
|
Payload wystawia panel pod `/admin` — health check może pingować stronę główną
|
|
albo `/admin`. Nie ustawiaj health check na endpoint wymagający bazy, jeśli
|
|
baza wstaje wolniej niż app.
|
|
|
|
---
|
|
|
|
## 5. PO DEPLOYU — weryfikacja
|
|
|
|
- [ ] Strona główna `/` przekierowuje na locale (`/pl`)
|
|
- [ ] Panel `/admin` działa, logowanie OK
|
|
- [ ] Formularz wysyła (test przez panel: Send test)
|
|
- [ ] Media się wyświetlają (jeśli R2 — custom domena działa, nie 403)
|
|
- [ ] Favicon w `<head>` (patrz seo.md — Google cache'uje wolno)
|
|
- [ ] HTTPS + nagłówki bezpieczeństwa (sprawdź np. securityheaders.com)
|
|
- [ ] Sitemap `/sitemap.xml` i `/robots.txt` odpowiadają
|
|
|
|
---
|
|
|
|
## DLACZEGO TO WAŻNE
|
|
|
|
- **Jedna lista env** — nikt nie zgaduje, czego brakuje
|
|
- **Powtarzalny deploy** — frozen-lockfile, ta sama kolejność, każdy projekt tak samo
|
|
- **Sekrety bezpieczne** — env/runtime, nigdy repo
|
|
- **Media przetrwają** — R2 albo wolumen, nie znikają przy redeployu |