129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# SoftVowels — project conventions
|
|
|
|
A monorepo with two apps:
|
|
|
|
```
|
|
apps/web Astro 5 (static site, Tailwind v4)
|
|
apps/cms Payload 3 (admin UI + REST/GraphQL, Next.js 15)
|
|
```
|
|
|
|
## Source paths
|
|
|
|
- `apps/web/src/components/{layout,home,article,category,search,newsletter,ui}/` — components
|
|
- `apps/web/src/layouts/` — page layouts
|
|
- `apps/web/src/lib/` — Payload client, types, SEO, formatting
|
|
- `apps/web/src/styles/` — `global.css` (Tailwind v4 `@theme` tokens) and `prose.css`
|
|
- `apps/web/public/fonts/` — drop `Geist-Variable.woff2` + `GeistMono-Variable.woff2` here
|
|
- `apps/cms/src/collections/` — Payload collections
|
|
- `apps/cms/src/hooks/` — Payload hooks
|
|
- `apps/cms/src/lib/` — Payload helpers (e.g. `withRevalidate`)
|
|
|
|
## Code style
|
|
|
|
- All component files are `.astro` single-file components. Frontmatter (between `---`) is TypeScript.
|
|
- No comments in code unless explicitly requested.
|
|
- Tailwind v4 tokens live in CSS (`@theme` in `global.css`). Do not create a `tailwind.config.*` file.
|
|
- Use `icon` (`astro-icon`) with names like `material-symbols:memory`. Self-host icon font woff2 under `public/icons/material-symbols-outlined.woff2` and wire it via `@font-face` in `global.css` (already declared; add the binary file when ready).
|
|
- Prefer `border border-border-subtle rounded-md` over arbitrary values to stay on the 4px baseline.
|
|
- For code blocks in MDX / Lexical output, the article body uses `prose-article` (see `prose.css`).
|
|
|
|
## Lint / typecheck (web app)
|
|
|
|
```bash
|
|
cd apps/web
|
|
npx astro check
|
|
npx prettier --check "src/**/*.{ts,astro,css}"
|
|
```
|
|
|
|
There is no separate ESLint run; the project's quality bar is enforced by `astro check` and Prettier.
|
|
|
|
## Local development (optional, not required for homeserver deploy)
|
|
|
|
If you have Node + pnpm on your dev machine:
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev:web # Astro on :4321
|
|
pnpm dev:cms # Payload on :3000
|
|
```
|
|
|
|
The homeserver deploy does **not** require Node or pnpm on the host — Docker builds both images from source.
|
|
|
|
## Build outputs
|
|
|
|
- `apps/web/dist/` is generated by `astro build` inside the `softvowels-web` Docker image. Baked into the image at `/usr/share/nginx/html/`.
|
|
- `apps/cms/.next/standalone/` is generated by `next build` (with `output: 'standalone'`) inside the `softvowels-cms` Docker image. Baked into the image and run via `node server.js`.
|
|
- `apps/cms/media/` (uploaded files) lives in a named Docker volume (`softvowels-cms-uploads`), not the image.
|
|
|
|
## Deploy (homeserver, Docker only)
|
|
|
|
The host needs Docker and Docker Compose v2. Nothing else.
|
|
|
|
```bash
|
|
# 1. Get the code on the server
|
|
git clone <repo> /opt/softvowels
|
|
cd /opt/softvowels
|
|
|
|
# 2. Configure environment
|
|
cp .env.example .env
|
|
$EDITOR .env # fill in POSTGRES_PASSWORD, PAYLOAD_SECRET, hostnames
|
|
|
|
# 3. Build and start
|
|
docker compose up -d --build
|
|
|
|
# 4. Watch the first boot
|
|
docker compose logs -f softvowels-cms
|
|
# On first run, Payload prints a one-time URL for creating the admin
|
|
# account. Open it, then visit https://cms.softvowels.example/admin.
|
|
```
|
|
|
|
### Updating the site (no webhook yet)
|
|
|
|
Until the webhook is in place, each site update requires:
|
|
|
|
```bash
|
|
cd /opt/softvowels
|
|
git pull
|
|
docker compose build softvowels-web
|
|
docker compose up -d softvowels-web
|
|
```
|
|
|
|
That's the entire "redeploy" for a content change. The CMS does not need rebuilding for content changes — only the web image.
|
|
|
|
## Nginx Proxy Manager setup
|
|
|
|
Add two proxied hosts in NPM:
|
|
|
|
| Domain | Forward to | Notes |
|
|
|---|---|---|
|
|
| `softvowels.example` | `softvowels-web:80` (http) | Force SSL, HSTS, HTTP/2, websockets off |
|
|
| `cms.softvowels.example` | `softvowels-cms:3000` (http) | Force SSL, HSTS, websockets on (Payload admin uses them) |
|
|
|
|
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 with:
|
|
|
|
```bash
|
|
docker network connect nginx_proxy_manager <npm-container-name>
|
|
```
|
|
|
|
## Self-hosting fonts
|
|
|
|
Drop these two files into `apps/web/public/fonts/` (before `docker compose build`):
|
|
|
|
- `Geist-Variable.woff2` (https://github.com/vercel/geist-font — rename `GeistVF.woff2`)
|
|
- `GeistMono-Variable.woff2` (rename `GeistMonoVF.woff2`)
|
|
|
|
The `@font-face` rules are already declared in `global.css`.
|
|
|
|
## Environment
|
|
|
|
Root `.env` (used by `docker compose`):
|
|
|
|
```
|
|
POSTGRES_PASSWORD=
|
|
PAYLOAD_SECRET=
|
|
WEB_HOSTNAME= # e.g. softvowels.example
|
|
CMS_HOSTNAME= # e.g. cms.softvowels.example
|
|
```
|
|
|
|
`REVALIDATE_TOKEN` was removed when the webhook was deferred. Re-add it to `.env` and `docker-compose.yml` when the on-publish rebuild is wired back in.
|