summercms/modules/sunrise/README.md

sunrise

Bootstrap script that installs the summer CLI and creates a new SummerCMS application, or updates an existing one, in one command, embedded so it is versioned with the framework.

import "git.golem15.com/golem15/summercms/modules/sunrise"

Overview

sunrise holds new.sh, the script behind the one-liner served at https://summercms.io/new:

curl -fsSL https://summercms.io/new | bash -s -- blog

The script checks for Go 1.27 or newer, git and Docker, clones the framework into ./summercms at its newest release tag (or moves an existing release checkout forward to it), installs the summer CLI with go install ./cmd/summer and runs summer new blog --framework <checkout> next to the checkout, which writes ./sm-blog-app. summer new prints the next steps; the script adds the cd line and, when the Go install directory is not on PATH, a hint for the login shell named by SHELL: fish_add_path <dir> for fish (which keeps it for new sessions), an export PATH=... line naming ~/.zshrc or ~/.bashrc for zsh and bash, and the generic export PATH=... line with "your shell profile" for any other shell.

The same script updates an existing application. Run inside the application directory, served at https://summercms.io/update:

cd sm-blog-app && curl -fsSL https://summercms.io/update | bash

curl -fsSL https://summercms.io/new | bash -s -- --update does the same. Update mode needs a go.mod and a summer.yaml in the current directory and reads the framework checkout from the go.mod replace of the framework module, as summer new writes it; a replace with a module version instead of a local path is refused. A detached checkout is fetched and moved fast-forward only to the newest release tag (or SUMMERCMS_REF); a branch checkout with an upstream is pulled with git pull --ff-only. A checkout with changes to tracked files, a branch without an upstream and a branch that has diverged stop the script with the checkout unchanged, and nothing is installed or built. Other sm-*-app directories next to the application or next to the checkout whose replace points at the same checkout are named on one not rebuilt line and left untouched. The script then reinstalls summer, appends a SUMMER_ADMIN__JWT__SECRET line to this application's .env when no active line sets it (once, keeping the file mode, never printing the value), runs summer build in the application and ends with a reminder to run summer migrate and restart summer serve, followed by the same PATH hint.

The script lives inside this package so //go:embed can reach it, and a web server serves the bytes of the framework release it was built against. sunrise.Script returns them; sunrise.UpdateScript returns the same script with update mode preset, for the update URL.

Features

• Truncation-safe: everything is a function definition and the last line is main "$@" (main "$@" --update in sunrise.UpdateScript), so a download cut short runs nothing.
• Prerequisites first: 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 compose plugin is only a warning.
• Release tags: a fresh clone is checked out detached at the newest vX.Y.Z tag, or at SUMMERCMS_REF when set.
• Fast-forward-only updates: an existing checkout is fetched (tags are never force-updated) and moved only when its HEAD is an ancestor of the target.
• Refusals that protect local work: an existing directory that is not a git repository, whose go.mod is not the framework module, that has changes to tracked files, or that is on a branch is left untouched and the script stops with a message.
• Early name check: a name that is not lower-case letters and digits starting with a letter, or an existing sm-<name>-app, stops the script before any clone or install.
• Login-shell-aware PATH hint: the closing hint is one correct line for fish, zsh or bash, with a generic export PATH=... line for any other shell; the directory is escaped for the target shell's double quotes and $PATH is printed literally.
• Update mode: run inside one application, it moves the framework checkout named by the application's go.mod replace forward, fast-forward only (detached release checkouts to the newest release, branch checkouts with git pull --ff-only), reinstalls summer and runs summer build in that application only.
• Shared-checkout notice: other applications whose go.mod replace resolves to the same checkout are named on one line and never built or written.
• Admin token secret: update mode appends a missing SUMMER_ADMIN__JWT__SECRET to the application's .env, 32 random bytes as base64, without printing it; an existing line, even an empty one, is left alone.
• No privilege escalation and no dynamic code; only bash builtins plus git, go and docker are run (update mode also runs openssl, or head and base64, and the installed summer), with stdin closed and GIT_TERMINAL_PROMPT=0 so nothing waits for input.

Usage

Run the script from the directory that should hold the framework checkout and the application:

curl -fsSL https://summercms.io/new | bash -s -- blog

bash -s -- <name> passes the application name to the piped script; -h or --help prints the usage. A local copy runs the same way with bash new.sh blog.

Update an existing application from inside its directory:

cd sm-blog-app
curl -fsSL https://summercms.io/update | bash

Update mode takes no other argument. It works the same from bash, zsh and fish, because the piped script always runs in bash.

Serving the script from a Go handler:

package acme

import (
	"net/http"

	"git.golem15.com/golem15/summercms/modules/sunrise"
)

func newScript(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.Header().Set("X-Content-Type-Options", "nosniff")
	_, _ = w.Write(sunrise.Script())
}

A second handler serves sunrise.UpdateScript() the same way at the update path.

API reference

Identifier	Description
sunrise.Script	Returns a fresh copy of the embedded new.sh bytes on every call.
sunrise.UpdateScript	Returns a fresh copy of the script with its last line main "$@" replaced by main "$@" --update, so it runs update mode.

Configuration

The script reads three environment variables, plus SHELL, which only picks the form of the PATH hint. It never reads or exports SUMMER_-prefixed variables, which the framework reads as configuration. The only such name it writes is SUMMER_ADMIN__JWT__SECRET, which update mode appends to the application's .env.

Variable	Default	Purpose
SUMMERCMS_REPO	https://git.golem15.com/golem15/summercms	Repository to clone; used only when cloning.
SUMMERCMS_DIR	summercms (relative to the current directory)	Framework checkout directory; the application is created next to it. Update mode ignores it with a warning, because the checkout comes from go.mod.
SUMMERCMS_REF	newest vX.Y.Z tag	Tag or commit to check out instead of the newest release. It applies to detached checkouts; update mode ignores it, with a warning, on a branch.

Dependencies

• SummerCMS modules: none.
• Third-party: none.
• Standard library: bytes, embed.

Testing

go test ./modules/sunrise/...

The default run checks the embedded bytes, the script's shape and syntax (bash -n), that sunrise.UpdateScript differs from it only in the last line, and runs every line-boundary prefix and every byte prefix of the final line of both scripts against stub commands to prove a truncated download invokes nothing. A behaviour harness runs the script against a local framework repository and stub go, docker, summer and openssl commands, covering create mode and update mode: detached and branch checkouts and their refusals, the shared-checkout notice, the .env admin secret and the PATH hint.

SUMMERCMS_BOOTSTRAP_CHECK=1 go test ./modules/sunrise/ -run TestBootstrapEndToEnd -timeout 20m

The gated run serves the script from a local HTTP server, pipes it through curl | bash with SUMMERCMS_REPO set to this repository and SUMMERCMS_REF to its HEAD, and builds the generated application. It then removes the admin token secret from the application's .env and updates the application through the update script, which must restore the secret without printing it and rebuild. It needs bash, curl, git, Go and access to the Go module proxy.