Proměnné prostředí

Lokální vývoj nepotřebuje žádnou konfiguraci — SQLite a lokální souborové úložiště fungují rovnou. Produkce potřebuje URL webu a (volitelně) přihlašovací údaje Cloudflare R2. Viz .env.example pro kompletní seznam.

Lokální vývoj

Zkopírujte .env.example do .env. Pro správné kanonické/OG/sitemap URL záleží jen na SITE_URL; databáze a nahrané soubory defaultují na ./data.

SITE_URL=http://localhost:4321

# Volitelná analytika
PUBLIC_GA_MEASUREMENT_ID=
PUBLIC_GTM_ID=

Produkce

Tyto nastavte v nastavení Environment vaší Dokploy služby.

Proměnná	Povinná	Účel
`SITE_URL`	doporučeno	Veřejný produkční origin (passkey RP origin)
`DATABASE_URL`	ne	Cesta k SQLite; defaultuje na `file:./data/kafecms.db`
`S3_ENDPOINT`	ano	R2 S3 endpoint `https://<accountid>.r2.cloudflarestorage.com`
`S3_BUCKET`	ano	Název R2 bucketu
`S3_ACCESS_KEY_ID`	ano	R2 access key (secret)
`S3_SECRET_ACCESS_KEY`	ano	R2 secret key (secret)
`S3_REGION`	ne	Defaultuje na `auto` (R2)
`S3_PUBLIC_URL`	ne	V této šabloně inertní — média se servírují přes proxy routu Kafe-CMS (viz níže). Klidně nechte prázdné
`RESEND_API_KEY`	pro e-mail	Resend API klíč; jeho přítomnost registruje e-mailového providera (secret)
`EMAIL_FROM`	pro e-mail	Ověřený odesílatel, např. `My Site <noreply@example.com>`

Hodnoty S3_* a RESEND_API_KEY ukládejte jako šifrované secrety, nikdy do repozitáře.

Úložiště médií (Cloudflare R2)

V produkci web ukládá média do R2 přes S3-kompatibilní API. Balíčky @aws-sdk/client-s3 / @aws-sdk/s3-request-presigner jsou přibalené a úložišťový adaptér resolvuje všechny hodnoty S3_* z prostředí při startu kontejneru (astro.config.ts volá s3() bez argumentů). Takže výše uvedené proměnné S3_* jsou v produkci vyžadované za běhu — bez nich uploady selžou s MISSING_S3_CONFIG. Lokální vývoj používá souborový systém (./data/uploads), pokud není v shellu nastavený S3_BUCKET.

Jak uploady fungují

Uploady používají presigned URL: administrace požádá server o podepsanou URL, poté prohlížeč PUTne soubor přímo do R2. Aby tento cross-origin PUT uspěl, musí být na místě dvě věci:

CORS R2 bucketu — povolte origin vašeho webu. Příklad politiky:

[
  {
    "AllowedOrigins": ["https://your-domain.example"],
    "AllowedMethods": ["GET", "PUT", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

CSP whitelist — Kafe-CMS nastavuje striktní CSP connect-src 'self' na routách /kafecms v produkci, což by jinak zablokovalo prohlížeči připojení k R2. Tato šablona přináší src/middleware/kafecms-csp.ts (zaregistrovaný před integrací Kafe-CMS v astro.config.ts), který připojí origin S3_ENDPOINT k connect-src, takže upload může proběhnout. Není potřeba žádná konfigurace nad rámec nastavení S3_ENDPOINT.

Jak se média servírují (a proč URL vypadají jako `/kafecms/...`)

Kafe-CMS servíruje všechna média přes vlastní same-origin proxy routu (/kafecms/api/media/file/<key>), která streamuje objekt z R2. Media Library v administraci a vykreslené stránky vždy zobrazují tuto proxy cestu — to je doručovací URL, nikoli úložná lokace. Soubor je v R2 bez ohledu na to (ověřte v Cloudflare R2 dashboardu → váš bucket → Objects).

Toto je záměrné a preferované: bucket zůstává privátní, média se servírují přes vaši vlastní doménu za Cloudflare a každý soubor dostane sandbox CSP + bezpečný Content-Disposition (ochrana proti stored-XSS). Kvůli tomu S3_PUBLIC_URL nemá vliv na to, co vidíte, a lze ho nechat prázdné. R2 bucket nepotřebuje zapnutý veřejný přístup, aby doručování fungovalo; veřejnou r2.dev URL můžete vypnout.

Poznámka: přepnutí úložišťových backendů nemigruje soubory už nahrané do předchozího backendu — dřívější assety znovu nahrajte.

E-mail (Resend)

Kafe-CMS potřebuje e-mailového providera pro odesílání magic-link přihlášení, pozvánek do týmu, obnovy účtu a notifikací. Tento starter přináší malého HTTP-based Resend providera (src/kafecms/resend-email.ts).

V produkci nastavte RESEND_API_KEY a EMAIL_FROM. Když je klíč přítomný, provider je zaregistrovaný, a protože je jediným e-mailovým providerem, Kafe-CMS ho vybere automaticky — žádná konfigurace v admin dashboardu není potřeba. Vytvořte klíč a ověřte svou odesílající doménu na resend.com. Nechte RESEND_API_KEY prázdné, aby se přešlo zpět na pozvánky s kopírováním odkazu.

První účet vlastníka se stále vytváří pomocí passkey přes HTTPS. E-mail je potřeba pro zvaní dalších uživatelů a pro magic-link přihlášení poté.

URL webu a odchozí odkazy

Existují dvě samostatné představy „URL webu“:

SITE_URL (env) — používá se pro kanonické/OG/sitemap URL a, což je důležité, jako passkey relying-party origin. Nastavte ho na svůj plný veřejný origin, např. https://your-domain.example (schéma vyžadováno, žádné koncové lomítko). Za reverzní proxy toto musí být nastavené, jinak ověření passkey selže.
kafecms:site_url (databáze) — zapsáno jednou během setup wizardu z toho originu, který prohlížeč použil, a používá se ke stavbě odchozích e-mailových odkazů (magic-link přihlášení, pozvánky, obnova). Env SITE_URL ho nepřepisuje.

Pokud jste setup dokončili na dočasné doméně (například host *.sslip.io), e-maily budou odkazovat tam. Uloženou hodnotu opravte na kanonické doméně pomocí:

# lokálně
pnpm set-site-url https://your-domain.example

# uvnitř kontejneru (Dokploy terminál)
cd /app && pnpm set-site-url https://your-domain.example

Nová hodnota se čte při dalším odeslání, takže není potřeba restart. Abyste tomuto opakování předešli, odeberte z aplikace jakoukoli auto-generovanou *.sslip.io doménu a k administraci vždy přistupujte přes svou kanonickou doménu.

Validace secretů

Skript validate:secrets proskenuje repozitář na omylem commitnuté secrety:

pnpm run validate:secrets

Běží během CI a shodí build, pokud je detekován pravděpodobný secret.