golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/setup/installation.md
View File

@@ -1,6 +1,6 @@
---
title: Installation
description: Install the Go toolchain, PostgreSQL and the summer CLI, then build, configure, migrate and serve your first SummerCMS application.
description: Create a SummerCMS application with one command, or install the summer CLI and build, migrate and serve the reference application by hand.
section: setup
order: 20
---
@@ -24,11 +24,69 @@ summer migrate
summer serve
```
## What the script does
Run the one-liner from the directory that should hold both the framework checkout and the application. `bash -s -- demo` passes the application name to the piped script; the name must be lower-case letters and digits, starting with a letter.
1. It checks the prerequisites. Go older than 1.27 or missing, or a missing git, stops the script with an install hint before anything is cloned. A missing Docker or Docker Compose plugin is only a warning, because the application needs them to run its database, not to be created.
2. It clones the framework into `./summercms` and checks out the newest `vX.Y.Z` release tag, detached. When `./summercms` already exists, the script fetches tags and moves the checkout forward to the newest release only when that is a fast-forward. It refuses, without changing anything, a directory that is not a framework checkout, a checkout with changes to tracked files and a checkout that is on a branch.
3. It installs the `summer` CLI from that checkout with `go install ./cmd/summer`. When the Go install directory is not on your `PATH`, the script ends with the `export PATH=...` line to run and to add to your shell profile.
4. It runs `summer new demo` next to the checkout, with `--framework` pointing at it, which writes `sm-demo-app` and prints the next steps. The script itself ends with the `cd` line into the new application.
The script stops before cloning when the name is invalid or `sm-demo-app` already exists. Three environment variables change its defaults:
| Variable | Default | Purpose |
|----------|---------|---------|
| `SUMMERCMS_REPO` | `https://git.golem15.com/golem15/summercms` | Repository to clone. |
| `SUMMERCMS_DIR` | `summercms` in the current directory | Framework checkout; the application is created next to it. |
| `SUMMERCMS_REF` | the newest release tag | Tag or commit to check out instead. |
Set them on the `bash` side of the pipe, for example `curl -fsSL https://summercms.io/new | SUMMERCMS_DIR=fw bash -s -- demo`. The [sunrise](../../modules/sunrise/README.md) module holds the script itself.
## Run the application
The generated application brings its own database and configuration:
- `compose.yaml` runs PostgreSQL 16, published on `127.0.0.1:54320` only, so it does not clash with a PostgreSQL already on port 5432.
- `.env` holds the matching `SUMMER_DATABASE__DSN` and a freshly generated `SUMMER_APP__KEY`. It is excluded by `.gitignore`; `.env.example` lists the same variables.
- `config/` holds `app.yaml`, `database.yaml`, `http.yaml` and `storage.yaml`, enough for `summer serve` and `route:list`.
From `sm-demo-app`, start the database, build the binary, run the migrations and serve:
```sh
docker compose up -d --wait
summer build
summer migrate
summer serve
```
From another terminal, the starter plugin `golem15.demo` answers on the root route:
```sh
curl http://127.0.0.1:8080/
```
It returns `{"message":"Hello from SummerCMS","plugin":"golem15.demo"}`. Stop the database with `docker compose down`, or `docker compose down -v` to delete its data as well.
## Create an application without the script
When you already have a framework checkout, or want to read the code before running anything, do the script's steps yourself. Clone the framework into `summercms`, install the tool from it and run `summer new` in the directory next to the checkout:
```sh
git clone https://git.golem15.com/golem15/summercms
go -C summercms install ./cmd/summer
summer new demo
```
`summer new` finds a sibling `summercms` or `summercms.go` checkout by its module path. For a checkout anywhere else, pass it explicitly with `summer new demo --framework ../path/to/summercms`. [Scaffolding](../console/scaffolding.md) lists every flag and the files `summer new` writes.
The rest of this page is the manual path: it installs the tool and builds `examples/hello`, the small reference application in the framework repository.
## Requirements
- Go 1.27.
- PostgreSQL 15 or newer for any application that uses the data layer.
- Docker, only for the integration tests that start PostgreSQL or Mailpit containers.
- PostgreSQL 15 or newer for any application that uses the data layer. A generated application runs PostgreSQL 16 in Docker.
- Docker, for the database of a generated application and for the integration tests that start PostgreSQL or Mailpit containers.
You do not need Node.js to build an application or these docs. It is needed only when you work on the admin SPA itself.
@@ -47,7 +105,7 @@ summer --help
export PATH="$(go env GOPATH)/bin:$PATH"
```
The tool builds and watches applications, scaffolds plugins, models, migrations and admin controllers, and builds this documentation. Check that the framework compiles and its unit tests pass:
The tool creates, builds and watches applications, scaffolds plugins, models, migrations and admin controllers, and builds this documentation. Check that the framework compiles and its unit tests pass:
```sh
go vet ./...
@@ -127,13 +185,9 @@ curl http://127.0.0.1:8080/items/1
From the application directory, `summer migrate`, `summer migrate:status` and `summer serve` run the same commands through the built binary, building it first when it is missing.
> [!WARNING]
> Known issues in the current framework:
>
> - The committed `examples/hello/main.go` is older than what `summer build` generates now, so building the example leaves that file modified. Restore it with `git checkout -- examples/hello/main.go` if you do not intend to commit it.
## Next steps
- Read [Coming from WinterCMS](coming-from-wintercms.md) if you are porting a WinterCMS plugin.
- Read the [Architecture introduction](../architecture/introduction.md) to see how the pieces fit.
- Read [Go modules and workspaces](../architecture/go-modules-and-workspaces.md) for what `summer new` writes into `go.mod` and `go.work`.
- Scaffold your own plugin with `summer make:plugin` as described in [Plugin registration](../plugins/registration.md).