Update README.md for improved clarity and formatting in Docker commands and usage instructions

Author: mkjsix

README.md

@@ -21,38 +21,45 @@ Check also the [RESTHeart Greetings Services Tutorial](https://restheart.org/doc
 
 🚀 To run and develop this project you can now use the new [RESTHeart command line interface](https://github.com/SoftInstigate/restheart-cli/tree/master). It provides a convenient interface for watching for code changes and automatically rebuilding/redeploying RESTHeart plugins.
 
-After you have installed the cli, follow its [Usage Guide](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md). It explains how to start from this plugin skeleton to create a __continuous development process__.
+After you have installed the cli, follow its [Usage Guide](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md). It explains how to start from this plugin skeleton to create a **continuous development process**.
 
 ### Run with Docker
 
 Follow these steps if you prefer to set up and run the project with docker:
 
 1. Clone the repository:
+
    ```bash
-   $ git clone --depth 1 git@github.com:SoftInstigate/restheart-plugin-skeleton.git
+   git clone --depth 1 git@github.com:SoftInstigate/restheart-plugin-skeleton.git
    ```
+
 2. Navigate to the project directory:
+
    ```bash
-   $ cd restheart-plugin-skeleton
+   cd restheart-plugin-skeleton
    ```
+
 3. Build and run the container:
+
    ```bash
-   $ ./mvnw clean package && docker run --pull=always --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s
+   ./mvnw clean package && docker run --pull=always --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s
    ```
 
 > **Note:** The `-s` option (**standalone mode**) disables MongoDB-dependent plugins. Use this option if you do not intend to connect to a MongoDB instance during runtime.
 
 Test the service using:
 
 With curl:
+
 ```bash
-$ curl localhost:8080/srv
+curl localhost:8080/srv
 {"message":"Hello World!","rnd":"njXZksfKFW"}%
 ```
 
 With httpie:
+
 ```bash
-$ http -b :8080/srv
+http -b :8080/srv
 {
     "message": "Hello World!",
     "rnd": "KvQGBwsPBp"
@@ -68,23 +75,29 @@ $ http -b :8080/srv
 To run RESTHeart with MongoDB, follow these steps:
 
 1. Launch a MongoDB container:
+
    ```bash
-   $ docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0
+   docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0
    ```
+
 2. Initialize MongoDB as a Single Node Replica Set:
+
    ```bash
-   $ docker exec mongodb mongosh --quiet --eval "rs.initiate()"
+   docker exec mongodb mongosh --quiet --eval "rs.initiate()"
    ```
+
 3. Build and run the RESTHeart container:
+
    ```bash
-   $ ./mvnw clean package && docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart
+   ./mvnw clean package && docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart
    ```
 
 > **Note:** The `-s` option is not used here to enable MongoDB-dependent plugins.
 
 Test a simple GET request:
+
 ```bash
-$ curl -u admin:secret localhost:8080/users
+curl -u admin:secret localhost:8080/users
 ```
 
 For more details, check the [REST API Tutorial](https://restheart.org/docs/mongodb-rest/tutorial) and the [GraphQL Tutorial](https://restheart.org/docs/mongodb-graphql/tutorial).
@@ -96,17 +109,19 @@ For more details, check the [REST API Tutorial](https://restheart.org/docs/mongo
 The default configuration is used. The environment variable `RHO` can be used to override the configuration. See [Change the configuration in Docker container](https://restheart.org/docs/configuration#change-the-configuration-in-docker-container)
 
 Example:
+
 ```bash
-$ docker run --name restheart --rm     -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/helloWorldService/message->'Ciao Mondo!'"     -p "8080:8080"     -v ./target:/opt/restheart/plugins/custom     softinstigate/restheart -s
+docker run --name restheart --rm     -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/helloWorldService/message->'Ciao Mondo!'"     -p "8080:8080"     -v ./target:/opt/restheart/plugins/custom     softinstigate/restheart -s
 ```
 
 Here, the `RHO` variable overrides:
+
 - `/http-listener/host`: Sets the host to `0.0.0.0`.
 - `/mclient/connection-string`: Specifies the MongoDB connection string.
 - `/helloWorldService/message`: Changes the default service message to "Ciao Mondo!".
 
 ```bash
-$ curl localhost:8080/srv
+curl localhost:8080/srv
 {"message":"Ciao Mondo!","rnd":"rhyXFHOQUA"}%
 ```
 
@@ -119,9 +134,11 @@ Dependencies are managed using Maven. By default, jars are copied to the `target
 ### Avoid Duplicate JARs
 
 RESTHeart includes several libraries by default. To avoid conflicts:
+
 - Use the `provided` scope for dependencies already included in RESTHeart.
 
 Example:
+
 ```xml
 <dependency>
     <groupId>org.restheart</groupId>
@@ -132,9 +149,10 @@ Example:
 ```
 
 To list included libraries:
+
 ```bash
-$ git clone https://github.com/SoftInstigate/restheart.git && cd restheart
-$ mvn dependency:tree -Dscope=compile
+git clone https://github.com/SoftInstigate/restheart.git && cd restheart
+mvn dependency:tree -Dscope=compile
 ```
 
 ---
@@ -144,20 +162,25 @@ $ mvn dependency:tree -Dscope=compile
 RESTHeart supports building native images with GraalVM for optimized startup time and memory usage.
 
 ### Requirements
+
 - Install GraalVM using [sdkman](https://sdkman.io/):
+
   ```bash
-  $ sdk install java 21.0.3-graal
+  sdk install java 21.0.3-graal
   ```
 
 ### Build and Run Native Image
 
 1. Build the native image:
+
    ```bash
-   $ ./mvnw clean package -Pnative
+   ./mvnw clean package -Pnative
    ```
+
 2. Run the binary:
+
    ```bash
-   $ RHO="/fullAuthorizer/enabled->true" target/restheart-plugin-skeleton
+   RHO="/fullAuthorizer/enabled->true" target/restheart-plugin-skeleton
    ```
 
 For more details, check [Deploy Java Plugins on RESTHeart native](https://restheart.org/docs/plugins/deploy#deploy-java-plugins-on-restheart-native).
@@ -180,13 +203,47 @@ For more details, check [Deploy Java Plugins on RESTHeart native](https://resthe
 ### Using Maven Profiles
 
 Activate a profile with the `-P` option:
+
 ```bash
-$ ./mvnw clean package -Psecurity
+./mvnw clean package -Psecurity
 ```
 
 Combine profiles as needed:
+
 ```bash
-$ ./mvnw clean package -Psecurity,mongodb
+./mvnw clean package -Psecurity,mongodb
 ```
 
 For more details, refer to the `pom.xml` file.
+
+### Profile Matrix (Common Scenarios)
+
+Use this matrix to pick the right profiles and commands for typical setups.
+
+| Scenario | Profiles | Build Command | Run Command |
+| --- | --- | --- | --- |
+| Standalone demo (no MongoDB) | _(none)_ or `security`/`metrics` as needed | \`./mvnw clean package\` | \`docker run --pull=always --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s\` |
+| MongoDB development (insecure dev only) | `mongodb` | \`./mvnw clean package -Pmongodb\` | \`docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0\` then \`docker exec mongodb mongosh --quiet --eval "rs.initiate()"\` then \`docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart\` |
+| Secured MongoDB API | `security,mongodb` | \`./mvnw clean package -Psecurity,mongodb\` | Same as MongoDB development (without `-s`) |
+| GraphQL over MongoDB | `graphql,mongodb` (add `security` if needed) | \`./mvnw clean package -Pgraphql,mongodb\` | Same as MongoDB development (without `-s`) |
+| Metrics enabled | `metrics` (+ combine with others) | \`./mvnw clean package -Pmetrics\` | Combine with your chosen run mode |
+| Native executable (bundles RESTHeart + plugin) | `native` (+ combine modules at build time is not supported; native already bundles required RESTHeart artifacts) | \`sdk install java 21.0.3-graal\` then \`./mvnw clean package -Pnative\` | \`RHO="/fullAuthorizer/enabled->true" target/restheart-plugin-skeleton\` |
+
+Notes:
+
+- Docker `-s` flag runs in standalone mode (disables MongoDB-dependent plugins). Do not use `-s` when you enable `mongodb` profile.
+- In default (non-`native`) builds, RESTHeart core dependencies are treated as `provided`; your plugin JAR plus `target/lib` contains only external runtime deps.
+- Avoid heavy static initializers in plugins to keep GraalVM native-image builds smooth.
+
+---
+
+## Debugging & Logs
+
+- RESTHeart logs to stdout/stderr in Docker and to console in native runs. Inspect container logs for plugin issues:
+
+   ```bash
+   docker logs -f restheart
+   ```
+
+- If your service returns `405`, verify the HTTP method handling in `src/main/java/org/restheart/examples/HelloWorldService.java` and ensure `OPTIONS` is handled via `handleOptions(req)` for CORS.
+- To adjust service behavior at runtime, prefer `RHO` env overrides instead of code changes (e.g., `/helloWorldService/message`).