Update all docs & md files

2026-03-27 17:49:07 -05:00
parent e1f9cc4edf
commit 5ee4da55d3
3 changed files with 420 additions and 546 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # Convex Turbo Monorepo

-A production-ready Turborepo starter with Next.js, Expo, and self-hosted Convex backend. Built with TypeScript, Tailwind CSS, and modern tooling.
+A production-ready Turborepo starter with Next.js, Expo, self-hosted Convex, and
+embedded Payload CMS for live-editable marketing content. Built with TypeScript,
+Tailwind CSS, and modern tooling.

 ---

@@ -22,6 +24,7 @@ A production-ready Turborepo starter with Next.js, Expo, and self-hosted Convex
 - **Framework:** Next.js 16 (App Router) + Expo 54
 - **Backend:** Convex (self-hosted)
 - **Auth:** @convex-dev/auth with Authentik OAuth & Password providers
+- **CMS:** Payload CMS embedded inside the Next.js app
 - **Styling:** Tailwind CSS v4 + shadcn/ui
 - **Language:** TypeScript (strict mode)
 - **Package Manager:** Bun
@@ -64,39 +67,45 @@ git remote add origin https://your-git-host.com/your/new-repo.git

 ---

-### Step 2 — Configure the Docker Environment
-
-The `docker/` directory contains everything needed to run the Convex backend and the
-Next.js app in production.
+### Step 2 — Configure the Single Root Environment File

 ```bash
-cd docker/
 cp .env.example .env
 ```

-Edit `docker/.env` and fill in your values. The variables below the Next.js app section
-control the Convex containers — you'll need to choose:
+The root `/.env` is the single required env file for this repo. It is used for:
+
+- app/package runtime env vars
+- Next.js build-time env vars
+- Payload env vars
+- Docker Compose interpolation
+- helper scripts in `scripts/`
+
+Fill it in with your values. The Docker-related variables in the same file control the
+Convex containers and Next.js container — you'll need to choose:

 - `INSTANCE_NAME` — a unique name for your Convex instance
 - `INSTANCE_SECRET` — a secret string (generate something random)
 - `CONVEX_CLOUD_ORIGIN` — the public HTTPS URL for your Convex backend API (e.g. `https://api.convex.example.com`)
 - `CONVEX_SITE_ORIGIN` — the public HTTPS URL for Convex Auth HTTP routes (e.g. `https://api.convex.example.com`)
 - `NEXT_PUBLIC_DEPLOYMENT_URL` — the URL for the Convex dashboard (e.g. `https://dashboard.convex.example.com`)
+- `NEXT_CONTAINER_NAME`, `BACKEND_CONTAINER_NAME`, and `DASHBOARD_CONTAINER_NAME` — the Docker service container names
+
+Do not create or rely on a separate `docker/.env`.

 ---

 ### Step 3 — Start the Convex Containers

 ```bash
-cd docker/
-sudo docker compose up -d convex-backend convex-dashboard
+./scripts/docker-compose up -d backend dashboard
 ```

 Wait a moment for `convex-backend` to pass its health check, then verify both
 containers are running:

 ```bash
-sudo docker compose ps
+./scripts/docker-compose ps
 ```

 Reverse-proxy the two Convex services through nginx-proxy-manager (or your preferred
@@ -110,8 +119,7 @@ can proceed.
 With the backend container running, generate the admin key:

 ```bash
-cd docker/
-./generate_convex_admin_key
+./scripts/generate-convex-admin-key
 ```

 Copy the printed key — you'll need it as `CONVEX_SELF_HOSTED_ADMIN_KEY` in the root
@@ -119,21 +127,16 @@ Copy the printed key — you'll need it as `CONVEX_SELF_HOSTED_ADMIN_KEY` in the

 ---

-### Step 5 — Configure Root Environment Variables
+### Step 5 — Finish Configuring Root Environment Variables

-Create the root `.env` file:
-
-```bash
-# From the repo root
-cp .env.example .env
-```
-
-Fill out all values in `/.env`:
+Fill out all values in root `/.env`:

 ```bash
 # Next.js
 NODE_ENV=development
 SENTRY_AUTH_TOKEN=               # From your self-hosted Sentry
+PAYLOAD_SECRET=                  # openssl rand -hex 32
+PAYLOAD_DB_URL=postgresql://user:password@host:5432/db_name
 NEXT_PUBLIC_SITE_URL=https://example.com
 NEXT_PUBLIC_CONVEX_URL=https://api.convex.example.com
 NEXT_PUBLIC_PLAUSIBLE_URL=https://plausible.example.com
@@ -154,6 +157,18 @@ USESEND_FROM_EMAIL=My App <noreply@example.com>
 AUTH_AUTHENTIK_ID=
 AUTH_AUTHENTIK_SECRET=
 AUTH_AUTHENTIK_ISSUER=https://auth.example.com/application/o/my-app/
+
+# Docker Compose
+NETWORK=nginx-bridge
+NEXT_CONTAINER_NAME=next-app
+BACKEND_CONTAINER_NAME=convex-backend
+DASHBOARD_CONTAINER_NAME=convex-dashboard
+INSTANCE_NAME=convex
+INSTANCE_SECRET=
+CONVEX_CLOUD_ORIGIN=https://api.convex.example.com
+CONVEX_SITE_ORIGIN=https://convex.convex.example.com
+NEXT_PUBLIC_DEPLOYMENT_URL=https://dashboard.convex.example.com
+POSTGRES_URL=postgresql://user:password@host:5432/convex
 ```

 ---
@@ -209,6 +224,26 @@ bun dev               # All apps (Next.js + Expo + Backend)
 - **Next.js:** http://localhost:3000
 - **Convex Dashboard:** https://dashboard.convex.example.com

+### Docker Helper Scripts
+
+This repo includes helper scripts so you do not have to keep passing `--env-file` and
+`-f` manually to Docker Compose.
+
+Useful commands:
+
+```bash
+./scripts/docker-compose ps
+./scripts/docker-compose up -d backend dashboard
+./scripts/docker-compose up -d next
+./scripts/build-next-app
+./scripts/update-next-app
+./scripts/update-convex
+./scripts/generate-convex-admin-key
+```
+
+`./scripts/docker-compose` also accepts short service aliases like `next`, `backend`,
+and `dashboard` and maps them to the container names from root `/.env`.
+
 ---

 ## Development Commands
@@ -278,7 +313,13 @@ convex-monorepo/
 ├── docker/                  # Self-hosted deployment
 │   ├── compose.yml
 │   ├── Dockerfile
-│   └── .env.example
+│   └── data/                # Convex data volume (gitignored in real use)
+│
+├── scripts/                 # Docker/deployment helper scripts using root .env
+│   ├── docker-compose
+│   ├── build-next-app
+│   ├── update-next-app
+│   └── update-convex
 │
 ├── turbo.json              # Turborepo configuration
 └── package.json            # Root workspace & catalogs
@@ -298,6 +339,7 @@ convex-monorepo/
 ### Next.js App

 - **App Router:** Next.js 16 with React Server Components
+- **Editable Marketing Content:** Payload-backed landing page with live preview
 - **Data Preloading:** SSR data fetching with `preloadQuery` + `usePreloadedQuery`
 - **Middleware:** Route protection & IP-based security (`src/proxy.ts`)
 - **Styling:** Tailwind CSS v4 with dark mode (OKLCH-based theme)
@@ -327,26 +369,18 @@ convex-monorepo/
 ### Production Deployment (Docker)

 Once the Convex containers are running (they only need to be started once), deploying
-a new version of the Next.js app is a two-command workflow:
+a new version of the Next.js app is a one-command workflow:

 ```bash
-# SSH onto your server, then:
-cd docker/
-
-# Build the new image
-sudo docker compose build next-app
-
-# Deploy it
-sudo docker compose up -d next-app
+./scripts/build-next-app
 ```

 To start all services from scratch:

 ```bash
-cd docker/
-sudo docker compose up -d convex-backend convex-dashboard
+./scripts/docker-compose up -d backend dashboard
 # Wait for backend health check to pass, then:
-sudo docker compose up -d next-app
+./scripts/docker-compose up -d next
 ```

 **Services:**
@@ -359,11 +393,10 @@ sudo docker compose up -d next-app

 ### Production Checklist

- [ ] Fill out `docker/.env` with your domain names and secrets
+- [ ] Fill out root `/.env` with all app, Payload, and Docker Compose values
 - [ ] Start `convex-backend` and `convex-dashboard` containers
- [ ] Generate and set `CONVEX_SELF_HOSTED_ADMIN_KEY` via `./generate_convex_admin_key`
+- [ ] Generate and set `CONVEX_SELF_HOSTED_ADMIN_KEY` via `./scripts/generate-convex-admin-key`
 - [ ] Reverse-proxy both Convex services via nginx-proxy-manager with SSL
- [ ] Fill out root `/.env` with all environment variables
 - [ ] Generate JWT keys and sync all env vars to Convex (`bun with-env npx convex env set ...`)
 - [ ] Update `CONVEX_SITE_URL` in the Convex Dashboard to your production Next.js URL
 - [ ] Build and start the `next-app` container
@@ -374,6 +407,7 @@ sudo docker compose up -d next-app
 ## Documentation

 - **[AGENTS.md](./AGENTS.md)** — Comprehensive guide for AI agents & developers
+- **[docs/payload-cms.md](./docs/payload-cms.md)** — How Payload is wired up and how to extend it in this template
 - **[Convex Docs](https://docs.convex.dev)** — Official Convex documentation
 - **[Turborepo Docs](https://turbo.build/repo/docs)** — Turborepo documentation
 - **[Next.js Docs](https://nextjs.org/docs)** — Next.js documentation
@@ -402,11 +436,16 @@ import { api } from '@gib/backend/convex/_generated/api.js';

 ### Docker containers won't start

-1. Check Docker logs: `sudo docker compose logs`
-2. Verify environment variables in `docker/.env`
+1. Check Docker logs: `./scripts/docker-compose logs`
+2. Verify environment variables in root `/.env`
 3. Ensure the `nginx-bridge` network exists: `sudo docker network create nginx-bridge`
 4. Check that the required ports (3210, 6791) are not already in use

+### Only one `.env` file matters
+
+Use the root `/.env` for everything in this repo, including Docker helper scripts and
+Docker Compose interpolation. Do not create or rely on a separate `docker/.env`.
+
 ### Auth doesn't work in production

 Make sure `CONVEX_SITE_URL` is set to your production Next.js URL in the **Convex