create-nextblock 0.8.11 → 0.9.5

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/custom-block-r2-upload.test.ts

@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 vi.mock('server-only', () => ({}));
 
 const mocks = vi.hoisted(() => ({
-  getS3ClientMock: vi.fn(),
+  getS3PresignClientMock: vi.fn(),
   getSignedUrlMock: vi.fn(),
   getUserMock: vi.fn(),
   profileSingleMock: vi.fn(),
@@ -28,7 +28,7 @@ vi.mock('@nextblock-cms/db/server', () => ({
 }));
 
 vi.mock('@nextblock-cms/utils/server', () => ({
-  getS3Client: mocks.getS3ClientMock,
+  getS3PresignClient: mocks.getS3PresignClientMock,
 }));
 
 vi.mock('@aws-sdk/client-s3', () => ({
@@ -82,7 +82,7 @@ describe('custom block R2 presigned upload flow', () => {
     );
 
     expect(response.status).toBe(401);
-    expect(mocks.getS3ClientMock).not.toHaveBeenCalled();
+    expect(mocks.getS3PresignClientMock).not.toHaveBeenCalled();
   });
 
   it('rejects oversized files for authorized writers', async () => {
@@ -103,13 +103,13 @@ describe('custom block R2 presigned upload flow', () => {
 
     expect(response.status).toBe(400);
     expect(payload.error).toContain('10 MB');
-    expect(mocks.getS3ClientMock).not.toHaveBeenCalled();
+    expect(mocks.getS3PresignClientMock).not.toHaveBeenCalled();
   });
 
   it('returns a direct PUT upload space for authorized writers', async () => {
     mocks.getUserMock.mockResolvedValueOnce({ data: { user: { id: 'user-1' } }, error: null });
     mocks.profileSingleMock.mockResolvedValueOnce({ data: { role: 'ADMIN' }, error: null });
-    mocks.getS3ClientMock.mockResolvedValueOnce({ send: vi.fn() });
+    mocks.getS3PresignClientMock.mockResolvedValueOnce({ send: vi.fn() });
     mocks.getSignedUrlMock.mockResolvedValueOnce('https://r2.example.test/presigned-put');
 
     const response = await POST(

package/templates/nextblock-template/lib/custom-block-r2-upload.ts

@@ -2,7 +2,7 @@ import 'server-only';
 
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
-import { getS3Client } from '@nextblock-cms/utils/server';
+import { getS3PresignClient } from '@nextblock-cms/utils/server';
 
 import { resolveMediaUrl } from './media/resolveMediaUrl';
 import {
@@ -35,7 +35,7 @@ export async function createR2PresignedUpload(
     throw new R2PresignedUploadError('File uploads are not configured on this server.', 500);
   }
 
-  const s3Client = await getS3Client();
+  const s3Client = await getS3PresignClient();
   if (!s3Client) {
     throw new R2PresignedUploadError('File uploads are not configured on this server.', 500);
   }