Excel/softvowels-webpage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: payload building issues

Browse Source
This commit is contained in:
Excel
2026-06-17 23:58:51 +05:30
parent d3ab5028af
commit e974313f6d
15 changed files with 264 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+106 -152
View File
@@ -1,8 +1,8 @@
# SoftVowels
> A premium tech publication. **Astro 5 (static)** frontend + **PayloadCMS 3** headless backend, deployed with **Docker** and fronted by **Nginx Proxy Manager**.
> A premium tech publication. **Astro 5 (static)** frontend + **PayloadCMS 3** headless backend, deployed with **Docker only** and fronted by **Nginx Proxy Manager**.
SoftVowels is a content-driven site for long-form engineering writing. Editors write in `/admin`; the public site is regenerated on demand and served as static HTML by nginx.
SoftVowels is a content-driven site for long-form engineering writing. Editors write in `/admin`; the public site is served as static HTML from a self-contained nginx container.
## Table of contents
@@ -10,9 +10,8 @@ SoftVowels is a content-driven site for long-form engineering writing. Editors w
- [Repository layout](#repository-layout)
- [Prerequisites](#prerequisites)
- [Quick start (local dev)](#quick-start-local-dev)
- [Production build](#production-build)
- [Docker deployment (homeserver)](#docker-deployment-homeserver)
- [On-demand rebuilds (webhook flow)](#on-demand-rebuilds-webhook-flow)
- [Updating the site after a content change](#updating-the-site-after-a-content-change)
- [Nginx Proxy Manager setup](#nginx-proxy-manager-setup)
- [Customising the design](#customising-the-design)
- [Self-hosting fonts](#self-hosting-fonts)
@@ -25,105 +24,84 @@ SoftVowels is a content-driven site for long-form engineering writing. Editors w
| Layer | Technology |
|---|---|
| Frontend | [Astro 5](https://astro.build/) — `output: 'static'`, Tailwind v4, MDX, sitemap, RSS |
| Backend / CMS | [PayloadCMS 3](https://payloadcms.com/) running on Next.js 15 |
| Backend / CMS | [PayloadCMS 3](https://payloadcms.com/) on Next.js 15 (standalone output) |
| Database | PostgreSQL 16 (one schema, one volume) |
| Static host | nginx 1.27 (one container, serves `apps/web/dist/`) |
| Static host | nginx 1.27 (one container, dist baked into the image) |
| Reverse proxy / TLS | [Nginx Proxy Manager](https://nginxproxymanager.com/) on the homeserver |
| Container runtime | Docker + Docker Compose v2 |
| Language / runtime | Node.js 20+, pnpm 9 |
**The homeserver only needs Docker.** No Node, no pnpm, no git is required on the host at runtime — every image is built from source by the compose stack.
## Repository layout
```
.
├── apps/
│ ├── web/ # Astro 5 frontend (static)
│ ├── web/ # Astro 5 frontend (static)
│ │ ├── src/
│ │ │ ├── components/ # layout, home, article, category, search, newsletter, ui
│ │ │ ├── layouts/ # BaseLayout, ArticleLayout
│ │ │ ├── lib/ # payload client, types, seo, format
│ │ │ ├── pages/ # routes
│ │ │ └── styles/ # global.css (@theme tokens), prose.css
│ │ ├── public/fonts/ # drop Geist*.woff2 here
│ │ ├── Dockerfile # build → dist, copy to nginx
│ │ ├── nginx-default.conf # serves dist/, gzip, /admin → CMS
│ │ │ ├── components/ # layout, home, article, category, search, newsletter, ui
│ │ │ ├── layouts/ # BaseLayout, ArticleLayout
│ │ │ ├── lib/ # payload client, types, seo, format
│ │ │ ├── pages/ # routes
│ │ │ └── styles/ # global.css (@theme tokens), prose.css
│ │ ├── public/fonts/ # drop Geist*.woff2 here
│ │ ├── Dockerfile # pnpm build -> nginx alpine
│ │ ├── nginx-default.conf # serves dist/, gzip
│ │ ├── .dockerignore
│ │ └── astro.config.mjs
│ └── cms/ # PayloadCMS 3 admin
│ └── cms/ # PayloadCMS 3 admin
│ ├── src/
│ │ ├── collections/ # Articles, Authors, Categories, Tags, Editions, Subscribers, Media, Users
│ │ ├── hooks/ # revalidateAstro (afterChange → POST webhook)
│ │ └── app/ # Next.js routes
│ ├── Dockerfile
│ │ ├── collections/ # Articles, Authors, Categories, Tags, Editions, Subscribers, Media, Users
│ │ ├── hooks/ # revalidateAstro (webhook, currently unused)
│ │ ├── lib/ # withRevalidate helper
│ │ └── app/ # Next.js routes
│ ├── Dockerfile # pnpm build -> Next standalone
│ ├── .dockerignore
│ └── payload.config.ts
├── scripts/
│ ├── rebuild.sh # git pull + pnpm --filter web build
│ ├── webhook.js # host-side Node webhook receiver
│ └── softvowels-webhook.service
├── docker-compose.yml # db + cms + web
├── scripts/ # (legacy) host-side webhook + rebuild; not used currently
├── docker-compose.yml # db + cms + web, all in one
├── .env.example
├── AGENTS.md # contributor conventions
└── README.md # ← you are here
├── AGENTS.md # contributor conventions
└── README.md # ← you are here
```
## Prerequisites
- **Node.js 20.11+** (`node --version`)
- **pnpm 9** (`npm i -g pnpm`)
- **Docker 24+** with Compose v2 (`docker compose version`)
- A homeserver (or any Linux box) with **Nginx Proxy Manager** already running
- Two DNS records pointing at the homeserver:
- `softvowels.example` (the public site)
- `cms.softvowels.example` (the admin)
That's it. No Node, no pnpm, no git on the host at runtime.
## Quick start (local dev)
Local dev doesn't need Docker for the apps themselves; only Postgres is required.
Optional — only useful if you want to iterate on the source code on your dev machine. Production deployment is below.
```bash
# 1. Install workspace dependencies
pnpm install
# 2. Copy environment templates
cp .env.example .env
cp apps/web/.env.example apps/web/.env
cp apps/cms/.env.example apps/cms/.env
# 3. Fill in the secrets in .env (at minimum POSTGRES_PASSWORD and PAYLOAD_SECRET)
# 4. Start Postgres in Docker
docker compose up -d db
# 5. Run the two apps
docker compose up -d softvowels-db
pnpm dev:cms # Payload on http://localhost:3000/admin
pnpm dev:web # Astro on http://localhost:4321
```
The Astro dev server fetches articles from `PAYLOAD_API_INTERNAL=http://localhost:3000`. If Payload is empty, every page still renders a graceful empty state.
> First Payload boot will print a one-time URL in the logs to create the first admin user. Open it in your browser.
## Production build
Build both apps as containers:
```bash
pnpm build # builds apps/web (static)
pnpm build:cms # builds apps/cms (Next.js production server)
```
Or build the containers directly:
```bash
docker compose build
```
The static site is emitted to `apps/web/dist/` and is what the `web` nginx container serves.
> First Payload boot prints a one-time URL in the logs to create the first admin user. Open it in your browser.
## Docker deployment (homeserver)
The repo ships a `docker-compose.yml` with three services: `db`, `cms`, and `web`.
The repo ships a `docker-compose.yml` with three services, all on the external `nginx_proxy_manager` network:
### One-time setup on the server
| Service | Image | Port (internal) | Purpose |
|---|---|---|---|
| `softvowels-db` | `postgres:16-alpine` | 5432 | data store |
| `softvowels-cms` | built from `apps/cms/Dockerfile` | 3000 | Payload admin + REST/GraphQL API |
| `softvowels-web` | built from `apps/web/Dockerfile` | 80 | static site served by nginx |
### One-time setup
```bash
# 1. Get the code on the server
@@ -141,18 +119,17 @@ $EDITOR .env
|---|---|
| `POSTGRES_PASSWORD` | Postgres password (used by `db` and `cms`) |
| `PAYLOAD_SECRET` | Long random string, signs Payload sessions |
| `REVALIDATE_TOKEN` | Shared secret for the `/__revalidate` webhook |
| `WEB_HOSTNAME` | e.g. `softvowels.example` |
| `CMS_HOSTNAME` | e.g. `cms.softvowels.example` |
Generate them with:
Generate secrets with:
```bash
openssl rand -hex 32 # for PAYLOAD_SECRET
openssl rand -hex 24 # for REVALIDATE_TOKEN
openssl rand -hex 24 # for POSTGRES_PASSWORD
```
### Drop in self-hosted fonts
### Drop in self-hosted fonts (optional but recommended)
```bash
curl -L -o apps/web/public/fonts/Geist-Variable.woff2 \
@@ -161,84 +138,60 @@ curl -L -o apps/web/public/fonts/GeistMono-Variable.woff2 \
https://github.com/vercel/geist-font/raw/main/fonts/GeistMonoVF.woff2
```
(The `@font-face` rules are already in `apps/web/src/styles/global.css`.)
The `@font-face` rules are already in `apps/web/src/styles/global.css`.
### First boot
```bash
docker compose up -d --build
docker compose logs -f cms # watch the first migration
docker compose logs -f softvowels-cms
```
The first time Payload starts it will print a one-time setup URL in the `cms` logs:
The first time Payload starts it prints a one-time URL for the first admin user. Find it with:
```bash
docker compose logs cms | grep -i "first user"
docker compose logs softvowels-cms | grep -i "first user"
```
Open it in your browser to create the first admin user, then start publishing at `https://cms.softvowels.example/admin`.
Open the URL in your browser to create the first admin user, then visit `https://cms.softvowels.example/admin` for the admin UI.
## On-demand rebuilds (webhook flow)
The static site has to be rebuilt whenever content changes. The flow is:
```
Editor hits Publish in /admin
│
▼
Payload afterChange hook (apps/cms/src/hooks/revalidateAstro.ts)
│ POST http://host.docker.internal:4321/__revalidate?secret=…&collection=…&op=…
▼
scripts/webhook.js (running on the host, not in Docker)
│ spawns scripts/rebuild.sh
▼
scripts/rebuild.sh
│ git pull origin main → pnpm install → pnpm --filter web build
▼
The next browser request gets the fresh dist/ via the web container
```
### Install the webhook on the host
### Wipe everything (clean start)
```bash
sudo cp scripts/softvowels-webhook.service /etc/systemd/system/
sudo systemctl edit --full softvowels-webhook.service
# (set WEBHOOK_PORT, REBUILD_TOKEN, REPO_DIR, LOG_FILE in [Service])
sudo systemctl daemon-reload
sudo systemctl enable --now softvowels-webhook
sudo systemctl status softvowels-webhook
docker compose down -v
docker volume ls -q | grep softvowels | xargs -r docker volume rm
```
The `REBUILD_TOKEN` value here **must match** the one in `.env`. The webhook listens on `127.0.0.1:4321`; Payload reaches it via `host.docker.internal:4321` (already wired in `docker-compose.yml`).
## Updating the site after a content change
Logs land at `/var/log/softvowels-rebuild.log`. Tail with:
Until the on-publish webhook is wired up, the rebuild flow is manual:
```bash
sudo journalctl -u softvowels-webhook -f
tail -f /var/log/softvowels-rebuild.log
cd /opt/softvowels
git pull
docker compose build softvowels-web
docker compose up -d softvowels-web
```
This rebuilds only the static site image and restarts the `softvowels-web` container. The CMS does not need to be rebuilt for content changes — only the web image does.
## Nginx Proxy Manager setup
NPM runs on the host. Add two proxied hosts:
NPM runs on the host. The three softvowels containers are already attached to the `nginx_proxy_manager` external network. Add two proxied hosts:
| Domain | Forward to | Notes |
|---|---|---|
| `softvowels.example` | `web:80` | Force SSL, enable HSTS, HTTP/2, websockets off |
| `cms.softvowels.example` | `cms:3000` | Force SSL, HSTS, websockets on (Payload admin uses them) |
| Domain | Forward to | Scheme | Websockets |
|---|---|---|---|
| `softvowels.example` | `softvowels-web:80` | http | off |
| `cms.softvowels.example` | `softvowels-cms:3000` | http | on (Payload admin uses them) |
Because the `web` and `cms` services are on a private Docker network named `app`, NPM must run on the **same host** (or be given network access — easiest is host networking or adding NPM's container to the `app` network).
Both need: "Force SSL" + HSTS enabled.
If NPM is also in Docker, attach it:
NPM must be able to resolve `softvowels-web` and `softvowels-cms`. The `nginx_proxy_manager` network is `external: true` in `docker-compose.yml`; the easiest way to make NPM see the containers is to run NPM on the **same host** and add the network to its container:
```bash
docker network connect softvowels-app <npm_container_name>
docker network connect nginx_proxy_manager <npm-container-name>
```
### Useful NPM custom locations (optional)
The `web` container already redirects `/admin` to the CMS. If you want NPM to handle that instead, add a `location /admin` redirect in NPM's "Advanced" tab.
## Customising the design
All tokens are declared in `apps/web/src/styles/global.css` inside the `@theme` block. Change once, applies everywhere:
@@ -255,6 +208,12 @@ Article prose styles live in `apps/web/src/styles/prose.css` (`.prose-article`).
The full design brief is in `.opencode/stitch/DESIGN.md` and the original Stitch HTML mockups in `.opencode/stitch/softvowels_*/code.html`.
After changing design tokens, rebuild the web image (it bakes the styles at build time):
```bash
docker compose build softvowels-web && docker compose up -d softvowels-web
```
## Self-hosting fonts
Drop the two variable woff2 files into `apps/web/public/fonts/`:
@@ -264,7 +223,7 @@ Drop the two variable woff2 files into `apps/web/public/fonts/`:
| `Geist-Variable.woff2` | <https://github.com/vercel/geist-font> (rename `GeistVF.woff2`) |
| `GeistMono-Variable.woff2` | same repo (rename `GeistMonoVF.woff2`) |
The `@font-face` rules are already declared in `global.css`. The Material Symbols font is delivered through `@iconify-json/material-symbols` (svg sprites), so no separate font binary is required.
The `@font-face` rules are already declared in `global.css`. The Material Symbols font is delivered through `@iconify-json/material-symbols` (SVG sprites), so no separate font binary is required.
## Content model
@@ -284,52 +243,47 @@ The Astro side renders Lexical richText to HTML using `@payloadcms/richtext-lexi
## Useful commands
```bash
pnpm dev # Astro only
pnpm dev:cms # Payload only
pnpm build # Astro build
pnpm build:cms # Payload build
pnpm typecheck # astro check (zero errors expected)
pnpm format # prettier --write
pnpm format:check # prettier --check
docker compose up -d --build # build and start all services
docker compose down # stop (keeps volumes)
docker compose down -v # stop and wipe volumes
docker compose logs -f web # tail web container
docker compose logs -f cms # tail Payload
sudo journalctl -u softvowels-webhook -f # tail webhook
tail -f /var/log/softvowels-rebuild.log # tail rebuilds
docker compose up -d --build # build and start all services
docker compose down # stop (keeps volumes)
docker compose down -v # stop and wipe volumes
docker compose logs -f softvowels-web # tail web container
docker compose logs -f softvowels-cms # tail Payload
docker compose restart softvowels-web # restart just the web
docker compose build softvowels-web # rebuild just the web image
docker volume ls | grep softvowels # list softvowels volumes
```
## Troubleshooting
**`pnpm install` complains about a broken `pnpm` binary on Windows.** Use `npm` inside each app folder instead:
```bash
cd apps/web && npm install
cd ../cms && npm install
```
`pnpm-workspace.yaml` works with both package managers for development. The homeserver `scripts/rebuild.sh` prefers pnpm if available, falls back to npm.
**`softvowels-cms` keeps restarting with `ERR_PNPM_NO_SCRIPT_OR_SERVER`.** The CMS uses Next.js standalone output (`next.config.ts: output: 'standalone'`). The runtime stage of `apps/cms/Dockerfile` runs `node server.js` directly — make sure the standalone build was actually produced (`docker compose build --no-cache softvowels-cms`).
**`astro build` fails with `Cannot convert undefined or null to object`.** Make sure `tailwindcss` and `@tailwindcss/oxide` are pinned to the **same** version (we use 4.1.13). Mismatched versions cause the scanner to crash on Windows + Node 22.
**`/admin` returns 502.** The CMS container hasn't finished initialising yet. Wait ~30 s after `docker compose up`. The first boot runs Payload's database migrations; subsequent boots are fast.
**`/admin` returns 502.** The CMS container hasn't finished initialising yet. Wait ~30 s after `docker compose up`. The first boot runs Payload's database migrations.
**`/admin` returns 404 from the `web` container.** It should redirect to the CMS. The redirect is configured in `apps/web/nginx-default.conf` (`location /admin`). If you've overridden NPM's locations, set the redirect there instead.
**Webhook returns `401`.** `REBUILD_TOKEN` in `apps/web/.env`, `apps/cms/.env`, `/etc/systemd/system/softvowels-webhook.service`, and `docker-compose.yml` (passed through as `ASTRO_REVALIDATE_TOKEN` to the CMS) must all match.
**Webhook returns `202` but nothing rebuilds.** Check `/var/log/softvowels-rebuild.log`. Common causes: `git pull` failed (auth), `pnpm install` failed (lockfile drift), or the rebuild script exited with an error before `pnpm build` completed.
**Editor in `/admin` can publish but the public site doesn't update.** The `web` container is a plain `nginx:1.27-alpine` that bind-mounts `./apps/web/dist` from the host. The webhook should be rewriting that folder. Verify:
**Editor in `/admin` can publish but the public site doesn't update.** That's expected — the on-publish webhook isn't wired up yet. Run the manual rebuild flow:
```bash
ls -la apps/web/dist/index.html
docker compose exec web ls -la /usr/share/nginx/html/index.html
cd /opt/softwovls
git pull
docker compose build softvowels-web
docker compose up -d softvowels-web
```
If the host file is newer but the container still serves old content, run `docker compose restart web` so nginx re-opens the file handles. (nginx should pick up file changes automatically via inotify, but a restart is the nuclear option.)
**Public site returns 403 directory index forbidden.** The `softvowels-web` image wasn't built, or the build failed silently. Run `docker compose build --no-cache softvowels-web` and look for the `astro build` step output.
**Want to inspect the database.** Connect to it from any other container on the `nginx_proxy_manager` network:
```bash
docker run --rm -it --network nginx_proxy_manager postgres:16-alpine \
psql postgres://payload:$POSTGRES_PASSWORD@softvowels-db:5432/softvowels
```
**`/admin` first-user URL is in the past.** Payload's one-time URL expires. Restart the CMS to get a new one:
```bash
docker compose restart softvowels-cms
docker compose logs softvowels-cms | grep -i "first user"
```
---
Built with Astro 5, PayloadCMS 3, Tailwind v4, and Postgres 16.
Built with Astro 5, PayloadCMS 3, Tailwind v4, and Postgres 16. Runs in Docker.