[backend] chore(onboarding): improv our onboarding process (#5567)

openaev-api/src/main/resources/application-dev.properties.example

@@ -0,0 +1,81 @@
+# =============================================================================
+# OpenAEV Development Profile (Spring profile: dev)
+# =============================================================================
+# Copy this file to application-dev.properties and update values as needed.
+# Activate with: --spring.profiles.active=dev (or ACTIVE_PROFILES=dev in IntelliJ)
+#
+# Default values below match the docker-compose services in openaev-dev/.
+
+# OpenAEV General Configuration
+openaev.admin.email=admin@openaev.io
+openaev.admin.password=admin
+openaev.admin.token=<generate-a-uuid>
+openaev.admin.encryption_key=ChangeMe
+openaev.admin.encryption_salt=ChangeMe
+# Enterprise license (leave empty for community edition)
+# A valid license can be found in the team's 1Password vault.
+openaev.application-license=
+
+########################
+# RUNTIME DEPENDENCIES #
+########################
+
+### POSTGRESQL Configuration
+# Values should match POSTGRES_USER / POSTGRES_PASSWORD from openaev-dev/.env
+spring.datasource.url=jdbc:postgresql://localhost:5432/openaev
+spring.datasource.username=${POSTGRES_USER:openaev}
+spring.datasource.password=${POSTGRES_PASSWORD:openaev}
+
+### ENGINE Configuration
+# selector can be "elk" (Elasticsearch, port 9200) or "opensearch" (OpenSearch, port 9202)
+engine.engine-selector=opensearch
+engine.url=http://localhost:9200
+
+### MINIO Configuration
+# Ports match docker-compose: API on 10000, console on 10001
+minio.endpoint=localhost
+minio.port=10000
+minio.access-key=minioadmin
+minio.access-secret=minioadmin
+
+######################
+# RUNTIME PROPERTIES #
+######################
+
+# Logging
+logging.level.root=info
+logging.level.io.openaev=info
+
+#############
+# INJECTORS #
+#############
+
+# Mail sending config (required for email-based injects)
+# Credentials can be found in 1Password: "[OpenAEV/Dev] SMTP / IMAP account"
+openaev.default-mailer=no-reply@openaev.io
+openaev.default-reply-to=contact@openaev.io
+spring.mail.host=<see-1password>
+spring.mail.port=465
+spring.mail.username=<see-1password>
+spring.mail.password=<see-1password>
+# Extra mail configuration
+spring.mail.properties.mail.smtp.ssl.trust=*
+spring.mail.properties.mail.smtp.ssl.enable=true
+spring.mail.properties.mail.smtp.auth=true
+spring.mail.properties.mail.smtp.starttls.enable=true
+
+# IMAP Configuration (optional, for email reception)
+# Credentials can be found in 1Password: "[OpenAEV/Dev] SMTP / IMAP account"
+openaev.mail.imap.enabled=false
+openaev.mail.imap.host=ssl0.ovh.net
+openaev.mail.imap.username=<see-1password>
+openaev.mail.imap.password=<see-1password>
+openaev.mail.imap.port=993
+openaev.mail.imap.inbox=INBOX
+
+#############################
+# FEATURE UNDER DEVELOPMENT #
+#############################
+# Use "*" to enable all dev features, or a comma-separated list
+openaev.enabled-dev-features=*
+

openaev-dev/.env.example

@@ -1,18 +1,25 @@
+# =============================================================================
 # OpenAEV Development Environment Variables
-# Copy this file to .env and update values as needed
+# =============================================================================
+# Copy this file to .env and update values as needed:
+#   cp .env.example .env
+#
+# These variables are consumed by docker-compose.yml (via podman compose).
 
-# PostgreSQL Configuration
+# ---------- PostgreSQL ----------
+# Used by both dev (port 5432) and test (port 5433) PostgreSQL containers
 POSTGRES_USER=openaev
 POSTGRES_PASSWORD=openaev
 
-# pgAdmin Configuration
+# ---------- pgAdmin (optional) ----------
+# Web UI available at http://localhost:5050
 PGADMIN_USER=admin@openaev.io
 PGADMIN_PASSWORD=admin
 
-# openaev API, e.g. for XTM Composer
+# ---------- XTM Composer (optional) ----------
+# Only needed if you run the xtm-composer service.
+# OPENAEV_ADMIN_TOKEN must match openaev.admin.token in application-dev.properties
 OPENAEV_ADMIN_TOKEN=
 XTM_COMPOSER_ID=
-
-# openaev URL used for XTM Composer, for macOS and Windows, use http://host.docker.internal:8080,
-# for Linux, use http://localhost:8080
+# For macOS/Windows use http://host.docker.internal:8080, for Linux use http://localhost:8080
 OPENAEV_URL=

openaev-dev/README.md

@@ -4,7 +4,7 @@ This folder contains configuration files for setting up a local development envi
 
 ## Prerequisites
 
-- Docker and Docker Compose
+- Podman and Podman Compose (or `podman compose`)
 - Java 21+ (for backend development)
 - Node.js 20+ and Yarn (for frontend development)
 - IntelliJ IDEA (recommended IDE)
@@ -28,41 +28,67 @@ Copy-Item .env.example .env
 
 The default values should work for local development.
 
-### 2. Start the Docker containers
+### 2. Create the backend dev configuration
+
+Copy the example and fill in your values:
+
+```bash
+cp ../openaev-api/src/main/resources/application-dev.properties.example \
+   ../openaev-api/src/main/resources/application-dev.properties
+```
+
+### 3. Start the containers
+
+#### Minimal start (recommended to get up and running quickly)
+
+Only **4 services** are required to run OpenAEV locally:
+
+```bash
+podman compose up -d openaev-dev-pgsql openaev-dev-minio openaev-dev-elasticsearch openaev-dev-rabbitmq
+```
+
+| Service | Port | Why it's required |
+|---------|------|-------------------|
+| **PostgreSQL (dev)** | 5432 | Primary data store — all entities, users, scenarios |
+| **MinIO** | 10000 (API), 10001 (Console) | File/document storage (S3-compatible) |
+| **Elasticsearch (dev)** | 9200, 9300 | Full-text search & indexing engine |
+| **RabbitMQ** | 5672 (AMQP), 15672 (Management) | Async messaging between backend components |
+
+> **Tip:** If you prefer OpenSearch over Elasticsearch, start `openaev-dev-opensearch` instead and set `engine.engine-selector=opensearch` / `engine.url=http://localhost:9202` in your `application-dev.properties`.
+
+#### Full start (all services)
 
 ```bash
-docker compose up -d
+podman compose up -d
 ```
 
-This will start the following services:
+This starts everything, including optional services:
 
 | Service | Port | Description |
 |---------|------|-------------|
 | PostgreSQL (dev) | 5432 | Main development database (persistent) |
 | PostgreSQL (test) | 5433 | Test database (ephemeral, no volume) |
 | MinIO | 10000 (API), 10001 (Console) | Object storage |
 | RabbitMQ | 5672 (AMQP), 15672 (Management) | Message queue |
-| Caldera | 8888 | Adversary simulation platform |
 | Elasticsearch (dev) | 9200, 9300 | Search engine |
 | Elasticsearch (test) | 9201, 9301 | Test search engine |
 | OpenSearch (dev) | 9202, 9600 | Alternative search engine |
 | Kibana (dev) | 5601 | Elasticsearch UI |
-| Kibana (test) | 5602 | Test Elasticsearch UI |
-| pgAdmin | 5050 | PostgreSQL management UI |
+| Kibana (test) | 5602 | Test Elasticsearch UI (optional) |
+| pgAdmin | 5050 | PostgreSQL management UI (optional) |
 
-### 3. Access services
+### 4. Access services
 
 - **MinIO Console**: http://localhost:10001 (minioadmin/minioadmin)
 - **RabbitMQ Management**: http://localhost:15672 (guest/guest)
 - **pgAdmin**: http://localhost:5050 (admin@openaev.io/admin by default, see `.env`)
 - **Kibana**: http://localhost:5601
-- **Caldera**: http://localhost:8888 (red/ChangeMe or blue/ChangeMe by default, see `caldera.yml`)
 
 ## IntelliJ Run Configurations
 
 This folder contains pre-configured IntelliJ run configurations:
 
-- **Backend docker compose**: Starts all Docker containers
+- **Backend docker compose**: Starts all containers via Podman
 - **Backend start**: Starts the Spring Boot backend with the `dev` profile
 - **Frontend start**: Starts the frontend development server
 
@@ -73,11 +99,11 @@ To use them, copy the `*.run.xml` files to your `.idea/runConfigurations/` folde
 | File | Description |
 |------|-------------|
 | `.env.example` | Example environment variables (copy to `.env`) |
-| `docker-compose.yml` | Docker Compose configuration for all services |
-| `caldera.yml` | Caldera server configuration |
+| `docker-compose.yml` | Container composition file (used via `podman compose`) |
 | `rabbitmq.conf` | RabbitMQ configuration |
 | `otlp-config.yaml` | OpenTelemetry Collector configuration (for telemetry) |
 | `Project.xml` | IntelliJ code style settings |
+| `../openaev-api/src/main/resources/application-dev.properties.example` | Example Spring dev profile (copy to `application-dev.properties`) |
 
 ## Notes
 

openaev-dev/docker-compose.yml

@@ -1,4 +1,10 @@
 services:
+
+  # ===========================================================================
+  #  MANDATORY SERVICES — Required to run OpenAEV locally
+  #  Start with: podman compose up -d openaev-dev-pgsql openaev-dev-minio openaev-dev-elasticsearch openaev-dev-rabbitmq
+  # ===========================================================================
+
   # Development PostgreSQL database (persistent storage)
   openaev-dev-pgsql:
     container_name: openaev-dev-pgsql
@@ -17,22 +23,6 @@ services:
       interval: 10s
       timeout: 5s
       retries: 5
-  # Test PostgreSQL database (ephemeral - no volume for clean test runs)
-  openaev-test-pgsql:
-    container_name: openaev-test-pgsql
-    image: postgres:17-alpine
-    environment:
-      POSTGRES_USER: ${POSTGRES_USER}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_DB: openaev
-    ports:
-      - "5433:5432"
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d openaev"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
   # MinIO object storage (S3-compatible)
   # API: http://localhost:10000, Console: http://localhost:10001
   # Credentials: minioadmin/minioadmin
@@ -67,56 +57,6 @@ services:
       interval: 30s
       timeout: 10s
       retries: 3
-  # Caldera adversary simulation platform
-  # See caldera.yml for configuration (update credentials before production use)
-  openaev-dev-caldera:
-    container_name: openaev-dev-caldera
-    image: openbas/caldera-server:5.1.0
-    restart: unless-stopped
-    ports:
-      - "8888:8888"
-    environment:
-      CALDERA_URL: http://localhost:8888
-    volumes:
-      - type: bind
-        source: ./caldera.yml
-        target: /usr/src/app/conf/local.yml
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8888"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-#  openaev-pyroscope:
-#    container_name: openaev-pyroscope
-#    image: grafana/pyroscope:latest
-#    restart: unless-stopped
-#    ports:
-#      - "4040:4040"
-#  openaev-telemetry-otlp:
-#    container_name: openaev-telemetry-otlp
-#    image: otel/opentelemetry-collector-contrib:0.119.0
-#    restart: unless-stopped
-#    volumes:
-#      - "./otlp-config.yaml:/etc/config/otlp-config.yaml"
-#      - "./telemetry.json:/telemetry.json"
-#    command:
-#      - '--config=/etc/config/otlp-config.yaml'
-#    ports:
-#      - "1010:1010"
-  # pgAdmin - PostgreSQL management UI
-  # Default credentials: see PGADMIN_USER/PGADMIN_PASSWORD in .env
-  openaev-dev-pgadmin:
-    image: dpage/pgadmin4
-    container_name: openaev-dev-pgadmin
-    restart: unless-stopped
-    ports:
-      - "5050:80"
-    environment:
-      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_USER}
-      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
-    depends_on:
-      openaev-dev-pgsql:
-        condition: service_healthy
   # Development Elasticsearch (persistent storage)
   openaev-dev-elasticsearch:
     container_name: openaev-dev-elasticsearch
@@ -147,6 +87,28 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
+
+  # ===========================================================================
+  #  OPTIONAL SERVICES — For testing, tooling, or alternative engines
+  #  These are NOT required for day-to-day backend/frontend development.
+  # ===========================================================================
+
+  # Test PostgreSQL database (ephemeral - no volume for clean test runs)
+  openaev-test-pgsql:
+    container_name: openaev-test-pgsql
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: openaev
+    ports:
+      - "5433:5432"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}", "-d", "openaev"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
   # Development OpenSearch (alternative to Elasticsearch, persistent storage)
   # NOTE: OpenSearch and Elasticsearch both use port 9200 by default internally.
   # OpenSearch is mapped to external port 9202 to avoid conflicts.
@@ -205,6 +167,20 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
+  # pgAdmin - PostgreSQL management UI
+  # Default credentials: see PGADMIN_USER/PGADMIN_PASSWORD in .env
+  openaev-dev-pgadmin:
+    image: dpage/pgadmin4
+    container_name: openaev-dev-pgadmin
+    restart: unless-stopped
+    ports:
+      - "5050:80"
+    environment:
+      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_USER}
+      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
+    depends_on:
+      openaev-dev-pgsql:
+        condition: service_healthy
   # Kibana - Elasticsearch UI for development
   openaev-dev-kibana:
     container_name: openaev-dev-kibana
@@ -229,6 +205,7 @@ services:
     depends_on:
       openaev-test-elasticsearch:
         condition: service_healthy
+  # RSA key generator & XTM Composer (needed only for injector integration testing)
   rsa-key-generator:
     image: alpine/openssl:3.5.5
     volumes:
@@ -268,6 +245,29 @@ services:
       openaev-dev-rabbitmq:
         condition: service_healthy
     restart: always
+  # Pyroscope — continuous profiling (optional, for performance debugging)
+  # Uncomment to enable. UI available at http://localhost:4040
+#  openaev-pyroscope:
+#    container_name: openaev-pyroscope
+#    image: grafana/pyroscope:latest
+#    restart: unless-stopped
+#    ports:
+#      - "4040:4040"
+
+  # OpenTelemetry Collector (optional, for telemetry/tracing)
+  # Uncomment to enable. Requires otlp-config.yaml and telemetry.json
+#  openaev-telemetry-otlp:
+#    container_name: openaev-telemetry-otlp
+#    image: otel/opentelemetry-collector-contrib:0.119.0
+#    restart: unless-stopped
+#    volumes:
+#      - "./otlp-config.yaml:/etc/config/otlp-config.yaml"
+#      - "./telemetry.json:/telemetry.json"
+#    command:
+#      - '--config=/etc/config/otlp-config.yaml'
+#    ports:
+#      - "1010:1010"
+
 volumes:
   esdata:
     driver: local