docs: add local console to getting started guide (#58)

docs/src/modules/ROOT/partials/cli-install-short.adoc

@@ -0,0 +1,42 @@
+Install the Akka CLI:
+
+NOTE: In case there is any trouble with installing the CLI when following these instructions, please check xref:reference:cli/installation.adoc[].
+
+[.tabset]
+Linux::
++
+--
+Download and install the latest version of `akka`:
+[source,bash]
+....
+curl -sL https://doc.akka.io/install-cli.sh | bash
+....
+
+--
+macOS::
++
+--
+The recommended approach to install `akka` on macOS, is using https://brew.sh[brew, window="new"]
+
+[source,bash]
+----
+brew install akka/brew/akka
+----
+
+--
+Windows::
++
+--
+
+. Download the latest version of `akka` from https://downloads.akka.io/latest/akka_windows_amd64.zip[https://downloads.akka.io/latest/akka_windows_amd64.zip]
+
+. Extract the zip file and move `akka.exe` to a location on your `%PATH%`.
+
+--
+
+Verify that the Akka CLI has been installed successfully by running the following to list all available commands:
+
+[source, command window]
+----
+akka help
+----

docs/src/modules/java/pages/author-your-first-service.adoc

@@ -3,25 +3,24 @@
 
 include::ROOT:partial$include.adoc[]
 
-This guide will walk you through the process of setting up your development environment, generating a project, and implementing a simple "Hello World!" REST service. By the end, you will have a functional HTTP endpoint built with the Akka SDK running locally.
+== Introduction 
 
-== Overview
+In this guide, you will:
 
-The Akka SDK comes with Maven support that enables you to get started quickly. In this guide, you will:
-
-* Use the Akka Maven archetype to generate a skeleton project that follows the recommended onion architecture.
-* Understand how to use the Akka Maven parent POM to define dependencies and run your application locally.
-
-NOTE: If you'd rather skip past this and want to review an already completed application see the xref:java:shopping-cart-quickstart.adoc[].
+* Set up your development environment.
+* Generate a simple project from a template that follows the recommended xref:concepts:architecture-model.adoc#_architecture[onion architecture].
+* Explore a basic HTTP Endpoint that responds with "Hello World!"
+* Add path parameters, a request body and a response body to the Endpoint.
+* Run your service locally.
+* Explore the local console to observe your running service.
 
 == Prerequisites
 
 include::ROOT:partial$local-dev-prerequisites.adoc[]
 
+== Generate and build the project
 
-== Generate and build the skeleton project
-
-The Maven archetype template prompts you to specify the project's group ID, name and version interactively. Run it using the commands shown for your OS.
+The Maven archetype template prompts you to specify the project's group ID, name and version interactively. Run it using the commands shown for your operating system.
 
 [sidebar]
 In IntelliJ, you can skip the command line. Open the IDE, select
@@ -35,7 +34,7 @@ Follow these steps to generate and build your project:
 Linux or macOS::
 +
 --
-[source,command line, subs="attributes"]
+[source,command window, subs="attributes"]
 ----
 mvn archetype:generate \
   -DarchetypeGroupId=io.akka \
@@ -46,7 +45,7 @@ mvn archetype:generate \
 Windows 10+::
 +
 --
-[source,command line, subs="attributes"]
+[source,command window, subs="attributes"]
 ----
 mvn archetype:generate ^
   -DarchetypeGroupId=io.akka ^
@@ -55,7 +54,8 @@ mvn archetype:generate ^
 ----
 --
 
-. Fill in
++
+.Fill in:
 * groupId: `com.example`
 * artifactId: `helloworld`
 * version: `1.0-SNAPSHOT`
@@ -65,7 +65,13 @@ mvn archetype:generate ^
 
 . Open it in your preferred IDE / Editor.
 
-. Expand directory `src/main/java/com/example/api` and open the `HelloWorldEndpoint.java` file.
+== Explore the HTTP Endpoint
+
+An _Endpoint_ is a component that creates an externally accessible API. Endpoints are how you expose your services to the outside world. Endpoints can have different protocols and, initially, support HTTP.
+
+HTTP Endpoint components make it possible to conveniently define such APIs accepting and responding in JSON, or dropping down to lower level APIs for ultimate flexibility in what types of data is accepted and returned.
+
+. Open the `src/main/java/com/example/api/HelloWorldEndpoint.java` file.
 
 The _Endpoint_ is implemented with:
 
@@ -83,14 +89,9 @@ public class HelloWorldEndpoint {
 }
 ----
 
-== Basics
-An _Endpoint_ is a component that creates an externally accessible API. Endpoints are how you expose your services to the outside world. Endpoints can have different protocols and, initially, support HTTP.
+This Endpoint is on the path `/hello` and exposes an HTTP GET operation on `/`.
 
-HTTP Endpoint components make it possible to conveniently define such APIs accepting and responding in JSON, or dropping down to lower level APIs for ultimate flexibility in what types of data is accepted and returned.
-
-This endpoint is on the path `/hello` and exposes an HTTP GET operation on `/`.
-
-You can also see that there is an _Access Control List_ (ACL) on this endpoint that allows all traffic from the Internet. Without this ACL the service would be unreachable, but you can be very expressive with these ACLs.
+You can also see that there is an _Access Control List_ (ACL) on this Endpoint that allows all traffic from the Internet. Without this ACL the service would be unreachable, but you can be very expressive with these ACLs.
 
 == Run locally
 
@@ -101,11 +102,11 @@ Start your service locally:
 mvn compile exec:java
 ----
 
-Once successfully started, any defined endpoints become available at `localhost:9000` and you will see an INFO message that the Akka Runtime has started.
+Once successfully started, any defined Endpoints become available at `localhost:9000` and you will see an INFO message that the Akka Runtime has started.
 
 Your "Hello World" service is now running.
 
-In another shell, you can now use `curl` to send requests to this endpoint.
+In another shell, you can now use `curl` to send requests to this Endpoint.
 
 [source, command line]
 ----
@@ -118,12 +119,17 @@ Which will reply
 Hello World!
 ----
 
+== Getting more advanced
+
+In this section, you will modify the HTTP Endpoint to accept path parameters, a request body, and return a response body.
+
+=== Add path parameters
+
+The path can also contain one or more parameters, which are extracted and passed to the method.
 
-== Getting more complex
-Endpoints provide the common capabilities you would expect for creating REST services. Here are a few more:
+Path parameters can be of type `String`, `int`, `long`, `boolean`,  `float`, `double`, `short` or `char`, as well as their `java.lang` class counterparts.
 
-=== Path parameters ===
-The path can also contain one or more parameters, which are extracted and passed to the method:
+Add path parameters to the Endpoint using the code shown below:
 
 [source,java]
 .HelloWorldEndpoint.java
@@ -135,10 +141,7 @@ include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java
 <3> When there are multiple parameters
 <4> The method must accept all the same names in the same order as in the path expression.
 
-Path parameter can be of types `String`, `int`, `long`, `boolean`,  `float`, `double`, `short` and `char` as well
-as their `java.lang` class counterparts.
-
-If you add this code above to `HelloWorldEndpoint.java` and restart the service, you can now curl these commands:
+Restart the service and curl these commands:
 
 [source, command line]
 ----
@@ -150,9 +153,9 @@ curl localhost:9000/hello/hello/Bob
 curl localhost:9000/hello/hello/Bob/30
 ----
 
-=== Request body ===
+=== Add a request body
 
-To accept an HTTP JSON body, specify a parameter that is a Java record.
+Modify the Endpoint to accept an HTTP JSON body using the code shown below:
 
 [source,java]
 .HelloWorldEndpoint.java
@@ -164,16 +167,17 @@ include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java
 <3> When combining request body with path variables
 <4> The body must come last in the parameter list
 
-You can now call these commands as well
+Restart the service and curl this command:
+
 [source, command line]
 ----
 curl -i -XPOST -H "Content-Type: application/json" localhost:9000/hello/hello -d '
 {"age":"30", "name":"Bob"}'
 ----
 
-=== Response body ===
+=== Add a response body
 
-To return response with JSON, the return value can be a record that gets serialized as JSON:
+Modify the Endpoint to return a response body using the code shown below:
 
 [source,java]
 .HelloWorldEndpoint.java
@@ -182,10 +186,55 @@ include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java
 ----
 <1> Returning a record that gets serialized as JSON
 
+Restart the service and curl this command:
+
 [source, command line]
 ----
 curl localhost:9000/hello/hello/Bob/30
 ----
 
+== Explore the local console
+
+The Akka local console is a web-based tool that provides a convenient way to view and interact with your running service.
+
+=== Install the Akka CLI
+
+Starting the local console requires using the Akka CLI and Docker.
+
+include::ROOT:partial$cli-install-short.adoc[]
+
+
+=== Start the local console
+
+. Start the local console. It will launch a Docker container:
++
+[source,bash]
+----
+akka local console
+
+Pulling local console image, please wait...
+----
+
+. Once the console is running, you will see a message like this:
+
++
+[source,bash]
+----
+- helloworld is running at: localhost:9000
+-----------------------------------------------------
+(use Ctrl+C to quit)
+----
+
+. You can then access the local console in your browser at:
++
+http://localhost:3000
+
+. Navigate to your service's Endpoint, which will be available http://localhost:3000/services/akka-javasdk-archetype/components/io.akka.api.HelloWorldEndpoint[here, window="new"].
+
+image:hello-world-local-console.png[]
+
+This is a simple Hello World service, so there isn't much to see here yet. However, as you build more complex services, the console will become a more valuable tool for monitoring and debugging.
+
 == Next steps
+
 Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application and learn how to deploy it to https://console.akka.io[akka.io].

docs/src/modules/reference/pages/cli/installation.adoc

@@ -24,10 +24,10 @@ curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix /tmp && \
 
 You can pass options to the installer script with `-s --` e.g.:
 
-[source,bash]
+[source,bash,subs="attributes"]
 ....
-curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version=2.0.22 --verbose
-curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v 2.0.22 -V
+curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version={akka-cli-version} --verbose
+curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v {akka-cli-version} -V
 ....
 
 --
@@ -59,9 +59,10 @@ curl -sL https://doc.akka.io/install-cli.sh | bash
 
 You can pass options to the installer script with `-s --` e.g.:
 
+[source,bash,subs="attributes"]
 ....
-curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version=2.0.22 --verbose
-curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v 2.0.22 -V
+curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version={akka-cli-version} --verbose
+curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v {akka-cli-version} -V
 ....
 --
 Windows::