blog/README.md

# 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 ─┬─ /admin and Strapi's plugin paths → Strapi (CMS) → PostgreSQL
                 └─ everything else                  → Nuxt (website)
```

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.** Every `change-me` must become a different random value —
Strapi refuses to start otherwise. This fills them all:

```bash
for var in POSTGRES_PASSWORD API_TOKEN_SALT ADMIN_JWT_SECRET TRANSFER_TOKEN_SALT JWT_SECRET ENCRYPTION_KEY; do
  sed -i "s|^$var=.*|$var=$(openssl rand -base64 32)|" .env
done
sed -i "s|^APP_KEYS=.*|APP_KEYS=$(openssl rand -base64 32),$(openssl rand -base64 32)|" .env
chmod 600 .env
```

`grep change-me .env` must print nothing. 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 (dev bypasses Caddy,
so the CMS is reached directly on its port). 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.** One `A` record (and `AAAA` if you have IPv6) on the
public IP of the machine:

| Record | Purpose |
|---|---|
| `example.com` | the website and, at `/admin`, the Strapi admin panel |

Wait for the record to resolve before starting the stack — Caddy requests the
certificate 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` |
| `ACME_EMAIL` | a mailbox you read — Let's Encrypt sends expiry warnings there |
| `PUBLIC_SITE_URL` | `https://example.com` |
| `PUBLIC_STRAPI_URL` | `https://example.com` — same origin, Caddy proxies `/admin` and Strapi's other plugin paths there (see `caddy/Caddyfile`) |
| `STRAPI_URL` | leave it as `http://cms:1337` — internal address, never public |

Then generate **fresh** secrets on that machine with the same loop as in development —
different values from the ones you use locally. 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 both the website and, under `/admin` and Strapi's
other plugin paths, the CMS on `PUBLIC_DOMAIN`, obtains and renews the TLS certificate on
its own, and adds HSTS and the other security headers.

**5. Create the administrator account** at `https://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).