gib/convex-monorepo-payload
Template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update all docs & md files

Browse Source
This commit is contained in:
Gabriel Brown
2026-03-27 17:49:07 -05:00
parent e1f9cc4edf
commit 5ee4da55d3
3 changed files with 420 additions and 546 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
AGENTS.md
View File

@@ -5,6 +5,10 @@ repository. Read it fully before making any changes. It covers architecture, pat
constraints, and known issues — everything you need to work effectively without
breaking things or introducing inconsistencies.
This file is a living document. If your work changes architecture, workflows,
deployment scripts, Payload structure, important file paths, or known issues, update
`AGENTS.md` in the same task so the next agent inherits the right context.
---
## Table of Contents
@@ -294,6 +298,10 @@ The root `.env` is gitignored. The root `.env.example` is the committed template
shows all required variable names without real values. **Keep `.env.example` up to
date whenever you add a new env var.**
The root `/.env` is also the only required Docker Compose env file. The helper scripts
in `scripts/` load this same root file before calling `docker compose`, so do not
create or rely on a separate `docker/.env`.
### Complete variable reference
| Variable | Used By | Purpose | Sync to Convex? |
@@ -309,6 +317,19 @@ date whenever you add a new env var.**
| `NEXT_PUBLIC_SENTRY_PROJECT_NAME` | Next.js build | Sentry project name | No |
| `PAYLOAD_SECRET` | Payload CMS | Payload application secret | No |
| `PAYLOAD_DB_URL` | Payload CMS | Postgres connection string used by Payload | No |
| `NETWORK` | Docker Compose | External Docker network name | No |
| `NEXT_CONTAINER_NAME` | Docker Compose | Next.js container name | No |
| `NEXT_DOMAIN` | Docker Compose | Public Next.js domain used by compose interpolation | No |
| `BACKEND_CONTAINER_NAME` | Docker Compose | Convex backend container name | No |
| `DASHBOARD_CONTAINER_NAME` | Docker Compose | Convex dashboard container name | No |
| `BACKEND_DOMAIN` | Docker Compose | Public backend domain used in compose interpolation | No |
| `DASHBOARD_DOMAIN` | Docker Compose | Public dashboard domain used in compose interpolation | No |
| `INSTANCE_NAME` | Docker Compose | Self-hosted Convex instance name | No |
| `INSTANCE_SECRET` | Docker Compose | Self-hosted Convex instance secret | No |
| `CONVEX_CLOUD_ORIGIN` | Docker Compose | Public Convex API origin | No |
| `CONVEX_SITE_ORIGIN` | Docker Compose | Public Convex site/auth origin | No |
| `NEXT_PUBLIC_DEPLOYMENT_URL` | Docker Compose | Deployment URL passed to Convex dashboard | No |
| `POSTGRES_URL` | Docker Compose | Self-hosted Convex Postgres connection string | No |
| `CONVEX_SELF_HOSTED_URL` | Convex CLI | URL of the self-hosted Convex backend | No |
| `CONVEX_SELF_HOSTED_ADMIN_KEY` | Convex CLI | Admin key for the self-hosted backend | No |
| `CONVEX_SITE_URL` | Convex Auth | CORS domain for token exchange (localhost:3000 for dev) | Yes (Dashboard) |
@@ -384,6 +405,9 @@ Or set it directly in the Convex Dashboard.
Also update `/.env.example` with the new variable (empty value or a placeholder).
If the variable is used by Docker Compose or one of the helper scripts in `scripts/`,
it still belongs in the same root `/.env`.
---
## 6. Dependency Management — The Catalog System
@@ -781,16 +805,43 @@ pieces are:
generated admin/API files
- **`apps/next/src/payload/collections/`** and `apps/next/src/payload/globals/` — the
editable Payload schema files you should actually work in
- **`apps/next/src/payload/globals/landing-page-blocks.ts`** — the current block schema
definitions for the landing-page global
- **`apps/next/src/lib/payload/`** — server helpers for obtaining the cached Payload
client and fetching CMS content
- **`apps/next/src/components/payload/refresh-route-on-save.tsx`** — enables live
preview refreshes for the landing page when `?preview=true` is present
Current state of the template:
- Payload currently powers the homepage via the `landing-page` global, not a `pages`
collection
- the editable block definitions live in
`apps/next/src/payload/globals/landing-page-blocks.ts`
- the frontend reads the saved global through
`apps/next/src/lib/payload/get-landing-page-content.ts`
- saved Payload content is merged with resilient defaults from
`apps/next/src/components/landing/content.ts`, so the page still renders even when
content is partial or missing fields
- live preview works by loading `/` with `?preview=true` and rendering
`RefreshRouteOnSave`
If you need a deeper walkthrough, read `docs/payload-cms.md`. That file should stay in
sync with the actual Payload implementation in this repo.
The current homepage is backed by the `landing-page` Payload global. The server page at
`apps/next/src/app/(frontend)/page.tsx` calls
`apps/next/src/lib/payload/get-landing-page-content.ts`, which merges saved Payload
content with defaults from `apps/next/src/components/landing/content.ts`.
When adding more Payload-managed marketing content in this template, there are two
reasonable paths:
1. add another Payload global plus a matching frontend route if the page is singular
and custom
2. introduce a `pages` collection once you need many reusable CMS-managed pages with
shared routing patterns
### The dual Convex provider setup
Two providers are required and both must be present:
@@ -1148,22 +1199,15 @@ The Convex backend and dashboard are long-running and rarely need to be rebuilt.
The typical workflow when you've made changes to the Next.js app:
```bash
# On the production server (via SSH)
cd docker/
# Build the Next.js app with current source
sudo docker compose build next-app
# Once build succeeds, bring up the new container
sudo docker compose up -d next-app
./scripts/build-next-app
```
If you need to start everything from scratch:
```bash
sudo docker compose up -d convex-backend convex-dashboard
./scripts/docker-compose up -d backend dashboard
# Wait for backend to be healthy, then:
sudo docker compose up -d next-app
./scripts/docker-compose up -d next
```
### The `.dockerignore` situation (known issue)
@@ -1180,11 +1224,22 @@ Do not un-comment those lines without understanding the full implications — re
`.env` from the build context would break Sentry source map uploads and
`NEXT_PUBLIC_*` variable baking into the client bundle.
**Note on `docker/.env`:** This file is entirely separate and serves a different
purpose. It is read by Docker Compose itself (not the build) to interpolate the
`${VARIABLE}` placeholders in `compose.yml` — things like container names, network
names, and Convex origin URLs. It is not the same as the root `/.env` and the two
are not interchangeable.
Docker Compose now reads from the root `/.env`, and the helper scripts in `scripts/`
wrap Compose so you do not need to repeatedly pass `--env-file` and `-f`.
### Docker helper scripts
The preferred deployment workflow now uses the helper scripts in `scripts/`:
- `scripts/docker-compose` — wrapper for custom Compose commands using the repo's root
`/.env` and `docker/compose.yml`
- `scripts/build-next-app` — build and restart the Next container
- `scripts/update-next-app` — `git pull`, then build and restart the Next container
- `scripts/update-convex` — pull and restart the backend/dashboard containers
- `scripts/generate-convex-admin-key` — run the backend container's admin key script
The `scripts/docker-compose` wrapper also translates short aliases like `next`,
`backend`, and `dashboard` into the container names defined in the root `/.env`.
### Convex data persistence
@@ -1192,13 +1247,12 @@ are not interchangeable.
This directory is gitignored. Back it up before any server migrations, restarts, or
image updates.
### `generate_convex_admin_key`
### `generate-convex-admin-key`
A bash script in `docker/` that generates the admin key from a running Convex backend:
A bash script in `scripts/` generates the admin key from a running Convex backend:
```bash
cd docker/
./generate_convex_admin_key
./scripts/generate-convex-admin-key
```
This runs the key generation script inside the `convex-backend` container and prints
@@ -1281,11 +1335,13 @@ deployment), these things should be updated:
repository URL, and quick-start text
- `apps/next/src/payload/globals/landing-page.ts` — update or replace the current landing
page global schema
- `apps/next/src/payload/globals/landing-page-blocks.ts` — update the landing-page block
definitions if the marketing content model changes
- `apps/next/src/payload.config.ts` — add/remove Payload collections and globals as the
project evolves
- Root `package.json` — update the workspace `name` field to fit the new project
- `/.env` — fill out all values for the new deployment
- `docker/.env` — fill out container names and domain URLs
- `/.env` — also fill out the Docker Compose container names and domain URLs
---
@@ -1323,12 +1379,18 @@ deployment), these things should be updated:
### Adding or changing Payload content
1. Edit the relevant schema file in `apps/next/src/payload/collections/` or
`apps/next/src/payload/globals/`
2. Register the collection/global in `apps/next/src/payload.config.ts`
3. Fetch the content from server code via `apps/next/src/lib/payload/`
1. For the current homepage, edit the landing-page global or its block definitions in
`apps/next/src/payload/globals/landing-page.ts` and
`apps/next/src/payload/globals/landing-page-blocks.ts`
2. Keep the frontend data contract in sync with
`apps/next/src/components/landing/content.ts`
3. Fetch or merge the content through `apps/next/src/lib/payload/`
4. If you need fresh Payload types, regenerate `apps/next/payload-types.ts`
5. Do not hand-edit the generated files in `apps/next/src/app/(payload)/`
5. If you change the database schema shape, regenerate
`apps/next/src/payload-generated-schema.ts`
6. Do not hand-edit the generated files in `apps/next/src/app/(payload)/`
7. If you introduce additional Payload-managed pages or collections, update
`docs/payload-cms.md` and this `AGENTS.md` file in the same task
### Adding a new environment variable
@@ -1443,12 +1505,13 @@ on Gitea) for automated lint and typecheck on pull requests.
Currently:
- `packages/backend/scripts/generateKeys.mjs` — generates JWT keys (run manually)
- `docker/generate_convex_admin_key` — bash script to get the admin key from Docker
- `scripts/generate-convex-admin-key` — bash script to get the admin key from Docker
- `scripts/docker-compose` and related helpers — wrap Docker Compose with the root
`/.env`
These are separate workflows that both need to be run once when setting up a new
deployment. Explore combining these into a unified setup script — potentially one that
generates the keys AND automatically syncs them to Convex in one step, possibly
moving everything to `docker/scripts/`.
generates the keys AND automatically syncs them to Convex in one step.
---
@@ -1499,10 +1562,11 @@ bun dev # Runs convex dev (push functions + watch)
bun setup # Runs convex dev --until-success (push once then exit)
bun with-env npx convex env set VAR "value" # Sync env var to Convex deployment
# ── Docker (run from docker/) ─────────────────────────────────────────────────
sudo docker compose up -d convex-backend convex-dashboard # Start Convex
sudo docker compose build next-app # Build Next.js image
sudo docker compose up -d next-app # Deploy Next.js
sudo docker compose logs -f # Stream all logs
./generate_convex_admin_key # Get admin key
# ── Docker / Deployment ───────────────────────────────────────────────────────
./scripts/docker-compose ps # Show compose status
./scripts/docker-compose up -d backend dashboard # Start Convex
./scripts/build-next-app # Build and deploy Next.js app
./scripts/update-next-app # git pull + rebuild Next.js app
./scripts/update-convex # Pull and restart Convex services
./scripts/generate-convex-admin-key # Get admin key
```