dodex-quarkus
An asynchronous server for Dodex, Dodex-input and Dodex-mess using the Quarkus Supersonic Subatomic Java Framework.
Install Assumptions
- Java 11 or higher installed with JAVA_HOME set.
- Gradle 6+ installed. If you have sdkman installed, execute
sdk install gradle 6.9
otherwise executing gradlew should install gradle. - The
npm
javascript package manager installed.
Note: The static directory was changed from src/main/resources/static
to src/main/resources/META-INF/resources
in compliance with v2.5.
Getting Started
-
npm install dodex-quarkus
or download from https://github.com/DaveO-Home/dodex-quarkus. If you use npm install, move node_modules/dodex-quarkus to an appropriate directory. -
cd <install directory>/dodex-quarkus/src/main/resources/META-INF/resources
and executenpm install --save
to install the dodex modules. -
cd <install directory>/dodex-quarkus
and executegradlew quarkusDev
. This should install java dependencies and startup the server in development mode against the default sqlite3 database. In this mode, any modifications to java source will be recompiled(refresh browser page to recompile). -
Execute url
http://localhost:8089/test
in a browser. -
You can also run
http://localhost:8089/test/bootstrap.html
for a bootstrap example. -
Follow instructions for dodex at https://www.npmjs.com/package/dodex-mess and https://www.npmjs.com/package/dodex-input.
-
The Cassandra database has been added via an
Akka
micro-service. See; https://www.npmjs.com/package/dodex-akka. -
Added Cassandra database to the
React
demo allowing thelogin
component to use Cassandra. -
See the
Firebase
section for using Google'sFirestore
backend.Note: In dev mode(
gradlew quarkusDev
), when modifying Java code, all you have to do is refresh the browser window. You can also usegradlew run
to set ENVIRONMENT variables first.See: Single Page React Section below on using Dodex in an SPA.
Operation
-
Execute
gradlew tasks
to view all tasks. -
Building the Production Uber jar
- Before running the Uber jar for production, do: (graalvm requires the Uber jar)
- Make sure that the spa react javascript is installed. Execute
npm install
in thesrc/spa-react
directory. - cd to src/spa-react/devl & execute
gulp prod
orgulp prd
(bypasses tests) ornpx gulp prod
-
npm install
must also populate thenode_modules
directory insrc/main/resources/META-INF/resources
- (optional) rm src/spa-react/node_modules (makes a smaller uber jar)
- Make sure that the spa react javascript is installed. Execute
- Execute
./gradlew quarkusBuild -Dquarkus.package.type=uber-jar
to build the production fat jar.
- Before running the Uber jar for production, do: (graalvm requires the Uber jar)
-
Execute
java -jar build/dodex-quarkus-2.1.0-runner.jar
to startup the production server. -
Execute url
http://localhost:8088/ddex/index.html
or.../ddex/bootstrap.html
in a browser. Note; This is a different port and url than development. Also Note; The default database on the backend is "Sqlite3", no further configuation is necessay. Dodex-quarkus also has Postgres/Cubrid/Mariadb/DB2/H2 implementations. See<install directory>/dodex-quarkus/src/main/resources/database_config.json
for configuration. -
Swapping among databases; Use environment variable
DEFAULT_DB
by setting it to eithersqlite3
,postgres
,cubrid
,mariadb
,ibmdb2
,h2
,cassandra
,firebase
or set the default database indatabase_config.json
. -
When Dodex-quarkus is configured for the Cubrid database, the database must be created using UTF-8. For example
cubrid createdb dodex en_US.utf8
. -
The dodex server has an auto user clean up process. See
application-conf.json
andDodexRouter.java
for configuration. It is turned off by default. Users and messages may be orphaned when clients change a handle when the server is offline.
Java Linting with PMD
- Run
gradlew pmdMain
andgradlew pmdTest
to verify code using a subset of PMD rules indodexstart.xml
- Reports can be found in
build/reports/pmd
Single Page React Application to demo Development and Integration Testing
- Integrated in Dodex-Quarkus at
src/spa-react
- Documentation https://github.com/DaveO-Home/dodex-quarkus/blob/master/src/spa-react/README.md
- Uses Sqlite3 as default backend database
- Router added to
src/main/java/dmo/fs/router/DodexRoutes.java
, see theinit
method.
Debug
- Executing
gradlew quarkusDev
defaults to debug mode. - Tested with VSCode, the
launch.json
=
{
"type": "java",
"name": "Debug (Launch) - Dodex",
"request": "attach",
"hostName": "localhost",
"port": 5005
}
Test Dodex
- Make sure the demo Java-quarkus server is running in development mode.
- Test Dodex-mess by entering the URL
localhost:8089/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.
Native execution with Graalvm
The quarkus documentation can be found at: https://quarkus.io/guides/building-native-image
A quick start (Assuming graalvm 21+ is installed and configured with native-image
):
The Quarkus Method: Execute gradlew build -Dquarkus.package.type=native
. The additional arguments are in application.properties
(quarkus.native.additional-build-args). The build fails with numerious errors.
The Old Fashion Method: Execute the supplied script - dodexvm11
. This will build an executable named dmo.fs.quarkus.Server
. This script should work, however it uses the fallback javaVM.
Docker, Podman and Minikube(Kubernetes)
- Assumes
docker
,podman
andminikube
are installed
-
image
andcontainer
withdocker
-
cd to the
dodex-quarkus
install directory -
make sure
dodex
and thespa-react
node_modules and application are installed- in
src/main/resources/META-INF/resources
executenpm install
- in
src/spa-react
executenpm install
- startup Quarkus in dev mode -
gradlew quarkusDev
- in
src/spa-react/devl
executegulp prod
orgulp prd
- stop the quarkus server - ctrl-c or enter
q
- build the production uber jar -
./gradlew quarkusBuild -Dquarkus.package.type=uber-jar
- verify the jar's name - if different than
dodex-quarkus-2.1.0-runner.jar
, change in./kube/Dockerfile
- in
-
execute
docker build -t dodex-quarkus:latest -f kube/Dockerfile .
-
execute
docker create -t -p 8088:8088 --name dodex_quarkus dodex-quarkus
-
execute
docker start dodex_quarkus
-
use browser to view - http://localhost:8088/ddex or http://localhost:8088/ddex/bootstrap/html, if the spa-react was installed this link should work, http://localhost:8088/dist/react-fusebox/appl/testapp.html
-
execute
docker stop dodex_quarkus
-
to clean-up execute
docker rm dodex_quarkus
anddocker rmi dodex-quarkus
-
to pull and generate a local image from the docker hub,
execute docker build -t dodex-quarkus:latest -f kube/quarkus/Dockerfile .
-
-
image
andcontainer
withpodman
- generate an empty pod execute
podman pod create -n quarkus-pod -p 0.0.0.0:8088:8088
- generate a container execute
podman create -t --pod quarkus-pod --name quarkus_server dodex-quarkus:latest
Note; if there is not a local image, usedufferdo2/dodex-quarkus:latest
to pull from the docker hub. - start the container execute
podman start quarkus_server
- view in browser
- to clean-up execute
podman stop quarkus_server
,podman rm quarkus_server
,podman pod rm quarkus-pod
- before cleaning up, generate a yaml file for
minikube
, executepodman generate kube quarkus_pod > quarkus.yml
- generate an empty pod execute
-
deployment
andservice
withminikube
-
minikube
can be forced to pull from a local registry, however for this exerciseminikube
pulls from the docker hub,dufferdo/dodex-quarkus
- execute
minikube start
- create a deployment with auto generated pod, execute
kubectl create deployment quarkus-depl --image=dufferdo2/dodex-quarkus:latest
- create a service from deployment, execute
kubectl expose deploy quarkus-depl --name=quarkus-service --port 8088 --target-port 8088 --type=NodePort
- to find the generated pod name, execute
kubectl get pod
- to run in default browser, execute
minikube service quarkus-service
- to get the ip:port to use, execute
minikube service quarkus-service --url
- view in browser
- clean-up execute
kubectl delete svc quarkus-service
,kubectl delete deploy quarkus-depl
,docker rmi dufferdo/dodex-quarkus
- execute
minikube stop
Note; From the the above
quarkus.yml
file, a pod can be created, executekubectl create -f quarkus.yml
and the servicekubectl expose po quarkus-pod --name=quarkus-service --port 8088 --target-port 8088 --type=NodePort
. Make sure the image entry inquarkus.yml
isimage: dufferdo2/dodex-quarkus:latest
. Optionally add the following afterimage:...
-imagePullPolicy: IfNotPresent
. If not working, trykubectl port-forward svc/quarkus-service 8088:8088
and view withlocalhost:8088
. Depending on your setup, the following may be needed;eval $(minikube -p minikube docker-env)
- execute
Firebase
- Create an account: https://firebase.google.com
- Getting started: https://firebase.google.com/docs/admin/setup#java
- Make sure you create a
Service-Account-Key.json
file as instructed. Dodex-Vertx uses the environment variable option to set the service-account -GOOGLE_APPLICATION_CREDENTIALS
. See gradle.build as one way to set it. - You will need to login to the
Firebase
console and create thedodex-firebase
project. Seesrc/main/java/dmo/fs/router/FirebaseRouter.java
for usage of the project-id and Google Credentials. Note; TheFirebase
rules are not used, so they should be set toallow read, write: if false;
which may be the default. - You only need the
Authentication
andFirestore
extensions. - If you want a different project name, change
.firebaserc
. - Gradle for development can set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable if you execgradlew run
instead ofgradlew quarkusDev
. Don't forget to modify the build.gradle file with the location of yourService-Account-Key.json
file.
Firebase Testing
- To make sure your project is created and the setup works, you should run the tests. Note; They are written in Typescript.
- cd
../dodex-vertx/src/firebase
and runnpm install
- execute
npm run emulators
to startup the emulators for testing. - To test the model and rules after starting the emulators, in a different terminal window, run
npm test
.
Neo4j
- See http://quarkus.io/guides/neo4j for usage.
- To use a docker with
apoc
you can try: Note: this has--privileged
set.docker run \ -p 7474:7474 -p 7687:7687 \ -v $PWD/neo4j/data:/neo4j/data -v $PWD/neo4j/plugins:/neo4j/plugins \ --name neo4j-apoc \ --privileged \ -e 'NEO4J_AUTH=neo4j/secret' \ -e NEO4J_apoc_export_file_enabled=true \ -e NEO4J_apoc_import_file_enabled=true \ -e NEO4J_apoc_import_file_use__neo4j__config=true \ -e NEO4JLABS_PLUGINS=\[\"apoc\"\] \ -e NEO4J_dbms_security_procedures_unrestricted=apoc.\\\* \ neo4j:4.3
To restart and stop: docker start neo4j-apoc
and docker stop neo4j-apoc
The Neo4j was tested with the apoc
install, however the database should work without it.
Simply execute export DEFAULT_DB=neo4j
to use, after database setup.
Dodex Monitoring
Getting Started
-
Apache Kafka must be installed.
- Kafka Quickstart - A container should also work
- .../config/server.properties should be modified if using a local install
- advertised.listeners=PLAINTEXT://localhost:9092
- num.partitions=2 # at least 2
- local startup
- ./bin/zookeeper-server-start.sh config/zookeeper.properties
- ./bin/kafka-server-start.sh config/server.properties
-
Setup Quarkus for Kafka
- set environment variable
DODEX_KAFKA=true
- Modify Quarkus application.properties file
- uncomment the
mp.messaging
entries - modify the server entries if necessary
- uncomment the
- startup Quarkus - the monitor should work with any of the databases
- the monitor configuation can be found in
application-conf.json
- set environment variable
-
Monitor Dodex
- in a browser enter
localhost:8089/monitor
orlocalhost:8088/monitor
in production. - as dodex messaging executes the events should be recorded.
- in the browser's
developer tools
console executestop();
andstart();
to stop/start the polling. Polling is started by default.
Note; you can open the messaging dialog with
ctrl-doubleclick
on the dials - in a browser enter
ChangeLog
https://github.com/DaveO-Home/dodex-quarkus/blob/master/CHANGELOG.md
Authors
- Initial work - DaveO-Home
License
This project is licensed under the MIT License - see the LICENSE file for details