Refactor Docker Compose file naming to avoid V2 precedence conflict

CHANGELOG.md

@@ -12,6 +12,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## 2026-03-22
 
 ### Changed
+- Refactored Docker Compose file naming to avoid V2 precedence conflict (#68)
+  - `compose.yaml` → `compose.dev.yaml` (dev dependencies for `bootRun`)
+  - `docker-compose.yml` → `compose.yaml` (full deployable stack)
+  - Added `spring.docker.compose.file` to `application-local.yml-example`
+  - Updated README with compose file descriptions and Docker Compose V2 syntax
 - Refactored `TestDataController` to use `Instant` instead of `Date` for registration dates, aligning with library changes (#65)
 
 ### Dependencies

README.md

@@ -117,7 +117,7 @@ The fastest way to get started is using Docker Compose:
 # Clone and start everything
 git clone https://github.com/devondragon/SpringUserFrameworkDemoApp.git
 cd SpringUserFrameworkDemoApp
-docker-compose up --build
+docker compose up --build
 ```
 
 **Access the Application**: `http://localhost:8080`
@@ -166,7 +166,7 @@ docker-compose up --build
        ```
      - Using Docker Compose with Keycloak stack:
        ```bash
-       docker-compose -f docker-compose-keycloak.yml up --build
+       docker compose -f docker-compose-keycloak.yml up --build
        ```
 
 5. **Access the Application**
@@ -510,13 +510,18 @@ mvn spring-boot:run
 
 The project includes a complete Docker setup with the application, MariaDB database, and a mail server.
 
+**Docker Compose files:**
+- **`compose.yaml`** — Full deployable stack (app + database + mail server). Use this to run the entire application in Docker.
+- **`compose.dev.yaml`** — Dev dependencies only (database). Used automatically by Spring Boot's Docker Compose integration during `bootRun` for local development.
+- **`docker-compose-keycloak.yml`** — Full stack with Keycloak for OIDC authentication testing.
+
 ```bash
-docker-compose up --build
+docker compose up --build
 ```
 
 To launch the Keycloak stack:
 ```bash
-docker-compose -f docker-compose-keycloak.yml up --build
+docker compose -f docker-compose-keycloak.yml up --build
 ```
 
 **Note**: Test emails sent from the local Postfix server may not be accepted by all email providers. Use a real SMTP server for production use.
@@ -695,7 +700,7 @@ Solution:
 1. Check SMTP configuration in application.yml
 2. Verify mail server credentials
 3. Check spam/junk folders
-4. Use Docker mail server for testing: docker-compose logs mailserver
+4. Use Docker mail server for testing: docker compose logs mailserver
 ```
 
 #### Application Won't Start

compose.dev.yaml

@@ -0,0 +1,20 @@
+# Local Development Database Configuration
+# WARNING: These credentials are for LOCAL DEVELOPMENT ONLY.
+# Production deployments MUST use secure credentials managed through
+# environment variables or secrets management systems.
+
+services:
+  mariadb:
+    image: mariadb:12.2
+    environment:
+      MARIADB_DATABASE: springuser
+      MARIADB_USER: springuser
+      MARIADB_PASSWORD: springuser
+      MARIADB_ROOT_PASSWORD: rootpassword
+    ports:
+      - "3306:3306"
+    volumes:
+      - mariadb-data:/var/lib/mysql
+
+volumes:
+  mariadb-data:

compose.yaml

@@ -1,20 +1,91 @@
-# Local Development Database Configuration
-# WARNING: These credentials are for LOCAL DEVELOPMENT ONLY.
-# Production deployments MUST use secure credentials managed through
-# environment variables or secrets management systems.
 
 services:
-  mariadb:
-    image: mariadb:12.2
+  myapp-db:
+    image: mariadb:11.6.2
+    container_name: springuser-db
+    volumes:
+      - userdb:/var/lib/mysql
     environment:
-      MARIADB_DATABASE: springuser
-      MARIADB_USER: springuser
-      MARIADB_PASSWORD: springuser
-      MARIADB_ROOT_PASSWORD: rootpassword
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: springuser
+      MYSQL_USER: springuser
+      MYSQL_PASSWORD: springuser
+      MYSQL_TCP_PORT: 3306
     ports:
       - "3306:3306"
+    healthcheck:
+      test: [ "CMD", "healthcheck.sh", "--connect", "--innodb_initialized" ]
+      start_period: 1m
+      start_interval: 10s
+      interval: 1m
+      timeout: 5s
+      retries: 3
+
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    container_name: springuser-mail
+    hostname: mailserver
+    domainname: local
+    env_file: mailserver.env
+    ports:
+      - "25:25"
+      - "587:587"
     volumes:
-      - mariadb-data:/var/lib/mysql
+      - maildata:/var/mail
+      - mailstate:/var/mail-state
+      - maillogs:/var/log/mail
+      - ./config/:/tmp/docker-mailserver/${SELINUX_LABEL}
+    environment:
+      PERMIT_DOCKER: connected-networks
+      ONE_DIR: 1
+      DMS_DEBUG: 0
+      SPOOF_PROTECTION: 0
+      REPORT_RECIPIENT: 1
+      ENABLE_SPAMASSASSIN: 0
+      ENABLE_CLAMAV: 0
+      ENABLE_FAIL2BAN: 1
+      ENABLE_POSTGREY: 0
+      SMTP_ONLY: 1
+    cap_add:
+      - NET_ADMIN
+      - SYS_PTRACE
+    healthcheck:
+      test: ["CMD", "nc", "-z", "localhost", "25"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+  myapp-main:
+    image: spring-user-framework-demo
+    container_name: springuser-app
+    build:
+      context: .
+      dockerfile: Dockerfile
+    depends_on:
+      myapp-db:
+        condition: service_healthy
+      mailserver:
+        condition: service_healthy
+    ports:
+      - "8080:8080"
+    environment:
+      SPRING_DATASOURCE_URL: jdbc:mariadb://myapp-db:3306/springuser?createDatabaseIfNotExist=true
+      SPRING_DATASOURCE_USERNAME: springuser
+      SPRING_DATASOURCE_PASSWORD: springuser
+      SPRING_PROFILES_ACTIVE: dev
+      SPRING_MAIL_HOST: mailserver
+      SPRING_MAIL_PORT: 25
+      SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH: "false"
+      SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: "false"
+      SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED: "false"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
 
 volumes:
-  mariadb-data:
+  maildata:
+  mailstate:
+  maillogs:
+  userdb:

src/main/resources/application-local.yml-example

@@ -12,6 +12,9 @@ logging:
         security: DEBUG # Set logging level for security
 
 spring:
+  docker:
+    compose:
+      file: compose.dev.yaml
   application:
     name: Spring User Framework Demo App # Change this as per your convenience
   datasource: