akka / akka-guide Goto Github PK

See #11

When running locally it's necessary to use different ports, but in cloud env it would probably use a fixed port. Ports for Akka Remoting, gRPC server and Akka Management.

We need to adjust Main to take local or cloud environment into account. Probably easiest to let Main amend the port configurations only if the port is defined as argument to main. Otherwise use the conf as is.

With what we've learned about structuring this guide with Antora we should consider renaming things:

The repository: akka-microservices-samples -> akka-platform-guide
The example: cqrs -> shopping-microservices

The tutorial directory can be removed so that shopping-microservices just contains the tutorial.

References #42

We can use a flat build, since it's not multi-project builds.

Also, the full list of dependencies can be included in all projects even though not used in all.

I'm thinking that we will have an empty project template with the dependencies and plugins. Then we could have a "how to reduce build dependencies" describing what can be removed if not used.

The IntegrationSpec is failing for me now. Strange, since I tried it when the docker-compose PR was added. I have tried to restart with docker-compose down.

[2020-08-21 11:36:55,305] [ERROR] [akka.actor.OneForOneStrategy] [] [IntegrationSpec-akka.actor.default-dispatcher-5] - Failed to construct kafka consumer
akka.actor.ActorInitializationException: akka://IntegrationSpec/system/kafka-consumer-1: exception during creation
	at akka.actor.ActorInitializationException$.apply(Actor.scala:196)
	at akka.actor.ActorCell.create(ActorCell.scala:661)
	at akka.actor.ActorCell.invokeAll$1(ActorCell.scala:513)
	at akka.actor.ActorCell.systemInvoke(ActorCell.scala:535)
  | => sat akka.dispatch.Mailbox.processAllSystemMessages(Mailbox.scala:295)
	at akka.dispatch.Mailbox.run(Mailbox.scala:230)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
	at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: org.apache.kafka.common.KafkaException: Failed to construct kafka consumer
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:820)
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:631)
	at akka.kafka.ConsumerSettings$.createKafkaConsumer(ConsumerSettings.scala:237)
	at akka.kafka.ConsumerSettings$.$anonfun$apply$3(ConsumerSettings.scala:111)
	at akka.kafka.internal.KafkaConsumerActor.akka$kafka$internal$KafkaConsumerActor$$applySettings(KafkaConsumerActor.scala:459)
	at akka.kafka.internal.KafkaConsumerActor.preStart(KafkaConsumerActor.scala:436)
	at akka.actor.Actor.aroundPreStart(Actor.scala:548)
	at akka.actor.Actor.aroundPreStart$(Actor.scala:548)
	at akka.kafka.internal.KafkaConsumerActor.aroundPreStart(KafkaConsumerActor.scala:212)
	at akka.actor.ActorCell.create(ActorCell.scala:641)
	... 7 common frames omitted
Caused by: org.apache.kafka.common.config.ConfigException: No resolvable bootstrap urls given in bootstrap.servers
	at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:88)
	at org.apache.kafka.clients.ClientUtils.parseAndValidateAddresses(ClientUtils.java:47)
	at org.apache.kafka.clients.consumer.KafkaConsumer.<init>(KafkaConsumer.java:735)
	... 16 common frames omitted

Maybe good to include in default config:

akka.persistence.journal.auto-start-journals = ["akka.persistence.cassandra.journal"]

Add a docker-compose configuration for Cassandra to run the example easily in a local setting.

or akka-microservices-guide

AsciiDoc supports lowering the failure of the processor using --failure-level=LEVEL (defaults to FATAL).

It'd be useful to setup --failure-level=WARNING. I've been looking around but can't locate how to setup our Makefile/antora build to pass that setting down into the asciidoctor command. Edit: that setting is for asciidoctorCLI, not asciidcotor.js.

Do we need to add some caching instructions for Travis to avoid downloading the docker stuff each time?

Some material from https://www.lagomframework.com/documentation/1.6.x/scala/CoreConcepts.html would be good to include here.

Describe what dependencies that can be removed (from the empty template project) when different things are not used.

using Akka Management health checks

I played with the idea that we could share some live templates for typical scaffolding.

Created a few in attached akka-templates.zip to illustrate.

That zip can be imported from File > Manage IDE Settings > Import Settings

It adds a Akka Microservices scaladsl template group. The templates are prefixed with akka- so you can try by creating a Cart.scala file and then akka + ctrl-space and select akka-Entity

I would like to suggest that we structure the documentation like Django documentation:
https://docs.djangoproject.com/en/3.1/internals/contributing/writing-documentation/#how-the-documentation-is-organized

• Tutorial - step by step tutorial building up the sample project
• Concepts - general explanation of concepts and motivations
• How to - recipes for specific things (additions to the tutorial sample)
• Reference - overview of links to reference documentation

I know there is an article describing how to structure documentation around these 4 topics, but I can't find it at the moment.

See #14

I don't think "write-model" and "read-model" are great names for the roles.

"write-side" and "read-side" are slightly better. A projection reads the events. Entities writes the events.

"entity" and "projection" might be better?

Also, define constants in the code for these roles.

Bootstrap - should we use it locally too so we don't end up having to describe seed nodes and bootstrap. Also avoids not having bootstrap.start being conditional for local.

Discovery - consider not using it for Kafka/gRPC/Cassandra. In k8s these can be headless services and for local we can override them to be localhost with config.

See #15

and remote the HTTP routes

Images in some of the Concepts pages e.g. https://github.com/akka/akka-platform-guide/blob/main/docs-source/docs/modules/concepts/assets/images/concepts/internal-and-external-communication.png) were directly copy/pasted from the original location.

As a consequence, the look of images in https://github.com/akka/akka-platform-guide/tree/main/docs-source/docs/modules/concepts/assets/images varyies or doesn't fully match the text (as it evolved).

Should it demo Maven or Gradle or sbt or 2/3 or all?

• port the shopping cart service #213
• port the orders service
• port the analytics service

Travis and CLA checker

In Travis, see attached log
IntegrationSpec.log

For example cluster and persistence config in separate files. Imported by application.conf

The documentation should explain the basics of how APIs can be evolved when using Protobuf.

The config of the grpc interface is still defined as 127.0.0.1. We need different config for application.conf and local.conf

Two places:

shopping-cart.grpc.interface
shopping-order.grpc.interface

For no reason the packages became sample.shoppingcart, sample.shoppinganalytics and sample.shoppingorder. Would be better with sample.shopping.cart, sample.shopping.analytics and sample.shopping.order

A question for Ruth.

In the tutorial I wanted to encourage the reader to actively build up the application by adding code themselves, even if that only means copy paste from the documentation snippets.

I used instructions like like "Add class ...", "You need to define...", "You implement the...", "Let's add...". followed by code snippet.

I don't know if that is a good style to use, or if it should be more indirect and describing like "This implements the..." followed by code snippet.

I don't know if we will get navigation for free with the real style. Otherwise we need to add links to next step at the the end of the tutorial pages.

See #11

See #11

I've initiated work to get an Akka design for Antora.

Refs #65

The Overview page should include a section stating what's the target audience.

Later, we could have specific audiences for each section:

• one audience for the tutorial
• one audience for a (basic) HOWTO
• another audience for an advanced HOWTO

The tutorial will probably only cover some unit tests. Integration testing with real Cassandra and Kafka can be a separate "how to recipe"

Even though the tutorial will be thorough and include all source code I think we should provide a download of the full source code for each part. I'm thinking that a zip file with different directories for each part would be nice.

between SendOrderProjection and ShoppingOrderService

see #31

See #21

Enable deploy of the Antora generated site to akka.io/akka-microservies.

The Main of the sample is now creating keyspace and tables automatically, which is not our recommendation for production. Ok to do that from tests.

How should we deal with this for running locally? Easy of running vs the right thing for production?

It will be the starting point for the tutorial and contains:

• build with dependencies and gRPC plugin
• configuration
• empty Main class

Until we have this in place the docs-source/docs/modules/shopping-microservices/examples/empty-shopping-cart-service-scala in branch wip-empty-project-patriknw can be used. https://github.com/akka/akka-platform-guide/tree/wip-empty-project-patriknw/docs-source/docs/modules/shopping-microservices/examples/empty-shopping-cart-service-scala

The purpose of this ticket is to describe an overview of the full example and its pieces. It will be broken down in more concrete tasks.

The example should illustrate the following technical pieces:

• gRPC server
• gRPC client call to another service
• EventSourcedBehavior with Sharding
• Projection that is publishing events to Kafka
• Projection that is updating a query database model

The full example could look like this:

Shopping Cart Service

• CartService provides a gRPC server interface.
• CartEntity represents the individual shopping carts (EventSourcedBehavior with Sharding).
• CartService sends commands to CartEntity with ask via Sharding EntityRef.
• CartEntity stores events in Cassandra journal. (Internal representation in CBOR format.)
• PublishEventsProjection sends all shopping cart events to a Kafka topic. (External representation in protobuf format.)
• PopularityProjection updates a count per item of how many shopping carts that include the item. Representing how popular the item is. The projection is stored in a Cassandra query db, which can be queried from the CartService.
• SendOrderProjection calls the OrderService over gRPC for CheckedOut events. The order should contain the items and quantities of the cart and that can be obtained with an ask to the CartEntity.

Order Service

• OrderService provides a gRPC server interface that is called from the SendOrderProjection. (The example doesn’t have to do anything more than logging here.)

Analytics Service

• AnalyticsService consumes shopping cart events from the Kafka topic with the purpose of producing statistics/reports of customer behavior. (Alpakka Kafka to consume the events.) (The example doesn’t have to do anything more than logging here.)

The example should be introduced step-by-step, with deployment of each step:

• CartService with one gRPC service method and dummy implementation (logging). Use grpcurl to interact with the service.
• Add CartEntity and interaction from CartService.
• Add PublishEventsProjection and AnalyticsService.
• Add SendOrderProjection and OrderService.
• Add PopularityProjection and popularity query from CartService.

(Should the projections be introduced in a different order?)
(Should it start with a single instance and introduce Akka cluster on the way?)

In #85 we added content copy/pasted from https://developer.lightbend.com/docs/introduction/traditional-architecture.html. The page https://github.com/akka/akka-platform-guide/blame/main/docs-source/docs/modules/concepts/pages/concepts-traditional-architecture.adoc should include a canonical tag pointing to the page in https://developer.lightbend.com....

See #11

Replace the old ShoppingCartProjectionHandler and EventProcessor