create-nextblock 0.9.0 → 0.9.6

package/templates/nextblock-template/app/setup/layout.tsx

@@ -0,0 +1,13 @@
+// Minimal layout for the first-boot wizard. Deliberately does NO Supabase work so it
+// renders even on a completely unconfigured instance. (It is still nested inside the
+// root layout, which short-circuits its own data loading when unconfigured.)
+import type { ReactNode } from 'react';
+
+export const metadata = {
+  title: 'Set up NextBlock',
+  robots: { index: false, follow: false },
+};
+
+export default function SetupLayout({ children }: { children: ReactNode }) {
+  return <div className="mx-auto w-full max-w-3xl px-4 py-10 sm:py-16">{children}</div>;
+}

package/templates/nextblock-template/app/setup/page.tsx

@@ -0,0 +1,103 @@
+import { redirect } from 'next/navigation';
+import { createClient } from '@nextblock-cms/db/server';
+import {
+  detectChannel,
+  isLocalWritableEnv,
+  isSupabaseConfigured,
+  type DeployChannel,
+} from '../../lib/setup/env-status';
+import { getProvisioningStatus } from '../../lib/setup/provisioning';
+import SetupWizard, { type StoragePrefill } from './SetupWizard';
+
+// Always evaluate live: the wizard's whole job is to react to the current env state.
+export const dynamic = 'force-dynamic';
+
+function buildStoragePrefill(channel: DeployChannel, supabaseUrl: string): StoragePrefill {
+  if (channel === 'docker') {
+    // The Docker stack ships MinIO as the S3 backend; docker-setup wrote these already.
+    return {
+      kind: 'minio',
+      readOnly: true,
+      accountId: process.env.R2_ACCOUNT_ID ?? 'minio',
+      bucket: process.env.STORAGE_BUCKET ?? process.env.R2_BUCKET_NAME ?? 'media',
+      endpoint: process.env.R2_S3_ENDPOINT ?? 'http://minio:9000',
+      publicUrl: process.env.NEXT_PUBLIC_R2_PUBLIC_URL ?? 'http://localhost:9000',
+      baseUrl: process.env.NEXT_PUBLIC_R2_BASE_URL ?? '',
+      accessKeyId: '',
+      secretAccessKey: '',
+    };
+  }
+
+  if (channel === 'vercel') {
+    // One-click Vercel deploys connect to Supabase Storage's S3-compatible endpoint.
+    const base = supabaseUrl.replace(/\/$/, '');
+    return {
+      kind: 'supabase',
+      readOnly: false,
+      accountId: 'supabase',
+      bucket: 'media',
+      endpoint: base ? `${base}/storage/v1/s3` : '',
+      publicUrl: base ? `${base}/storage/v1/object/public` : '',
+      baseUrl: '',
+      accessKeyId: process.env.R2_ACCESS_KEY_ID ?? '',
+      secretAccessKey: '',
+    };
+  }
+
+  // Local: the user brings their own Cloudflare R2 (higher free-tier storage).
+  return {
+    kind: 'r2',
+    readOnly: false,
+    accountId: process.env.R2_ACCOUNT_ID ?? '',
+    bucket: process.env.R2_BUCKET_NAME ?? '',
+    endpoint: '',
+    publicUrl: process.env.NEXT_PUBLIC_R2_PUBLIC_URL ?? '',
+    baseUrl: process.env.NEXT_PUBLIC_R2_BASE_URL ?? '',
+    accessKeyId: process.env.R2_ACCESS_KEY_ID ?? '',
+    secretAccessKey: '',
+  };
+}
+
+export default async function SetupPage() {
+  const status = await getProvisioningStatus();
+
+  // Already finished — there's a first admin. Get out of the wizard.
+  if (status.hasAdmin) {
+    redirect('/cms/dashboard');
+  }
+
+  // A signed-in user never needs the wizard. This also closes the brief window right
+  // after completion where is_admin_created may still be read-stale: the just-created
+  // admin has a session, so send them straight to the CMS. (Only checked when
+  // configured — an unconfigured instance has no real auth.)
+  if (status.configured) {
+    const supabase = createClient();
+    const {
+      data: { user },
+    } = await supabase.auth.getUser();
+    if (user) {
+      redirect('/cms/dashboard');
+    }
+  }
+
+  const channel = detectChannel();
+  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL ?? '';
+
+  return (
+    <SetupWizard
+      channel={channel}
+      configured={isSupabaseConfigured()}
+      writable={isLocalWritableEnv()}
+      siteUrl={process.env.NEXT_PUBLIC_URL ?? ''}
+      storagePrefill={buildStoragePrefill(channel, supabaseUrl)}
+      smtpPrefill={{
+        host: process.env.SMTP_HOST ?? '',
+        port: process.env.SMTP_PORT ?? '465',
+        user: process.env.SMTP_USER ?? '',
+        fromEmail: process.env.SMTP_FROM_EMAIL ?? '',
+        fromName: process.env.SMTP_FROM_NAME ?? '',
+      }}
+      turnstilePrefill={{ siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY ?? '' }}
+    />
+  );
+}

package/templates/nextblock-template/components/AppShell.tsx

@@ -66,8 +66,20 @@ export function AppShell({
 }: AppShellProps) {
   const pathname = usePathname() || '';
   const isCmsRequest = pathname.startsWith('/cms');
+  const isSetupRequest = pathname === '/setup' || pathname.startsWith('/setup/');
   const branding = useMemo(() => ({ logo, siteTitle }), [logo, siteTitle]);
 
+  // The first-boot setup wizard renders on its own clean, chrome-free page: no header
+  // or footer, and crucially no EnvVarWarning — the whole point of /setup is to supply
+  // the very env vars that warning complains about.
+  if (isSetupRequest) {
+    return (
+      <AppBrandingContext.Provider value={branding}>
+        <main className="min-h-screen bg-background">{children}</main>
+      </AppBrandingContext.Provider>
+    );
+  }
+
   return (
     <AppBrandingContext.Provider value={branding}>
       {process.env.NEXT_PUBLIC_IS_SANDBOX === 'true' && !isCmsRequest && <SandboxBanner />}

package/templates/nextblock-template/components/PublicEnvBootstrap.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+// Makes the PUBLIC Supabase values available to the browser at runtime via a global,
+// set SYNCHRONOUSLY during render (before any descendant calls the browser createClient).
+//
+// Why: NEXT_PUBLIC_* are inlined into the client bundle at build time. On a fresh local
+// dev setup the dev server starts with no env, so the loaded bundle holds empties; the
+// /setup wizard then writes the env at runtime. Browser-side readers (the Supabase client,
+// env checks, and resolveMediaUrl's R2 base) read `process.env.NEXT_PUBLIC_* ||
+// window.__NEXTBLOCK_PUBLIC_ENV__`, so this fills the gap without a dev-server restart. In
+// production the inlined values win and these props just match them (a harmless no-op). All
+// of these (Supabase url + anon key, R2 public base) are public values (safe to ship).
+//
+// This runs at render time (not in an effect, and not via a nonce'd <script> that could
+// be deferred/blocked in dev), so the global is set before sibling/descendant components
+// render. It's mounted in the root layout, so the value persists across client navigations.
+type PublicEnv = { url: string; anonKey: string; r2Base?: string };
+
+declare global {
+  interface Window {
+    __NEXTBLOCK_PUBLIC_ENV__?: PublicEnv;
+  }
+}
+
+export function PublicEnvBootstrap({ url, anonKey, r2Base }: PublicEnv) {
+  if (typeof window !== 'undefined' && url && anonKey) {
+    window.__NEXTBLOCK_PUBLIC_ENV__ = { url, anonKey, r2Base };
+  }
+  return null;
+}

package/templates/nextblock-template/components/header-auth.tsx

@@ -1,70 +1,32 @@
 'use client';
 
-import { hasPublicEnvVars } from "@nextblock-cms/utils";
-import Link from "next/link";
-import { Avatar, AvatarFallback, AvatarImage } from "@nextblock-cms/ui";
-import { Badge } from "@nextblock-cms/ui";
-import { Button } from "@nextblock-cms/ui";
-import { signOutAction } from "../app/actions";
-import { useAuth } from "../context/AuthContext";
-import { useTranslations } from "@nextblock-cms/utils";
-
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
-} from "@nextblock-cms/ui";
+import Link from "next/link";
+import { Avatar, AvatarFallback, AvatarImage } from "@nextblock-cms/ui";
+import { Button } from "@nextblock-cms/ui";
+import { signOutAction } from "../app/actions";
+import { useAuth } from "../context/AuthContext";
+import { useTranslations } from "@nextblock-cms/utils";
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@nextblock-cms/ui";
 import { User, LogOut, LayoutDashboard } from "lucide-react";
 
-export default function AuthButton() {
-  const { user, profile, isAdmin, isWriter } = useAuth();
-  const { t } = useTranslations();
-  const displayName = profile?.full_name || profile?.github_username || user?.email || null;
-  const showAdminLink = isAdmin || isWriter;
-
-  const handleSignOut = async () => {
-    await signOutAction();
-  };
+export default function AuthButton() {
+  const { user, profile, isAdmin, isWriter } = useAuth();
+  const { t } = useTranslations();
+  const displayName = profile?.full_name || profile?.github_username || user?.email || null;
+  const showAdminLink = isAdmin || isWriter;
+
+  const handleSignOut = async () => {
+    await signOutAction();
+  };
 
-  if (!hasPublicEnvVars) {
-    return (
-      <>
-        <div className="flex gap-4 items-center">
-          <div>
-            <Badge
-              variant={"default"}
-              className="font-normal pointer-events-none"
-            >
-              {t('update_env_file_warning')}
-            </Badge>
-          </div>
-          <div className="flex gap-2">
-            <Button
-              asChild
-              size="sm"
-              variant={"outline"}
-              disabled
-              className="opacity-75 cursor-none pointer-events-none"
-            >
-              <Link href="/sign-in">{t('sign_in')}</Link>
-            </Button>
-            <Button
-              asChild
-              size="sm"
-              variant={"default"}
-              disabled
-              className="opacity-75 cursor-none pointer-events-none"
-            >
-              <Link href="/sign-up">{t('sign_up')}</Link>
-            </Button>
-          </div>
-        </div>
-      </>
-    );
-  }
   return user ? (
     <div className="flex items-center gap-4">
       <DropdownMenu>

package/templates/nextblock-template/docker-compose.yml

@@ -98,6 +98,9 @@ services:
       KONG_PLUGINS: request-transformer,cors,key-auth,acl
       KONG_NGINX_PROXY_PROXY_BUFFER_SIZE: 160k
       KONG_NGINX_PROXY_PROXY_BUFFERS: 64 160k
+      # localhost cookies aren't port-scoped, so the app's Supabase auth cookies are also sent to
+      # Kong on every supabase-js request — give nginx room so they don't 431.
+      KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS: 8 32k
       SUPABASE_ANON_KEY: ${ANON_KEY}
       SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY}
     volumes:
@@ -179,8 +182,9 @@ services:
       NODE_ENV: production
       PORT: 3000
       HOSTNAME: 0.0.0.0
+      # Browser AND server both use localhost:8000; the in-container loopback proxy (see Dockerfile)
+      # forwards it to Kong, keeping the host-derived Supabase auth cookie key consistent for SSR.
       NEXT_PUBLIC_SUPABASE_URL: ${NEXT_PUBLIC_SUPABASE_URL:-http://localhost:8000}
-      SUPABASE_INTERNAL_URL: ${SUPABASE_INTERNAL_URL:-http://kong:8000}
       NEXT_PUBLIC_SUPABASE_ANON_KEY: ${ANON_KEY}
       SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
       NEXT_PUBLIC_URL: ${NEXT_PUBLIC_URL:-http://localhost:3000}

package/templates/nextblock-template/docs/11-SELF-HOSTED-DOCKER.md

@@ -0,0 +1,173 @@
+# 11 Self-Hosted Docker Mode
+
+## Purpose
+
+NextBlock can run as a complete, fully local stack with one command — **no Supabase
+Cloud, Vercel, Cloudflare R2, or SMTP account required**. It mirrors the production
+topology (Next.js 16 app + Supabase API behind a gateway + S3 object storage) on your
+own machine, so the **same application code runs locally and in the cloud with no
+variations** — only environment values differ.
+
+This is the "one-click local sandbox": pick Docker, and the installer drop-ships a
+hardened multi-stage app image alongside the core Supabase engines, an automated
+migration runner, and S3-compatible storage.
+
+## Choosing it
+
+Both initializers offer the choice up front:
+
+- **Monorepo / `git clone`:** `npm run setup` → select **"Local Self-Hosted Docker Mode"**
+- **Standalone CLI:** `npm create nextblock` → the same selector
+- **Direct:** `npm run docker:setup`
+
+In every case the work is driven by a single root hook: **`npm run docker:setup`**.
+
+## Prerequisites
+
+- **Docker Desktop** installed and running (<https://www.docker.com/products/docker-desktop>).
+- That's it. No cloud accounts, keys, or manual migrations.
+
+## Quick start
+
+```bash
+# Monorepo
+git clone https://github.com/nextblock-cms/nextblock.git
+cd nextblock
+npm install
+npm run docker:setup          # or: npm run setup  →  pick Docker
+
+# Standalone project
+npm create nextblock          # →  pick "Local Self-Hosted Docker Mode"
+```
+
+`docker:setup` then:
+
+1. Verifies Docker is installed and running.
+2. Asks **two optional questions** (Cloudflare Turnstile, SMTP) — both skippable with Enter.
+3. Generates a root `.env` with secure random secrets and **properly-signed Supabase
+   anon/service keys** (real HS256 JWTs derived from a generated `JWT_SECRET`).
+4. Builds the app image and boots the whole stack.
+
+When it finishes:
+
+| What | Where |
+| :--- | :--- |
+| App | <http://localhost:3000> |
+| Sign up | <http://localhost:3000/sign-up> — the **first account becomes ADMIN** |
+| Supabase API gateway | <http://localhost:8000> |
+| MinIO console | <http://localhost:9001> |
+
+With no SMTP configured, accounts are **auto-confirmed** and the first sign-up lands
+straight in `/cms/dashboard` — no confirmation email step.
+
+## The two optional prompts
+
+| Prompt | If you skip it |
+| :--- | :--- |
+| **Cloudflare Turnstile** site + secret key | Uses Cloudflare's official "always pass" test keys — forms work, with no real bot protection. |
+| **SMTP** host (+ port / user / pass / from) | GoTrue **auto-confirms** sign-ups; no email is sent, and the first admin can sign in immediately. |
+
+Provide real SMTP if you want actual confirmation emails — auto-confirm is then disabled,
+exactly like the cloud flow.
+
+## What you get (the stack)
+
+The root `docker-compose.yml` runs a trimmed, production-equivalent Supabase stack plus
+the app. Every image tag is pinned and overridable via an env var (e.g. `SUPABASE_DB_IMAGE`).
+
+| Service | Image (default) | Role |
+| :--- | :--- | :--- |
+| `db` | `supabase/postgres` | Postgres with the Supabase roles, schemas, and extensions. Named volume `nextblock_db_store`. |
+| `auth` | `supabase/gotrue` | Auth: sessions, JWTs, the `auth.users` table. |
+| `rest` | `postgrest/postgrest` | Instant REST API over the `public` / `graphql_public` schemas. |
+| `kong` | `kong` | Edge gateway — maps `/auth/v1`, `/rest/v1`, `/graphql/v1` to port **8000**. |
+| `minio` + `minio-init` | `minio/minio`, `minio/mc` | S3-compatible media storage + a public `nextblock` bucket. Named volume `nextblock_media`. |
+| `migrate` | `postgres:alpine` | Applies `libs/db/src/supabase/migrations` in order, **once**, then exits. |
+| `nextblock-cms` | built locally | The Next.js standalone app on **3000**. Boots **only after `migrate` succeeds**. |
+
+Both named volumes persist your database and uploaded media across restarts.
+
+### Commands
+
+| Command | Does |
+| :--- | :--- |
+| `npm run docker:setup` | Generate `.env` → build → up. The one-click entry point. |
+| `npm run docker:up` | Rebuild and (re)start the stack. |
+| `npm run docker:down` | Stop the stack. Add `-v` to also delete the volumes (wipes local data). |
+| `npm run docker:logs` | Follow the app logs (`docker compose logs -f nextblock-cms`). |
+
+### Ports (override with env vars)
+
+`APP_PORT` (3000), `KONG_HTTP_PORT` (8000), `MINIO_S3_PORT` (9000),
+`MINIO_CONSOLE_PORT` (9001), `POSTGRES_PORT_EXTERNAL` (54322).
+
+## How it works
+
+The interesting part is making one codebase work unchanged in both modes. A few
+mechanisms make that possible:
+
+- **Standalone build.** The app Dockerfile is multi-stage (deps → builder → hardened
+  non-root runner) and builds with Next.js `output: 'standalone'`, gated on a
+  `DOCKER_BUILD` env var so normal/Vercel builds are untouched. The runner ships only the
+  traced server tree, `.next/static`, and `public`.
+
+- **One URL + an in-container loopback proxy.** The browser reaches Supabase at
+  `http://localhost:8000`, and that value is inlined into the build. Server-side code runs
+  *inside* the container, where `localhost` has nothing — so the runner starts a tiny
+  `socat` proxy that forwards in-container `127.0.0.1:8000 → kong:8000` and
+  `127.0.0.1:9000 → minio:9000`. Browser and server therefore use the **same URL**, which
+  also keeps the Supabase auth-cookie key (derived from the URL host) identical on both
+  sides so SSR can read the session.
+
+- **Storage on `127.0.0.1`.** Media URLs use `http://127.0.0.1:9000` (not `localhost`).
+  On `localhost`, cookies are not port-scoped, so the browser would otherwise send the
+  app's auth cookies to MinIO and trip its header-size limit. `127.0.0.1` is a different
+  cookie host, so MinIO always receives clean image requests.
+
+- **Migration runner.** The `migrate` service waits for the database to be healthy and
+  for GoTrue to create `auth.users` (the schema FKs to it), then applies each migration in
+  order inside a transaction. It records applied versions, so restarts never re-run a
+  migration.
+
+- **Generated keys.** `docker:setup` generates a `JWT_SECRET` and derives valid HS256
+  `anon` and `service_role` JWTs from it (using Node's built-in `crypto`), so GoTrue,
+  PostgREST, and Kong all validate against the same secret out of the box.
+
+## Cloud vs Docker — same code, different env
+
+There are **no application code paths** specific to Docker. The difference is purely
+configuration:
+
+| | Managed Cloud | Self-Hosted Docker |
+| :--- | :--- | :--- |
+| Database / Auth | Supabase Cloud | `supabase/postgres` + `supabase/gotrue` |
+| Object storage | Cloudflare R2 | MinIO (S3-compatible) |
+| Email | Required SMTP | Optional — GoTrue auto-confirms without it |
+| Run command | `npx nx serve nextblock` / Vercel | `npm run docker:setup` |
+| Config | `.env.local` (cloud keys) | `.env` (generated local secrets) |
+
+> The R2 client already speaks S3, so MinIO is pointed at it via `R2_S3_ENDPOINT` /
+> `R2_FORCE_PATH_STYLE`; uploads are signed for the browser via `R2_S3_PUBLIC_ENDPOINT`.
+> A reference of every key the stack reads lives in `.env.docker.example`.
+
+## Troubleshooting
+
+- **"Docker is not installed or not running."** Start Docker Desktop and re-run
+  `npm run docker:setup`.
+
+- **`port is already allocated`.** Another process (often a previous stack) holds 8000 /
+  9000 / 3000 / 54322. Stop it, or override the port env vars above.
+
+- **GoTrue fails with `password authentication failed for user "supabase_auth_admin"`
+  (28P01) after a re-clone.** A leftover named volume from a previous install still holds
+  the old password, while your new `.env` has fresh secrets. Postgres only runs its
+  credential-setting init scripts on an *empty* volume. Fix:
+  `docker compose down -v && npm run docker:up`. (`docker:setup` does this automatically
+  when it generates a brand-new `.env`.)
+
+- **Re-running `docker:setup`.** If a `.env` already exists it **reuses your secrets and
+  keeps your data** — safe to re-run to rebuild after pulling changes.
+
+- **Wipe everything and start clean.** `docker compose down -v` removes the containers and
+  both named volumes (database + media).
+</content>

package/templates/nextblock-template/docs/12-VERCEL-DEPLOYMENT.md

@@ -0,0 +1,67 @@
+# 12 · Cloud Deployment (Deploy to Vercel)
+
+NextBlock ships a one-click **Deploy to Vercel** button (see the README) that brings
+up a production instance already connected to a managed Supabase project. From there,
+the in-app **First-Boot Setup Wizard** (`/setup`) finishes configuration in the
+browser — there is no terminal step.
+
+## How the button works
+
+The badge links to `https://vercel.com/new/clone` with these query parameters:
+
+| Parameter | Purpose |
+| :--- | :--- |
+| `repository-url` | The NextBlock repo to clone into the user's Git provider. |
+| `integration-ids=oac_VqOgBHqhEoFTPzGkPd7L0iH6` | Vercel's **Supabase integration**. During import, Vercel provisions (or links) a Supabase project and injects its environment variables automatically. |
+| `env=NEXT_PUBLIC_URL,CRON_SECRET,DRAFT_MODE_SECRET,REVALIDATE_SECRET_TOKEN` | The remaining variables Vercel prompts for. Only variable **names** are listed — never secret values. |
+| `envDescription` / `envLink` | Help text + a link back to this doc. |
+
+The Supabase integration injects the keys the app needs to boot:
+`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`,
+`SUPABASE_SERVICE_ROLE_KEY`, and `POSTGRES_URL`. Because those are present on first
+boot, the instance is **Profile A (pre-configured)**: the wizard skips the connection
+step and goes straight to creating the first administrator.
+
+## What the wizard does on Vercel
+
+1. **Database** — already connected (integration-injected). The wizard verifies a
+   first admin doesn't exist yet, otherwise it redirects to `/cms/dashboard`.
+2. **Schema** — apply the migrations to the managed Supabase project. The Supabase
+   integration creates the project but does **not** run NextBlock's migrations, so run
+   them once after the first deploy (locally against the project, or via the Supabase
+   dashboard SQL editor) — see [docs/04](./04-DATABASE-AND-AUTH.md) and
+   [docs/05](./05-DEVELOPER-GUIDE.md).
+3. **Storage** — pre-filled for **Supabase Storage** (S3-compatible). The wizard's
+   storage step shows the endpoint derived from your Supabase URL
+   (`<project>/storage/v1/s3`). Create an S3 access key in the Supabase dashboard
+   (Storage → S3 connection) and set `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` in
+   your Vercel project environment. (Cloudflare R2 remains the default for non-Vercel
+   installs — it has a more generous free storage tier; only the one-click Vercel
+   path defaults to Supabase Storage.)
+4. **Email / Bot protection / Sign-ups** — optional steps; bot-protection and the
+   sign-up policy persist to the database and work immediately. SMTP, if used, is set
+   as Vercel environment variables.
+5. **Administrator** — create the first admin. The account is created already
+   confirmed (`email_confirm: true`), so no verification email is required.
+
+> Filesystem is read-only on Vercel, so the wizard never writes `.env.local` there —
+> all configuration is environment variables (platform-managed) plus the database.
+
+## Cron jobs and the free tier
+
+`vercel.json` declares two daily crons (`/api/cron/reset-sandbox` and
+`/api/cron/sync-currencies`). Vercel's **Hobby (free) tier allows one cron per day**.
+For a free-tier production deploy, either:
+
+- Upgrade to a paid plan (both crons run as declared), **or**
+- Keep only the cron you need (most production sites don't need `reset-sandbox`, which
+  exists for the public demo sandbox), **or**
+- Consolidate both jobs into a single cron handler.
+
+This is intentionally left as a deploy-time decision rather than changed in the repo,
+since the sandbox/demo deploy relies on both crons.
+
+## After deploy
+
+Visit the deployment URL — it redirects to `/setup` until the first admin exists.
+Complete the wizard, then sign in at `/cms/dashboard`.

package/templates/nextblock-template/docs/README.md

@@ -16,6 +16,7 @@ library surfaces rather than historical planning notes.
 - Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
 - Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
 - Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
+- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
 
 ## Audience Guide
 
@@ -25,6 +26,7 @@ library surfaces rather than historical planning notes.
 - Custom block work: read `03`, then `10`.
 - AI / Cortex work: read `08`.
 - CLI or template work: read `06`.
+- Running everything locally without cloud accounts: read `11`.
 - AI agents: start with this index, then move directly to the subsystem file that
   matches the task. Treat `apps/nextblock`, `libs/*`, and
   `libs/db/src/supabase/migrations` as the final authority if a doc and code ever

package/templates/nextblock-template/lib/blocks/FeaturedProductBlock.tsx

@@ -25,7 +25,7 @@ export const FeaturedProductBlock = async ({ content }: { content: FeaturedProdu
      } else if (process.env.NEXT_PUBLIC_R2_BASE_URL) {
        imageUrl = `${process.env.NEXT_PUBLIC_R2_BASE_URL}/${mediaItem.file_path}`;
      } else {
-       imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL}/storage/v1/object/public/media/${mediaItem.file_path}`;
+       imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL ?? ''}/storage/v1/object/public/media/${mediaItem.file_path}`;
      }
   }
 

package/templates/nextblock-template/lib/blocks/ProductGridBlock.tsx

@@ -62,7 +62,7 @@ export const ProductGridBlock = async ({
          } else if (process.env.NEXT_PUBLIC_R2_BASE_URL) {
            imageUrl = `${process.env.NEXT_PUBLIC_R2_BASE_URL}/${mediaItem.file_path}`;
          } else {
-           imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL}/storage/v1/object/public/media/${mediaItem.file_path}`;
+           imageUrl = `${process.env.NEXT_PUBLIC_SUPABASE_URL ?? ''}/storage/v1/object/public/media/${mediaItem.file_path}`;
          }
       }
 

package/templates/nextblock-template/lib/media/resolveMediaUrl.ts

@@ -20,7 +20,15 @@ const BUNDLED_PUBLIC_MEDIA_KEYS = new Set([
 
 export function resolveMediaUrl(
   objectKey?: string | null,
-  baseUrl = process.env.NEXT_PUBLIC_R2_BASE_URL || ''
+  // On the client, NEXT_PUBLIC_R2_BASE_URL is inlined at build time, so a fresh-clone
+  // dev bundle built with no env holds an empty string; fall back to the runtime value
+  // injected by <PublicEnvBootstrap> (window.__NEXTBLOCK_PUBLIC_ENV__.r2Base). On the
+  // server, process.env is always current and the window branch is skipped.
+  baseUrl = process.env.NEXT_PUBLIC_R2_BASE_URL ||
+    (typeof window !== 'undefined'
+      ? (window as { __NEXTBLOCK_PUBLIC_ENV__?: { r2Base?: string } })
+          .__NEXTBLOCK_PUBLIC_ENV__?.r2Base || ''
+      : '')
 ) {
   if (!objectKey) return null;