diff --git a/Makefile b/Makefile index 38433e4da..a21360a34 100644 --- a/Makefile +++ b/Makefile @@ -44,7 +44,7 @@ attributes: prepare > "${managed_partials}/attributes.adoc" docs/bin/version.sh | xargs -0 printf ":akka-javasdk-version: %s" \ > "${managed_partials}/attributes.adoc" - echo ":akka-cli-version: 3.0.6" >> "${managed_partials}/attributes.adoc" + echo ":akka-cli-version: 3.0.7" >> "${managed_partials}/attributes.adoc" echo ":akka-cli-min-version: 3.0.4" >> "${managed_partials}/attributes.adoc" # see https://adoptium.net/marketplace/ echo ":java-version: 21" \ diff --git a/docs/src/modules/ROOT/partials/cli-install-short.adoc b/docs/src/modules/ROOT/partials/cli-install-short.adoc new file mode 100644 index 000000000..1eed185f0 --- /dev/null +++ b/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 +---- diff --git a/docs/src/modules/java/images/hello-world-local-console.png b/docs/src/modules/java/images/hello-world-local-console.png new file mode 100644 index 000000000..7d9997340 Binary files /dev/null and b/docs/src/modules/java/images/hello-world-local-console.png differ diff --git a/docs/src/modules/java/pages/author-your-first-service.adoc b/docs/src/modules/java/pages/author-your-first-service.adoc index 60deccb4f..1ab0875bb 100644 --- a/docs/src/modules/java/pages/author-your-first-service.adoc +++ b/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]. diff --git a/docs/src/modules/operations/pages/projects/container-registries.adoc b/docs/src/modules/operations/pages/projects/container-registries.adoc index abcb36d9b..1bc8892a3 100644 --- a/docs/src/modules/operations/pages/projects/container-registries.adoc +++ b/docs/src/modules/operations/pages/projects/container-registries.adoc @@ -9,7 +9,7 @@ Akka provides a built-in _Akka Container Registry (ACR)_ which is pre-configured == Akka Container Registry -The _Akka Container Registry (ACR)_ is available to all Akka users and supported across all Akka regions, allowing for easy, integrated deployments without dependency on external registry connectivity. Authentication is built-in, so deployments, restarts, and scaling operate independently from external networks. +The _Akka Container Registry (ACR)_ is available to all Akka users and supported across all Akka regions, allowing for easy, integrated deployments without dependency on external registry connectivity. Authentication is built-in, so deployments, restarts, and scaling operate independently of external networks. == Prerequisites diff --git a/docs/src/modules/reference/pages/cli/akka-cli/akka_local_console.adoc b/docs/src/modules/reference/pages/cli/akka-cli/akka_local_console.adoc index 6a4087f5d..cd590cd09 100644 --- a/docs/src/modules/reference/pages/cli/akka-cli/akka_local_console.adoc +++ b/docs/src/modules/reference/pages/cli/akka-cli/akka_local_console.adoc @@ -14,7 +14,7 @@ akka local console [flags] ---- -h, --help help for console - --local-console-image string Override the local console image. (default "gcr.io/kalix-public/akka-local-console:d0ed8e0") + --local-console-image string Override the local console image. (default "gcr.io/kalix-public/akka-local-console:e349ebdc") ---- == Options inherited from parent commands diff --git a/docs/src/modules/reference/pages/cli/installation.adoc b/docs/src/modules/reference/pages/cli/installation.adoc index 92657ffd3..c0cd65534 100644 --- a/docs/src/modules/reference/pages/cli/installation.adoc +++ b/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:: diff --git a/docs/src/modules/reference/pages/release-notes.adoc b/docs/src/modules/reference/pages/release-notes.adoc index 0ea50e466..35cddf42c 100644 --- a/docs/src/modules/reference/pages/release-notes.adoc +++ b/docs/src/modules/reference/pages/release-notes.adoc @@ -12,6 +12,9 @@ Current versions == December 2024 +* Akka CLI 3.0.7 + - Improvements to the Local Console + * https://github.com/akka/akka-sdk/releases/tag/v3.0.1[Akka SDK 3.0.1] - Minor improvements diff --git a/docs/src/modules/support/nav.adoc b/docs/src/modules/support/nav.adoc index dcb24ff79..6fbe263f9 100644 --- a/docs/src/modules/support/nav.adoc +++ b/docs/src/modules/support/nav.adoc @@ -3,4 +3,8 @@ * xref:support:index.adoc[] ** xref:support:community-forum.adoc[] ** xref:support:email.adoc[] -** xref:support:platform-status.adoc[] \ No newline at end of file +** xref:support:frequently-asked-questions.adoc[] +** xref:support:paid-plans.adoc[] +** xref:support:platform-status.adoc[] +** xref:support:request-a-demo.adoc[] +** xref:support:troubleshooting.adoc[] diff --git a/docs/src/modules/support/pages/community-forum.adoc b/docs/src/modules/support/pages/community-forum.adoc index 1367e91ef..65536a2fe 100644 --- a/docs/src/modules/support/pages/community-forum.adoc +++ b/docs/src/modules/support/pages/community-forum.adoc @@ -12,4 +12,4 @@ include::ROOT:partial$include.adoc[] [sidebar] -https://discuss.akka.io/[Join the Akka Community Forum] \ No newline at end of file +https://discuss.akka.io/c/akka-sdk/43[Join the Akka Community Forum] diff --git a/docs/src/modules/support/pages/email.adoc b/docs/src/modules/support/pages/email.adoc index 9e9e19a61..569d45a1b 100644 --- a/docs/src/modules/support/pages/email.adoc +++ b/docs/src/modules/support/pages/email.adoc @@ -6,4 +6,4 @@ include::ROOT:partial$include.adoc[] Connect with a member of the Akka team for advice and support on your project. -Browse to https://www.akka.io/contact[https://www.akka.io/contact,window="new"], provide the necessary details and submit the form. A team member will reach out to you shortly. \ No newline at end of file +Browse to https://akka.io/contact-us[akka.io/contact-us,window="new"], provide the necessary details and submit the form. A team member will reach out to you shortly. diff --git a/docs/src/modules/support/pages/frequently-asked-questions.adoc b/docs/src/modules/support/pages/frequently-asked-questions.adoc index 616c8b06e..c8f4493e9 100644 --- a/docs/src/modules/support/pages/frequently-asked-questions.adoc +++ b/docs/src/modules/support/pages/frequently-asked-questions.adoc @@ -43,8 +43,8 @@ In one sentence: "High performance and very low latency in an extremely cost-eff In a few more words, with Akka, companies can: -- Provide higher agility to ever changing market demands: Legacy infrastructure and architectures make it very expensive to deliver scalable solutions quickly. Akka let's you circumvent all those technical limitations. -- Increase the speed to innovation: Distributed compute and data have long been purview of expert engineers proficient in narrow scope of programming languages. Akka makes building these kinds of applications straight-forward in languages you already know and use. +- Provide higher agility to ever-changing market demands: Legacy infrastructure and architectures make it very expensive to deliver scalable solutions quickly. Akka lets you circumvent all those technical limitations. +- Increase the speed to innovation: Distributed compute and data have long been purview of expert engineers proficient in narrow scope of programming languages. Akka makes building these kinds of applications straight-forward. - Lower infrastructure costs: Scalable cloud architectures are difficult to operate, require large teams of costly resources and run significant risk of unexpected budget overages. Akka will charge for what you use, not what you might need (when generally available). == What are the benefits for developers? @@ -63,10 +63,6 @@ Yes! Akka is a single globally distributed state model. Teams anywhere in the wo Akka leverages the proven Akka reactive architecture for building stateful, high-performance, business-critical systems, without the developer needing to understand the complexities of Akka itself or distributed systems architecture in general. -== What languages are supported? - -Akka supports Java and Scala. For a detailed overview of supported features see xref:reference:feature-matrix[Feature Matrix] section. - == What are the resource limits of an Akka service? Individual requests and responses, states and events can in general have a payload size up to 12 Mb. @@ -117,7 +113,7 @@ The short answer is no. Please see the documentation on xref:support:paid-plans. === How do I purchase a paid plan? -https://www.akka.io/contact[Contact Lightbend] to purchase a paid plan. See the https://www.akka.io/pricing[pricing page] for purchase options. +https://akka.io/contact-us[Contact Akka] to purchase a paid plan. See the https://akka.io/pricing[pricing page] for purchase options. == What if I have additional questions or want to provide feedback? diff --git a/docs/src/modules/support/pages/paid-plans.adoc b/docs/src/modules/support/pages/paid-plans.adoc index 341829ea2..7d5e7708e 100644 --- a/docs/src/modules/support/pages/paid-plans.adoc +++ b/docs/src/modules/support/pages/paid-plans.adoc @@ -15,7 +15,7 @@ Upgrading to a paid plan offer several benefits: == Upgrading to a paid plan -To upgrade, please https://www.akka.io/contact[contact Akka,window="new"]. +To upgrade, please https://akka.io/contact-us[contact Akka,window="new"]. You will be required to provide: @@ -27,4 +27,4 @@ You will be required to provide: == Billing models -Please see the https://www.akka.io/pricing[Akka Pricing] page for more details on billing models, features and pricing. +Please see the https://akka.io/pricing[Akka Pricing] page for more details on billing models, features and pricing. diff --git a/docs/src/modules/support/pages/request-a-demo.adoc b/docs/src/modules/support/pages/request-a-demo.adoc index c24e30bc4..350b248c4 100644 --- a/docs/src/modules/support/pages/request-a-demo.adoc +++ b/docs/src/modules/support/pages/request-a-demo.adoc @@ -6,4 +6,4 @@ include::ROOT:partial$include.adoc[] We'd love to learn about your requirements, answer your unique questions, and review ways that Akka can help you and your organization. -Browse to https://www.akka.io/contact[https://www.akka.io/contact,window="new"], provide the necessary details and submit the form. A team member will reach out to you shortly. \ No newline at end of file +Browse to https://akka.io/contact-us[akka.io/contact-us,window="new"], provide the necessary details and submit the form. A team member will reach out to you shortly. diff --git a/docs/src/modules/support/pages/troubleshooting.adoc b/docs/src/modules/support/pages/troubleshooting.adoc index 58ef9b9b0..504cf0276 100644 --- a/docs/src/modules/support/pages/troubleshooting.adoc +++ b/docs/src/modules/support/pages/troubleshooting.adoc @@ -22,7 +22,8 @@ NOTE: You can check the version of the Akka CLI you have by running `akka versio When you see the following error: -``` +[source] +---- [ERROR] /path/to/file.proto [0:0]: --akka-grpc_out: protoc-gen-akka-grpc: Plugin output is unparseable: [0.001s][warning][os,container] Duplicate cpuset controllers detected. Picking /sys/fs/cgroup/cpuset, skipping /host/sys/fs/cgroup/cpuset. (...) [INFO] ------------------------------------------------------------------------ @@ -32,7 +33,7 @@ When you see the following error: [INFO] Finished at: 2022-03-07T15:31:49Z [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal org.xolstice.maven.plugins:protobuf-maven-plugin:0.6.1:compile (protobuf) on project customer-registry: protoc did not exit cleanly. Review output for more information. -> [Help 1] -``` +---- This problem is caused by JDK17 https://bugs.openjdk.java.net/browse/JDK-8270087[reporting some warnings to `stdout` instead of `stderr`, window="new"]. The easiest way to resolve this is to avoid the situation leading to the warning, or switching to a JDK version without this bug, like JDK11. @@ -67,7 +68,7 @@ The same status message will appear within the System Lifecycle events window. *Options to resolve this issue include:* * Use a public repository -* Supply your xref:operations:projects/container-registries.adoc#_a_private_container_registry[credentials], and validate that they are correct. +* Supply your xref:operations:projects/external-container-registries.adoc[credentials], and validate that they are correct. == How to resolve errors when my deployment cannot start