genesis-stack 1.2.1 → 1.3.1

package/stacks/pieces/spring-boot-postgresql.md

@@ -0,0 +1,68 @@
+# Stack piece: spring-boot-postgresql
+
+## Description
+
+Spring Boot PostgreSQL datasource, JDBC driver, Flyway, JPA, and database
+environment conventions.
+
+## Requires
+
+- `spring-boot`
+- `postgresql`
+
+## Conflicts
+
+- `spring-boot-mysql`
+
+## Environment defaults
+
+- Default `DB_HOST`: `127.0.0.1`
+- Default `DB_PORT`: `5432`
+- Default `DB_NAME`: `spring`
+- Default `DB_USERNAME`: `postgres`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USERNAME"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    }
+  ],
+  "optionalBindings": {
+    "testDatabase": "TEST_DB_NAME"
+  }
+}
+```
+
+## Guidance
+
+- Compose the JDBC URL from the individual names in `application.properties`:
+  `spring.datasource.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}`,
+  `spring.datasource.username=${DB_USERNAME}` and
+  `spring.datasource.password=${DB_PASSWORD:}`. A `postgres://` connection URL
+  is not a JDBC URL; do not feed one to `spring.datasource.url`.
+- Use the `org.postgresql:postgresql` runtime driver. Flyway 10 and later also
+  need `org.flywaydb:flyway-database-postgresql` next to the Flyway starter.
+- When `TEST_DB_NAME` is supplied, the `test` profile's
+  `src/test/resources/application-test.properties` sets
+  `spring.datasource.url` to the same JDBC URL with `${TEST_DB_NAME}` in place
+  of `${DB_NAME}`. Flyway migrates that existing database; the database role
+  may lack permission to create databases. Never point tests at `DB_NAME`.
+
+## Adoption
+
+- Confirm the datasource properties, the environment names they read, the
+  driver and Flyway or Liquibase modules, and every profile's overrides from
+  source before declaring readiness or connecting to the database.

package/stacks/pieces/spring-boot.md

@@ -0,0 +1,148 @@
+# Stack piece: spring-boot
+
+## Description
+
+Spring Boot web application, Spring MVC, Spring Security, Actuator, profiles,
+Maven or Gradle wrapper, and schema-migration conventions. Identified by a
+`pom.xml` or `build.gradle(.kts)` using the Spring Boot parent or plugin and an
+`@SpringBootApplication` class. Authoritative framework documentation:
+https://docs.spring.io/spring-boot/
+
+## Requires
+
+- `java`
+
+## Guidance
+
+- Use the Spring Boot version selected by the build and follow its matching
+  official documentation. Boot 4 splits auto-configuration into per-technology
+  starters (`spring-boot-starter-webmvc`, `spring-boot-starter-flyway`, ...):
+  a bare `flyway-core` dependency no longer runs migrations, so add the
+  matching starter instead of hand-written configuration. Preserve Spring's
+  dependency injection, configuration properties, Spring Data repositories,
+  Spring Security and Actuator instead of adding parallel plumbing.
+- Building and running need a full JDK (`javac`), not only a Java runtime.
+  Keep the Maven wrapper (`mvnw`, `.mvn/wrapper`) committed and executable;
+  the proposed operations call `./mvnw`.
+- Bind the listen address and port from the environment in
+  `application.properties`: `server.address=${HOST:127.0.0.1}` and
+  `server.port=${PORT:8080}`. Spring reads `SERVER_PORT`, not `PORT`, by
+  itself. The proposed development run also passes both as
+  `--server.address`/`--server.port` application arguments.
+- Behind a development or production reverse proxy on the same machine that
+  rewrites `Host` and sends `X-Forwarded-Host`, `X-Forwarded-Proto` and
+  `X-Forwarded-Port`, set `server.forward-headers-strategy=native`,
+  `server.tomcat.remoteip.host-header=X-Forwarded-Host` and
+  `server.tomcat.remoteip.port-header=X-Forwarded-Port`. Embedded Tomcat then
+  trusts those headers only from loopback and private internal proxies, so
+  login redirects, `ServletUriComponentsBuilder` URLs and the `Secure` session
+  cookie use the browser-facing origin. Without it, Spring Security redirects
+  to the loopback address. Use `framework` only for a non-Tomcat server, and
+  only while the server is reachable solely through that proxy.
+- Also set `server.tomcat.use-relative-redirects=true`. A proxy may send a
+  same-origin form post with the forwarded host and port removed and `Origin`
+  rewritten to the loopback address, so Tomcat would turn the redirect after
+  login or after any POST into `https://127.0.0.1/...`; a relative `Location`
+  lets the browser resolve it against its own origin.
+- Spring Security's CSRF protection is token based (`_csrf`) and works behind
+  such a proxy. A proxy may present same-origin requests with an `Origin`
+  rewritten to the loopback address; keep CORS configuration for genuine
+  cross-origin clients rather than comparing `Origin` with the request host.
+- Add `spring-boot-starter-actuator`, expose
+  `management.endpoints.web.exposure.include=health`, and let Spring Security
+  `permitAll` `/actuator/health`; the proposed readiness checks use it. Its
+  status includes the datasource, so readiness also proves the database
+  connection. An application that must not expose Actuator replaces both
+  readiness lines with another unauthenticated route.
+- Select profiles with `SPRING_PROFILES_ACTIVE` set separately in each
+  environment (for example `dev` locally); never make a development profile
+  the project-wide default, because defaults also reach deployment. Keep
+  profile-specific values in `application-<profile>.properties`.
+- Read credentials from the environment through property placeholders; never
+  commit passwords or tokens in `application*.properties`. Spring Boot has no
+  framework secret key of its own; application secrets, such as a token
+  signing key, are generated with `openssl rand -base64 32` and supplied
+  through the environment.
+- Flyway or Liquibase owns the schema and runs at application startup, so the
+  proposed deployment has no separate migration step. Add new migrations;
+  never edit an applied one (its checksum is validated). Use
+  `spring.jpa.hibernate.ddl-auto=validate` and never `create`, `create-drop`
+  or `update` against supplied data; set `spring.jpa.open-in-view=false`.
+  Seeds are idempotent: repeatable migrations or a startup runner that checks
+  before inserting.
+- Keep tests off development data: a `test` profile
+  (`src/test/resources/application-test.properties`, activated with
+  `@ActiveProfiles("test")` or Surefire's `spring.profiles.active`) points the
+  datasource at a disposable test database supplied by the environment
+  (`TEST_DB_NAME` with the database integrations below). Do not
+  add `src/test/resources/application.properties`, which replaces the main file
+  on the test classpath. Testcontainers needs a container runtime the
+  environment may not provide.
+- Deployment serves the executable jar. Set `<finalName>app</finalName>` in the
+  Maven `<build>` so the proposed Serve step finds `target/app.jar`; the jar
+  reads `HOST` and `PORT` through the properties above.
+- When the app has login, use Spring Security users with `ADMIN` and `USER`
+  roles and a delegating `PasswordEncoder`. Seed one administrator and one
+  ordinary user for development from a `dev`-profile runner or seed migration
+  that reads the password from the environment and creates each user only
+  when absent. Never use `{noop}` passwords or seeded credentials outside
+  development.
+- A Gradle project replaces the proposals with the wrapper equivalents:
+  `./gradlew` `bootRun` `--args=--server.address={host} --server.port={port}`,
+  `./gradlew` `test`, and `./gradlew` `bootJar` with
+  `bootJar { archiveFileName = 'app.jar' }` serving `build/libs/app.jar`.
+
+## Adoption
+
+- Inspect `pom.xml` or `build.gradle(.kts)`, the wrapper, the Spring Boot and
+  Java versions, `application.properties`/`application.yml` and every profile
+  file, the security configuration, the embedded server, the packaging (`jar`
+  or `war`) and the migration tool before changing project contracts. Preserve
+  the build tool and Boot major version.
+- Replace any proposed setup, run, readiness, verification or deployment line
+  that does not match the application before claiming readiness, including
+  the jar name, the health route and the address/port properties.
+- When the app uses PostgreSQL or MySQL, select the matching Spring Boot
+  database integration so its datasource environment names become explicit.
+
+## Workspace setup
+
+- Prepare `Compile application` with `java` when `pom.xml` exists: `./mvnw` `-B` `-DskipTests` `compile`
+
+## Outputs
+
+### Target `app`: Run Spring Boot app
+
+- Default.
+- Mode: `interactive`
+- Runtimes: `java`
+- Run `Develop`: `./mvnw` `-B` `spring-boot:run` `-Dspring-boot.run.arguments=--server.address={host} --server.port={port}`
+
+#### Presentation
+
+- Kind: `web`
+- Preferred port: `8080`
+- URL path: `/`
+- Ready when: `GET` `/actuator/health` returns `200`
+
+## Verification
+
+- Verify `application`: `./mvnw` `-B` `test`
+
+## Deployment
+
+- Runtimes: `java`
+- Ready when: `GET` `/actuator/health` returns `200`
+- Build `Package`: `./mvnw` `-B` `-DskipTests` `package`
+- Serve `Start`: `java` `-jar` `target/app.jar`
+
+## Deslop
+
+- Preserve Spring's constructor injection, configuration properties,
+  component boundaries, Spring Data repositories, transaction boundaries and
+  security configuration.
+- Keep `@Transactional` at service boundaries and validation at controller or
+  configuration-properties boundaries. Remove service, mapper or DTO layers only
+  when they duplicate framework behavior without protecting a real seam.
+- Preserve migration history and entity mappings; cleanup is not permission to
+  edit applied migrations or loosen `ddl-auto`.