docs(14.3-03): document summer new and the one-command start

- installation: one-liner first, what the script does and its overrides,
  running the generated app, summer new without the script, then the
  examples/hello walkthrough; the obsolete known-issues callout is gone (D-18)
- go modules and workspaces: what summer new writes (relative replace,
  framework detection order, committed relative go.work, no root go.sum);
  plugin:add adds a relative go.work path
- console scaffolding: Creating an application with --framework, --no-plugin,
  --no-git, the files written, first commit and naming convention (D-01)
- console introduction, llms note in site.yaml, root README quick start
This commit is contained in:
Jakub Zych
2026-10-08 12:08:35 +02:00
parent 90582522c7
commit e0640220f2
6 changed files with 178 additions and 22 deletions

View File

@@ -7,17 +7,39 @@ SummerCMS is a content management framework for Go, inspired by WinterCMS. An ap
- **Compiled plugins.** A plugin is a Go module that implements the capability interfaces in [pact](modules/pact/README.md). The `summer build` command reads the application's `summer.yaml` manifest, generates the plugin import list and builds the binary. Plugins are registered at build time and never loaded at runtime. [party](modules/party/README.md) orders them by dependency and runs their register and boot lifecycle.
- **YAML-driven admin.** Plugins describe admin lists, forms, filters and relations in WinterCMS-style YAML (`columns.yaml`, `fields.yaml`). [cabana](modules/cabana/README.md) compiles those definitions at boot and serves them as a JSON admin API, and [boardwalk](modules/boardwalk/README.md) serves the embedded Vue admin SPA that renders them.
- **Headless API.** Plugins declare HTTP routes and middleware. [surf](modules/surf/README.md) assembles them onto a standard library `net/http` ServeMux, and [wire](modules/wire/README.md) keeps JSON responses byte-compatible with a PHP (WinterCMS/Laravel) backend.
- **Scaffolding CLI.** The `summer` tool builds and watches applications and scaffolds plugins, models, migrations, console commands, jobs and admin controllers. Every application binary also carries runtime commands such as `migrate`, `serve` and `route:list`.
- **Scaffolding CLI.** The `summer` tool creates, builds and watches applications and scaffolds plugins, models, migrations, console commands, jobs and admin controllers. Every application binary also carries runtime commands such as `migrate`, `serve` and `route:list`.
## Requirements
- Go 1.27.
- PostgreSQL 15 or newer for any application that uses the data layer ([lagoon](modules/lagoon/README.md)).
- Node.js 22.6 or newer, only when working on the admin SPA in `admin/`.
- Docker, only for the integration tests that start PostgreSQL or Mailpit containers through testcontainers-go.
- Docker, to run the PostgreSQL 16 database of an application created by `summer new` (its `compose.yaml`), and for the integration tests that start PostgreSQL or Mailpit containers through testcontainers-go.
## Quick start
Create an application with one command. The script checks for Go 1.27 and Docker, clones the framework at its latest release tag into `./summercms`, installs the `summer` CLI and runs `summer new demo`:
```sh
curl -fsSL https://summercms.io/new | bash -s -- demo
cd sm-demo-app
docker compose up -d --wait # PostgreSQL 16 on 127.0.0.1:54320
summer build
summer migrate
summer serve # then: curl http://127.0.0.1:8080/
```
The [sunrise](modules/sunrise/README.md) module holds the script and documents its `SUMMERCMS_REPO`, `SUMMERCMS_DIR` and `SUMMERCMS_REF` overrides.
With a framework checkout already in place, install the CLI from it and run `summer new` in the directory next to the checkout; it finds a sibling `summercms` or `summercms.go` checkout, or takes `--framework <path>`:
```sh
go -C summercms install ./cmd/summer
summer new demo
```
### The example application
`examples/hello` is a small application with three compiled plugins. Install the `summer` CLI from the repository root, then build the example:
```sh
@@ -53,10 +75,6 @@ The `migrate`, `migrate:status`, `migrate:rollback`, `serve` and admin commands
`summer migrate`, `summer migrate:status`, `summer migrate:rollback` and `summer serve`, run from the application directory, delegate to the built binary in `bin/`.
### Known issues
- The committed `examples/hello/main.go` is older than what `summer build` generates now, so building the example (or running its tests, which build it) leaves that file modified. Restore it with `git checkout -- examples/hello/main.go` if you do not intend to commit it.
## Repository layout
| Path | Contents |
@@ -100,7 +118,7 @@ The `migrate`, `migrate:status`, `migrate:rollback`, `serve` and admin commands
## Using SummerCMS in an application
The framework is a single Go module, `git.golem15.com/golem15/summercms`; each framework package is imported from `git.golem15.com/golem15/summercms/modules/<name>`. An application requires that module and, during development, points it at a local checkout with a `replace` directive. For an application module `acme` in a sibling directory:
The framework is a single Go module, `git.golem15.com/golem15/summercms`; each framework package is imported from `git.golem15.com/golem15/summercms/modules/<name>`. An application requires that module and, during development, points it at a local checkout with a `replace` directive. `summer new` writes this `go.mod` for you, with a relative `replace` to the framework checkout and a committed `go.work` (see [Go modules and workspaces](docs/architecture/go-modules-and-workspaces.md)). Written by hand, for an application module `acme` in a sibling directory:
```
module git.golem15.com/acme/acme