f70d80ec7e
- NewOptions.AdminSecret: summer new writes SUMMER_ADMIN__JWT__SECRET to .env (still 0600), generated from 32 crypto/rand bytes when empty and validated as at least 32 .env-safe characters - .env.example gets an empty SUMMER_ADMIN__JWT__SECRET= placeholder with a comment; the secret never reaches the printed next steps - The next steps and the generated CLAUDE.md explain the admin at /backend: make:admin-controller, build, migrate and summer admin:create --email you@example.com --superuser - Goldens use a fixed, non-secret admin secret fixture - Scaffolding, installation and users-and-permissions docs updated
57 lines
3.5 KiB
Plaintext
57 lines
3.5 KiB
Plaintext
# CLAUDE.md
|
|
|
|
Guidance for AI coding agents working in this repository. `AGENTS.md` is a symlink to this file.
|
|
|
|
## What this is
|
|
|
|
`sm-demo-app` is a SummerCMS application: a Go program built on the SummerCMS framework, module `git.golem15.com/golem15/summercms`. `go.mod` replaces the framework with the local checkout at `../summercms`. That checkout is shared with every other application next to it: do not edit the framework from here. Change this application, or report the framework problem.
|
|
|
|
Framework documentation for agents:
|
|
|
|
- https://summercms.io/docs/llms.txt (index)
|
|
- https://summercms.io/docs/llms-full.txt (full text in one file)
|
|
|
|
## Commands
|
|
|
|
Run them from this directory.
|
|
|
|
```sh
|
|
docker compose up -d --wait # start PostgreSQL 16 on 127.0.0.1:54320
|
|
summer build # generate main.go and plugins.gen.go, build bin/demo
|
|
summer dev # watch sources and rebuild
|
|
summer migrate # run plugin migrations
|
|
summer serve # start the HTTP server
|
|
summer make:plugin golem15.<name> # scaffold a plugin module under plugins/<name>
|
|
summer plugin:add plugins/<name> # register it in summer.yaml, go.mod and go.work
|
|
summer make:admin-controller golem15.<plugin> <Name> # scaffold an admin controller with its YAML
|
|
summer admin:create --email you@example.com --superuser # create a backend administrator (password prompted)
|
|
```
|
|
|
|
## Layout
|
|
|
|
- `summer.yaml`: the application manifest (module path, binary name, ordered plugin list).
|
|
- `plugins/`: local plugin modules. `plugins/demo` is the starter plugin `golem15.demo`; its `routes.go` answers `GET /` with JSON.
|
|
- `config/`: YAML configuration (`app.yaml`, `database.yaml`, `http.yaml`, `storage.yaml`). Any key can be overridden with a `SUMMER_` environment variable, a double underscore separating path segments (`SUMMER_DATABASE__DSN` sets `database.dsn`).
|
|
- `.env`: local secrets (database DSN, application key, admin token secret). Never commit it; `.gitignore` excludes it. `.env.example` lists the variables.
|
|
- `compose.yaml`: the local PostgreSQL 16.
|
|
- `main.go`, `plugins.gen.go`: generated by `summer build` from `summer.yaml`. Do not edit them by hand; they are committed.
|
|
- `go.work`: the workspace that joins the application and its plugin modules.
|
|
|
|
Plugins are Go modules compiled into the binary at build time; there is no runtime plugin loading. Add a plugin with `summer make:plugin` and `summer plugin:add`, then run `summer build`.
|
|
|
|
## Admin
|
|
|
|
The backend admin (the admin SPA and its JSON API) lives under `/backend`, at `http://127.0.0.1:8080/backend` with the default `summer serve` address. It is mounted only when a plugin registers an admin controller; until then `summer serve` prints `admin: off`. To add it:
|
|
|
|
1. `summer make:admin-controller golem15.<plugin> <Name>` scaffolds the controller and its YAML. The generated controller requires the permission `golem15.<plugin>.access_<name>` (`<name>` is the controller name in snake case): declare it in the plugin's `Permissions()` (`pact.HasPermissions`) or the admin refuses to start. Its `NewRecord` returns `nil` until you return the plugin's model.
|
|
2. `summer build`, then `summer migrate`.
|
|
3. `summer admin:create --email you@example.com --superuser` creates the first administrator; the password is prompted.
|
|
|
|
`.env` already holds `SUMMER_ADMIN__JWT__SECRET`, which signs admin tokens.
|
|
|
|
## Naming convention
|
|
|
|
- `sm-<name>-app`: an application, like this repository.
|
|
- `sm-<name>-plugin`: a standalone plugin module.
|
|
- `sm-<name>-theme`: a Nuxt/Vue frontend.
|