refactor(db): retire dockerless PostgreSQL support (#1522)

Author: FelixTJDietrich

.changeset/solid-socks-smash.md

@@ -0,0 +1,2 @@
+---
+---

.gitignore

@@ -190,7 +190,6 @@ sdist/
 server/.env.bak.*
 server/logs/
 server/postgres-data/
-server/postgres-data-local/
 server/postgres-data-temp-*
 server/postgres-data-temp/
 server/postgres-data*.tgz

docs/contributor/dockerless-postgres.mdx

@@ -12,7 +12,8 @@ Hephaestus supports full-stack development across Java and TypeScript. This guid
 Install and configure the following tools before you attempt a local build:
 
 1. **Java JDK 21** – Required for the Spring Boot application server.
-2. **Docker Desktop** – Used for PostgreSQL and NATS containers.
+2. **Docker and Docker Compose** – Required for PostgreSQL and NATS. Verify both with `docker info`
+   and `docker compose version`.
 3. **Node.js LTS (>= 24)** and **pnpm (>= 11)** (enable via `corepack enable`) – For the React client and root scripts.
 4. **Bun** – Runs the agent runtime and precompute tests (`pnpm run test:agents`). `corepack` does not
    provide it; install it separately. Match the version the agent image pins — the `ARG BUN_VERSION`
@@ -64,8 +65,7 @@ they are used.
 
 They are **not** Maven profiles — `./mvnw -Plocal` warns that the profile does not exist and changes
 nothing. Maven passes the active Spring profile through the `app.profiles` property, so the override
-is `-Dapp.profiles=…` (this is what `pnpm dev:server:e2e` does). Maven's own profiles are a separate,
-smaller set: `live-tests`, `architecture-tests`, `quick`, `pitest`, `aot` and `local-db-timeout`.
+is `-Dapp.profiles=…` (this is what `pnpm dev:server:e2e` does).
 
 Create `server/src/main/resources/application-local.yml` to override defaults. This file is gitignored.
 
@@ -75,7 +75,7 @@ Never commit `application-local.yml`. It may contain secrets and machine-specifi
 
 ### Running the stack
 
-1. Start Docker Desktop.
+1. Ensure the Docker daemon is running with `docker info`.
 2. From the repo root, start everything with one command:
 
    ```bash

docs/contributor/local-development.mdx

@@ -17,9 +17,6 @@ const sidebars: SidebarsConfig = {
         'coding-guidelines',
         'api-error-handling',
         'workspace-context',
-        'dockerless-postgres',
-        // How we develop, not what we ship — the "AI Development" category below is the product's
-        // own agent runtime, which is a different meaning of the word.
         'ai-agent-workflow',
       ],
     },
@@ -43,7 +40,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'AI Development',
+      label: 'Agent Runtime',
       items: ['unified-pi-runtime', 'agent/agent-workspace-abi', 'llm-cost-vocabulary'],
     },
     {

docs/sidebars.contributor.ts

@@ -7,7 +7,7 @@
 	"scripts": {
 		"changeset:version": "changeset version && node scripts/sync-selfhost-version.ts",
 		"generate:api:application-server:clean": "node -e \"import('node:fs/promises').then(fs => fs.rm('webapp/src/api', {recursive: true, force: true}))\"",
-		"generate:api:application-server:specs": "cd server && sh -c 'if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then ./mvnw verify -DskipTests=true -Dapp.profiles=specs; else SPRING_DOCKER_COMPOSE_ENABLED=false ./mvnw verify -DskipTests=true -Dapp.profiles=specs; fi'",
+		"generate:api:application-server:specs": "cd server && ./mvnw verify -DskipTests=true -Dapp.profiles=specs",
 		"generate:api:application-server:client": "pnpm run generate:api:application-server:clean && pnpm --filter webapp run openapi-ts",
 		"generate:api:application-server": "pnpm run generate:api:application-server:specs && pnpm run generate:api:application-server:client",
 		"generate:api": "pnpm run generate:api:application-server",

package.json

@@ -10,20 +10,22 @@ Scripts use dependencies from the root `package.json`. Run `pnpm install` at the
 
 ### Database Utilities
 
-All database-related commands are accessed via `db-utils.sh` which handles database setup, migrations, and cleanup:
+Database documentation commands use `db-utils.sh` and require Docker with the Compose plugin:
 
 ```bash
 pnpm run db:generate-erd-docs                    # Generate Mermaid ERD diagram
 pnpm run db:draft-changelog                       # Generate Liquibase changelog diff
 ```
 
-**ERD Generation Environment Variables:**
+**ERD generation environment variables:**
 
-| Variable             | Default     | Description                  |
-| -------------------- | ----------- | ---------------------------- |
-| `POSTGRES_HOST`      | `localhost` | PostgreSQL host              |
-| `POSTGRES_PORT`      | `5432`      | PostgreSQL port              |
-| `HEPHAESTUS_DB_MODE` | `docker`    | Database mode: docker/local  |
+| Variable            | Default      | Description         |
+| ------------------- | ------------ | ------------------- |
+| `POSTGRES_HOST`     | `localhost`  | PostgreSQL host     |
+| `POSTGRES_PORT`     | `5432`       | PostgreSQL port     |
+| `POSTGRES_DB`       | `hephaestus` | PostgreSQL database |
+| `POSTGRES_USER`     | `root`       | PostgreSQL user     |
+| `POSTGRES_PASSWORD` | `root`       | PostgreSQL password |
 
 ### Achievement Formatting