davide
c9ee871c44
README gets step-by-step instructions for both: secrets generation and the local stack on one side, DNS records, firewall, environment variables, TLS and backups on the other. CLAUDE.md records the decisions that are not visible in the code: why the browser never reaches Strapi, why the content model stays this small, and where the public permissions are granted.
135 lines
5.2 KiB
Markdown
135 lines
5.2 KiB
Markdown
# Blog
|
|
|
|
Blog platform: a public website built with Nuxt, and a private Strapi CMS where the
|
|
articles are written. Everything runs behind Caddy via Docker Compose.
|
|
|
|
```text
|
|
Browser → Caddy ─┬─ public domain → Nuxt (website)
|
|
└─ cms subdomain → Strapi (CMS) → PostgreSQL
|
|
```
|
|
|
|
There are no front-end accounts: sign-up is disabled and only administrators write
|
|
content. An article is a title, a Markdown body, a cover image and a category.
|
|
|
|
## Development
|
|
|
|
No domain and no TLS needed — the services are published on localhost instead of going
|
|
through Caddy. Requires Docker.
|
|
|
|
**1. Create the environment file**
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
**2. Generate the secrets** and paste them into `.env`. Strapi refuses to start with the
|
|
placeholder values.
|
|
|
|
```bash
|
|
openssl rand -base64 32 # run once per secret
|
|
```
|
|
|
|
Fill in `POSTGRES_PASSWORD`, both values of `APP_KEYS`, `API_TOKEN_SALT`,
|
|
`ADMIN_JWT_SECRET`, `TRANSFER_TOKEN_SALT`, `JWT_SECRET` and `ENCRYPTION_KEY`. The domain
|
|
and URL variables can stay as they are for local use.
|
|
|
|
**3. Start the stack**
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build database cms frontend
|
|
```
|
|
|
|
The first build takes a few minutes. `docker-compose.dev.yml` publishes the ports on
|
|
`127.0.0.1` and leaves Caddy out; it must always be passed explicitly, so it can never be
|
|
picked up by accident in production.
|
|
|
|
**4. Create the administrator account** at http://localhost:1337/admin. This is the first
|
|
run, so the form creates the account — pick your own credentials.
|
|
|
|
**5. Write something.** In the admin panel: create a **Category**, then an **Article**
|
|
(the body field is Markdown), then press **Publish** — the website only shows published
|
|
content.
|
|
|
|
**6. Open the website** at http://localhost:3000 — home, `/blog`, `/blog/<slug>` and
|
|
`/category/<slug>`.
|
|
|
|
Useful commands:
|
|
|
|
```bash
|
|
docker compose logs -f cms # follow the CMS logs
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml restart frontend
|
|
docker compose down # stop, keep the data
|
|
docker compose down -v # stop and WIPE the database and media
|
|
```
|
|
|
|
To iterate on the code without rebuilding an image every time, run a package directly —
|
|
`cd frontend && npm run dev`, or `cd cms && npm run develop`. The frontend defaults to
|
|
`http://localhost:1337` for Strapi, so it works against the containerised CMS as is;
|
|
override it with `NUXT_STRAPI_URL` if needed. Strapi reads its own `cms/.env`.
|
|
|
|
## Production
|
|
|
|
**1. Point the DNS at the server.** Two `A` records (and `AAAA` if you have IPv6) on the
|
|
public IP of the machine:
|
|
|
|
| Record | Purpose |
|
|
|---|---|
|
|
| `example.com` | the website |
|
|
| `cms.example.com` | the Strapi admin panel |
|
|
|
|
Wait for the records to resolve before starting the stack — Caddy requests the
|
|
certificates on the first boot and a failed challenge means a retry delay.
|
|
|
|
**2. Open the firewall** for ports `80` and `443` only. Port `80` is required: Caddy uses
|
|
it for the ACME challenge and to redirect to HTTPS. PostgreSQL, Strapi and Nuxt are only
|
|
reachable inside the Docker network — do not publish their ports.
|
|
|
|
**3. Configure the environment.** Copy `.env.example` to `.env` on the server and set:
|
|
|
|
| Variable | Value |
|
|
|---|---|
|
|
| `PUBLIC_DOMAIN` | `example.com` |
|
|
| `CMS_DOMAIN` | `cms.example.com` |
|
|
| `ACME_EMAIL` | a mailbox you read — Let's Encrypt sends expiry warnings there |
|
|
| `PUBLIC_SITE_URL` | `https://example.com` |
|
|
| `PUBLIC_STRAPI_URL` | `https://cms.example.com` |
|
|
| `STRAPI_URL` | leave it as `http://cms:1337` — internal address, never public |
|
|
|
|
Then generate **fresh** secrets for that machine (`openssl rand -base64 32`), different
|
|
from the development ones. Keep `.env` out of version control; it is already ignored.
|
|
|
|
> Changing `APP_KEYS`, `ADMIN_JWT_SECRET` or `JWT_SECRET` later logs everyone out.
|
|
> Changing `ENCRYPTION_KEY` after content exists makes already-encrypted values
|
|
> unreadable. Set them once, then back up the file somewhere safe.
|
|
|
|
**4. Start everything**
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
This time Caddy is included: it serves the website on `PUBLIC_DOMAIN`, the CMS on
|
|
`CMS_DOMAIN`, obtains and renews the TLS certificates on its own, and adds HSTS and the
|
|
other security headers.
|
|
|
|
**5. Create the administrator account** at `https://cms.example.com/admin`, immediately,
|
|
before anyone else finds the URL — the first visitor to that form is the one who gets the
|
|
account. Then publish as in development.
|
|
|
|
**6. Back up what is not in git**: the `postgres-data` volume (all content) and the
|
|
`cms-uploads` volume (all images). Nothing else on the server holds state.
|
|
|
|
```bash
|
|
docker compose exec -T database pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > backup.sql
|
|
docker run --rm -v blog_cms-uploads:/data -v "$PWD:/out" alpine tar czf /out/uploads.tar.gz -C /data .
|
|
```
|
|
|
|
**Updating a running site**: pull the new code, then `docker compose up -d --build`.
|
|
Strapi applies its own schema changes at startup; take a backup first.
|
|
|
|
Architecture, conventions and constraints are documented in [CLAUDE.md](CLAUDE.md).
|
|
|
|
## License
|
|
|
|
Proprietary — Copyright (c) 2026 Davide Grilli. All rights reserved. See [LICENSE](LICENSE).
|