dodex-akka

doDex-akka, a scala asynchronous/reactive client to doDex-vertx supporting the Cassandra nosql database for Dodex, Dodex-input and Dodex-mess

Install Assumptions

• Java 17 or higher installed with JAVA_HOME set.
• Scala 3.4.2 and sbt installed.
• Node/npm javascript package manager installed.
• Docker(to install a test Cassandra container) or installed Cassandra
• Optionally cqlsh

Motivation and Summary

A maiden voyage into the Scala, Akka and Cassandra world. The Akka client attaches to the Vertx Event Bus Bridge using TCP. Daniel Stieger's project @ https://github.com/danielstieger/javaxbus is used to communicate with the event bus on the Vertx Server. On the Akka side this code was converted to Scala and used to fomulate the message. The development/testing environment uses either a Cassandra container or an installed networked Cassandra. View and change the configuration in application.conf. The asynchronous/reactive code is much like Vertx using Futures and Promises. Conclusion, Akka is a good place to start if you want to learn Scala and the Actor/Behavior pattern. The need for a Dodex database is simple so Cassandra usage barely scratches the surface.

Note; dodex-Akka can be run/developed on most platforms since cqlsh is now supported with python 3.

Getting Started

• Download methods:

  • npm install dodex-akka
  • gh repo clone DaveO-Home/dodex-akka
  • git clone from https://github.com/DaveO-Home/dodex-akka
    If you use npm install, move node_modules/dodex-akka to an appropriate directory.

• Install Cassandra or use the provided script cassDocker.sh to create a Docker container. When using the Docker container, additional Cassandra configuration is not necessary to get started. The Cassandra container runs @ 127.0.0.1:9042.

• Edit src/main/resources/application.conf and change the following;

  • modify cassandra-service host values to reflect a networked Cassandra
  • modify event.bus.dev.host to reflect the location of the development Vertx micro-service
  • modify event.bus.host to reflect the location of the production Vertx micro-service
  • also change the port values if test and production are running on the same machine simultaneously. Make sure the bridge.port value in application-conf.json for the Vertx micro-service corresponds to these values.

• cd <install directory>/dodex-akka and execute sbt to enter the sbt shell and execte run. This should install Scala dependencies and startup the micro-service in development mode against the installed Cassandra database. Review instructions below on Akka development.

• On the Vertx side, make sure dodex-vertx is running with Cassandra database set.

  • Method 1; export DEFAULT_DB=cassandra or Set DEFAULT_DB=cassandra before starting the Dodex-Vertx micro-service.
  • Method 2; change defaultdb to cassandra in database_config.json file before starting vertx.

• With both Vertx and Akka sevices running, execute url http://localhost:8087/test in a browser. To test that the Akka service is working, follow instructions for Dodex-Mess. If the message box displays connected you are good to go.
  Note: The Vertx service is started with Cassandra if the startup message TCP Event Bus Bridge Started is displayed.

• You can also run http://localhost:8087/test/bootstrap.html for a bootstrap example.

• Follow instructions for dodex at dodex-mess and dodex-input.

Using the Vert.x Mqtt Broker and Akka Mqtt Client

• The order of precedence for starting Sbt in development mode to run the Mqtt Client.
  • Execute sbt, set run / fork := true, ~run mqtt=true
  • Execute export USE_MQTT=true, sbt, set run / fork := true, ~run
  • In file src/main/resources/application.conf set use.dev.mqtt=true, execute sbt, set run / fork := true, ~run
    • For production use use.mqtt=true
    • The TCP/Event Bus connection is default.

Note: To start the Vert.x Mqtt Broker, see dodex-vertx README

Operation

• Starting in Dev Mode to test implementation; execute sbt and then run. The dodex-vertx service should be running first, however if dodex-akka is started first, the Akka service will continue attempting the TCP handshake for a limited number of tries. This can be configured in Limits.scala. Conversely, if dodex-vertx is shutdown, the Akka client will continue with attempts to reconnect a limited number of times, frequency can also be configured.

• Starting in Dev Mode to develop; execute sbt to start the sbt shell
  Note: These commands should work when changing Akka code.

  • execute set run / fork := true, this allows the application to reload when shutting down with ctrl-c
  • execute set run / javaOptions += "-Ddev=true" for forked JVM and then execute ~run to start
  • modify some Akka code and execute ctrl-c, while still in the sbt shell and using ~run the Akka service will restart.
  • When changing and restarting the Vert.x service, the Akka service should auto restart.

• Building a Production distribution - Review the sbt plugin documentation for details

  • Try sbt stage this will build a production setup without packaging. You can execute by running target/universal/stage/bin/akka-dodex-scala. Make sure your production database is running.

  • Execute sbt "Universal / packageBin" to package the application. It can then be moved to a proper machine/directory for extraction and execution. The generated package is target/universal/akka-dodex-scala-2.0.zip.

  • Building a fat jar using the assembly plugin requires a hack for an Akka application. Basically the plugin cannot determine the full Akka configuration.

    • Using a Java based package @ https://github.com/DaveO-Home/jin to generate the Fat Jar
    • Jin must be installed in the src directory. The simplist method is to cd src and execute git clone https://github.com/DaveO-Home/jin.git.
    • In the project directory where GenFatJar is located, execute export WD=., export CD=${PWD}/target/classes and mkdir target/classes.
    • Execute ./GenFatJar to build the Fat Jar.
    • The generated jar should be target/scala-3.4.2/akka-dodex-scala-assembly-2.0.jar.
    • Execute scala target/scala-3.4.2/akka-dodex-scala-assembly-2.0.jar to startup production.
    • Or using Java you can execute ./runUber.

Cassandra

• If cqlsh is installed, to access the local database, this might be useful - cqlsh 127.0.0.1 --cqlversion=3.4.6 --encoding=utf8.
• For a Cassandra 4 setup this might be useful - cqlsh <production host> 9042 --cqlversion="3.4.6".
• Other wise just execute cqlsh, use dodex; and describe tables;.

Test Dodex

• Make sure the demo Java-vertx server is running in development mode.
• Test Dodex-mess by entering the URL localhost:3087/test/index.html in a browser.
• Ctrl+Double-Click a dial or bottom card to popup the messaging client.
• To test the messaging, open up the URL in a different browser and make a connection by Ctrl+Double-Clicking the bottom card. Make sure you create a handle.
• Enter a message and click send to test.
• For dodex-input Double-Click a dial or bottom card to popup the input dialog. Allows for uploading, editing and removal of private content. Content in JSON can be defined as arrays to make HTML more readable.

Optimizing with Graalvm

• See https://www.scala-sbt.org/sbt-native-packager/formats/graalvm-native-image.html to implement.

Single Page React Application to demo Development and Integration Testing

• For details see https://github.com/DaveO-Home/dodex-vertx/blob/master/src/spa-react/README.md
• In the vertx directory .../src/spa-react/devl, the following commands can be executed, assuming the the app was installed in "spa-react" by running npm install.
• After setting the database to cassandra, co-ordination among Akka, Vertx and React builds is difficult to automate. Therefore using npx gulp test and npx gulp prod will not work. For a test build use npx gulp rebuild and once Vertx and Akka are restarted, tests can be executed with npx gulp acceptance. For the React production build, use npx gulp prd.

Additional References

• Scala, Sbt, Akka and Cassandra documentation.

  • Scala; https://docs.scala-lang.org/overviews/index.html
  • sbt; https://www.scala-sbt.org/1.x/docs/index.html
  • Akka; https://doc.akka.io/docs/akka/current
  • Cassandra; https://cassandra.apache.org/doc/latest/
  • sbt native plugin; https://www.scala-sbt.org/sbt-native-packager/gettingstarted.html

ChangeLog

https://github.com/DaveO-Home/dodex-akka/blob/master/CHANGELOG.md

Authors

• Initial work - DaveO-Home

License

This project is licensed under the MIT License - see the LICENSE file for details