Local development

Status: implemented local PostgreSQL and backend workflow. Updated: 29 October 2026.

Prerequisites

• JDK 25 for the JVM build.
• Docker with Compose for the local PostgreSQL stack.
• GraalVM 25 with native-image and the platform C toolchain only when building the native executable.
• A Google OAuth client ID whose ID tokens target this backend.
• A Base64 HMAC secret containing at least 32 random bytes.

Environment file

Create apps/product-backend/local.env. It is ignored by Git and excluded from the Docker build.

POSTGRES_DB=product_backend
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<local database password>
JWT_SECRET=<Base64 secret, at least 32 decoded bytes>
GOOGLE_CLIENT_ID=<Google OAuth client ID>

Generate a suitable secret with:

openssl rand -base64 32

Use a real Google client ID for sign-in testing. The Compose stack substitutes local-development.invalid only when GOOGLE_CLIENT_ID is absent, which allows startup but not real login.

Outside the local profile, supply SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, and SPRING_DATASOURCE_PASSWORD directly. For hosted Supabase, use a reachable direct or session-pooler JDBC endpoint with certificate-verified TLS.

Apply the schema manually

Flyway is a test-only dependency. The application does not create or migrate the schema at startup, and the Compose image does not run Flyway.

After PostgreSQL is healthy, apply the baseline once:

cd apps/product-backend
docker compose --env-file local.env up -d --wait postgres
docker compose --env-file local.env exec -T postgres \
  psql -U postgres -d product_backend -v ON_ERROR_STOP=1 \
  < src/main/resources/database/migrations/V1__product_schema.sql

Change -d product_backend if POSTGRES_DB uses another name. The Compose image creates the postgres role, so keep POSTGRES_USER=postgres for the local stack. Apply later migration files in filename order. Do not edit an applied migration; add a forward migration instead.

The Compose database mounts postgres-bootstrap.sql once during initial database setup to grant the local role permission to create product tables in the public schema. That grant does not create the product tables.

Run with Compose

Build and start both containers:

cd apps/product-backend
docker compose --env-file local.env up -d --build
curl http://127.0.0.1:8080/hello
docker compose --env-file local.env down

The backend waits for PostgreSQL readiness, not for the schema. Apply the schema before starting the backend, or restart the backend after applying it.

Named volumes preserve database data and Supabase database configuration when containers stop. down without -v keeps the data.

Run on the host

Start PostgreSQL, apply the schema, then run Spring on the host:

cd apps/product-backend
docker compose --env-file local.env up -d --wait postgres
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

The local profile imports optional:file:./local.env[.properties] from the backend directory and overrides the JDBC URL with jdbc:postgresql://127.0.0.1:${PRODUCT_POSTGRES_PORT:5432}/${POSTGRES_DB:product_backend}. Run the command from apps/product-backend.

Commands

Run these from the repository root unless noted. The pnpm scripts wrap the Maven commands.

From apps/product-backend:

./mvnw verify
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
curl http://127.0.0.1:8080/hello

verify runs the entity JSON tests, Google decoder tests, token service tests, and HTTP integration tests, then packages target/product-backend.jar. The HTTP tests start a disposable PostgreSQL container through Testcontainers and apply the test schema through Flyway, so Docker must be running. The checked-in Maven Wrapper selects Maven 3.9.16. Builds target Java 25 and use Spring Boot 4.1.2 with Kotlin 2.4.21.

IDE setup

Open the repository root in IntelliJ IDEA. The root atstrology-designs module owns the pnpm workspace; the separate product-backend Java module owns this directory, its Kotlin source and test roots, resources, and Maven dependencies. Keep the backend directory visible in the root module; only target is excluded.

The root IntelliJ project links this app’s pom.xml and selects the graalvm-ce-25 SDK. Ensure that SDK points to an installed JDK 25 under File → Project Structure → Project. Keep the Node interpreter and pnpm package manager configured independently under Settings → Languages & Frameworks → JavaScript Runtime.

If module files change while the project is open, reopen the root project, then use Reload All Maven Projects. Confirm that Project Structure → Modules lists both atstrology-designs and product-backend, and that the backend has a Kotlin facet and Maven libraries. If the POM is absent from the Maven tool window, right-click pom.xml and choose Add as Maven Project. Kotlin completion requires the imported module and resolved dependencies; linking the POM alone is insufficient.

Verification and troubleshooting

• GET /hello proves JVM and HTTP startup without database or Google access.
• GET /v3/api-docs proves Springdoc and controller annotations are reachable.
• A real login requires a Google ID token whose audience equals GOOGLE_CLIENT_ID.
• GOOGLE_TOKEN_REQUIRED means the request body was blank.
• INVALID_GOOGLE_TOKEN means Google signature, issuer, audience, or time validation failed.
• UNVERIFIED_GOOGLE_IDENTITY means the token lacked a subject, email, verified email, or expiry.
• A missing login_identity or login_session table means the schema was not applied.
• Startup failure about a missing or weak JWT_SECRET means the key is absent or does not decode to at least 32 bytes.
• AUTHENTICATION_REQUIRED, INVALID_ACCESS_TOKEN, and ACCESS_DENIED are authentication failures, not missing routes.

Related files