chore: prep repo

Author: dhevdotdev

.dockerignore

@@ -0,0 +1,7 @@
+.gradle
+.idea
+build
+*.iml
+.git
+.gitignore
+HELP.md

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: gradle
+
+      - name: Run Gradle tests
+        run: ./gradlew test
+
+      - name: Start local stack
+        run: docker compose up --build -d postgres app
+
+      - name: Run Hurl suite
+        run: ./scripts/run-hurl.sh
+
+      - name: Export OpenAPI document
+        run: ./scripts/export-openapi.sh
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: docs-site
+
+      - name: Stop local stack
+        if: always()
+        run: docker compose down -v

.github/workflows/deploy-docs.yml

@@ -0,0 +1,38 @@
+name: deploy-docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ vars.CF_PAGES_PROJECT_NAME != '' }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Start local stack
+        run: docker compose up --build -d postgres app
+
+      - name: Run Hurl suite
+        run: ./scripts/run-hurl.sh
+
+      - name: Export OpenAPI document
+        run: ./scripts/export-openapi.sh
+
+      - name: Deploy docs site to Cloudflare Pages
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: npx wrangler pages deploy docs-site --project-name "${{ vars.CF_PAGES_PROJECT_NAME }}"
+
+      - name: Stop local stack
+        if: always()
+        run: docker compose down -v

.gitignore

@@ -38,3 +38,6 @@ out/
 
 ### Claude Code ###
 .claude/
+
+### Cloudflare ###
+.wrangler/

Dockerfile

@@ -0,0 +1,13 @@
+FROM eclipse-temurin:21-jdk AS build
+WORKDIR /workspace
+COPY gradlew gradlew
+COPY gradle gradle
+COPY build.gradle settings.gradle ./
+COPY src src
+RUN ./gradlew --no-daemon bootJar
+
+FROM eclipse-temurin:21-jre
+WORKDIR /app
+COPY --from=build /workspace/build/libs/*.jar app.jar
+EXPOSE 8080
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]

README.md

@@ -0,0 +1,109 @@
+# RealWorld Spring Boot API
+
+Backend implementation of the [RealWorld](https://github.com/realworld-apps/realworld)
+spec using Spring Boot 3, Java 21, PostgreSQL, Flyway, Docker, and Hurl.
+
+This repository is built against the RealWorld backend contract. It is not
+presented here as an official RealWorld listing.
+
+## Stack
+
+- Java 21
+- Spring Boot 3
+- PostgreSQL
+- Flyway
+- Docker Compose
+- Hurl
+- OpenAPI via springdoc
+- Scalar API reference
+
+## What is here
+
+- RealWorld backend endpoints for auth, profiles, articles, comments, tags, favorites, and feed
+- Docker-based local stack with PostgreSQL
+- Hurl verification suite against the running API
+- Static docs site artifact for separate publishing
+
+## API docs
+
+The app serves an interactive reference at `/`, but live request execution is
+disabled so the page behaves like hosted documentation instead of an API client.
+
+The repository also includes a static docs site in [`docs-site/`](./docs-site)
+that can be published separately, for example on `realworld.dhev.dev`.
+
+## Local development
+
+Run the full stack with Docker Compose:
+
+```sh
+docker compose up --build -d postgres app
+```
+
+The API will be available at `http://localhost:8080` and the app will use the
+Compose-managed PostgreSQL container instead of requiring a host-installed
+database.
+
+Run the Hurl verification suite against the Compose stack:
+
+```sh
+./scripts/run-hurl.sh
+```
+
+Export the OpenAPI document for the static docs site:
+
+```sh
+./scripts/export-openapi.sh
+```
+
+Stop everything:
+
+```sh
+docker compose down
+```
+
+If you want to remove the local PostgreSQL volume too:
+
+```sh
+docker compose down -v
+```
+
+## Local build without Docker
+
+The app can still run against any reachable PostgreSQL instance through env vars.
+Without overrides, it defaults to `jdbc:postgresql://localhost:5432/realworld`.
+
+```sh
+./gradlew bootJar
+```
+
+## CI and docs deploy
+
+GitHub Actions includes:
+
+- `ci.yml` to run Gradle tests, boot the Docker stack, run the Hurl suite, and export the OpenAPI document
+- `deploy-docs.yml` to deploy `docs-site/` to Cloudflare Pages
+
+To use the docs deploy workflow, set:
+
+- repository variable `CF_PAGES_PROJECT_NAME`
+- repository secrets `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`
+
+Custom domain mapping such as `realworld.dhev.dev` is configured in Cloudflare
+Pages, not in this repository.
+
+## Deploy
+
+Use a Docker-capable web host and a managed PostgreSQL database.
+
+Minimal environment:
+
+```text
+SPRING_DATASOURCE_URL=jdbc:postgresql://<host>/<database>?sslmode=require
+SPRING_DATASOURCE_USERNAME=<username>
+SPRING_DATASOURCE_PASSWORD=<password>
+JWT_SECRET=<base64-encoded-strong-secret>
+```
+
+For a quick public demo, use Render Free for the web service and Neon Free for
+PostgreSQL. The app reads the platform `PORT` env var automatically.

compose.yaml

@@ -0,0 +1,54 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: realworld
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d realworld"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  app:
+    build:
+      context: .
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      PORT: 8080
+      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/realworld
+      SPRING_DATASOURCE_USERNAME: postgres
+      SPRING_DATASOURCE_PASSWORD: postgres
+      JWT_SECRET: MkdhNr+BZydYUbnFnTMCd9ddPPVShVdsDT0322Y5hlQvb/Y6gnywB2TcsuqjdAO6AI4SxtV4Kcqduk8YT4SNSg==
+    ports:
+      - "8080:8080"
+
+  hurl:
+    image: ghcr.io/orange-opensource/hurl:latest
+    profiles: ["verify"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+      app:
+        condition: service_started
+    volumes:
+      - ./hurl:/hurl:ro
+    entrypoint:
+      - sh
+      - -lc
+    command: >
+      uid=$$(date +%s%N) &&
+      hurl --test
+      --retry 30
+      --retry-interval 1000
+      --variable host=http://app:8080
+      --variable uid=$$uid
+      /hurl/*.hurl
+
+volumes:
+  postgres-data:

docs-site/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>RealWorld API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-url="./openapi.json"
+      data-configuration='{
+        "theme": "default",
+        "forceDarkModeState": "dark",
+        "hideModels": true,
+        "expandAllResponses": true,
+        "expandAllModelSections": true,
+        "hideTestRequestButton": true,
+        "hideClientButton": true,
+        "documentDownloadType": "none",
+        "showDeveloperTools": "never",
+        "agent": { "disabled": true }
+      }'
+    ></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>

docs-site/openapi.json

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUTPUT_DIR="$ROOT_DIR/docs-site"
+OUTPUT_FILE="$OUTPUT_DIR/openapi.json"
+API_URL="${API_URL:-http://localhost:8080/v3/api-docs}"
+
+mkdir -p "$OUTPUT_DIR"
+curl --fail --silent --show-error "$API_URL" > "$OUTPUT_FILE"
+echo "OpenAPI document written to $OUTPUT_FILE"