dodex-quarkus
v3.4.1
Published
A java asynchronous server for Dodex using quarkus
Downloads
1,156
Maintainers
Readme
dodex-quarkus
An asynchronous server for Dodex, Dodex-input and Dodex-mess using the Quarkus Supersonic Subatomic Java Framework.
Install Assumptions
- Java 17+ installed with JAVA_HOME set.
- Gradle 8+ installed. If you have sdkman installed, execute
sdk install gradle 8.8
otherwise executing gradlew should install gradle. - Javascript node with npm package manager installed.
Note: The Spa React Production demo url has changed to: **`localhost:8089/spa/react-fusebox/appl/testapp.html
Getting Started
Important: Jakarta websocket has been replaced with Quarkus-WebSocket-Next. As a result, dodex-quarkus implements conditional annotations for a given database and now requires the DEFAULT_DB
to be set, e.g. export DEFAULT_DB=h2
. This allows for the removal of stringy code to filter the configuration.
Quick Getting Started with Docker
- Execute
docker build -t dufferdo2/dodex-quarkus:latest -f kube/quarkus/Dockerfile ./kube
-- see install steps inBuilding dodex-quarkus
below. - Execute
docker run -d -p 8088:8088 -p 8071:8071 -p 9901:9901 --name dodex_quarkus dufferdo2/dodex-quarkus
- View in browser; localhost:8088/ddex or localhost:8088/ddex/bootstrap.html or localhost:8088/handicap.html
- To verify that the image is working, execute
docker exec -ti --tty dodex_quarkus /bin/sh
and thencat logs/quarkus.log
- To keep and run later, execute
docker stop dodex_quarkus
and laterdocker start dodex_quarkus
- To cleanup execute
docker stop dodex_quarkus
anddocker rm dodex_quarkus
anddocker rmi dufferdo2/dodex-quarkus
anddocker rmi envoyproxy/envoy:v1.25.0
Building dodex-quarkus
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
runexport DEFAULT_DB=sqlite3
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 the login component to use Cassandra.
- See the Firebase section for using Google's Firestore backend.
- To generate
jooq
code, setDEFAUT_DB=sqlite3
and execute./gradlew jooqGenerate
. The code is generated tosrc/main/kotlin/golf/handicap/generated
.
Note: In dev mode(gradlew quarkusDev
), when modifying Java code, all you have to do is refresh the browser window. You can also use gradlew run
(in build.gradle) 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:
- Make sure that the spa react javascript is installed. Execute
npm install --legacy-peer-deps
in thesrc/spa-react
directory. - cd to src/spa-react/devl & execute
npx gulp prod
ornpx gulp prd
(bypasses tests)` 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 -Pquarkus.package.jar.enabled=true -Dquarkus.package.jar.type=uber-jar
to build the production fat jar. - Or just execute
gradlew quarkusBuild
since the config inapplication.properties
is setup to default to a uber-jar.- Important When building the Uber jar, set DEFAULT_DB=h2 or mariadb or postgres and USE_HANDICAP=true
- Before running the Uber jar for production, do:
Execute
java -jar build/dodex-quarkus-3.11.2-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 must be set because of conditionalweb-socket-next
configuration, e.g. DEFAULT_DB=h2. Dodex-quarkus also has Postgres/Cubrid/Mariadb/DB2/H2/Cassandra/Neo4j/firebase implementations. See<install directory>/dodex-quarkus/src/main/resources/database_config.json
and<install directory>/generate/src/main/resources
for configuration.Swapping among databases; Use environment variable
DEFAULT_DB
by setting it to eithersqlite3
,postgres
,cubrid
,mariadb
,ibmdb2
,h2
,cassandra
,firebase
,neo4j
. You can also use command line args, e.g../gradlew quarkusDev -DDEFAULT_DB=mariadb -DUSE_HANDICAP=true
.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.
Important Note: Since building jooq
source code, the database configurations from the .../dodex-quarkus/generate project may override the database_configs in the the dodex/spa configurations. When making a change to src/main/resources/database_(spa)_config.json
also make the change in generate/src/main/resources
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
- Set DEFAULT_DB=h2 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 dodex-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.jar.type=native
. Additional arguments can be supplied in application.properties
(quarkus.native.additional-build-args). Currently the build fails with numerous errors.
Note: The gRPC application uses the JOOQ
object generator which causes issues with GraalVM
.
Docker, Podman and Minikube(Kubernetes)
- Assumes docker, podman and minikube are installed
Building an image and container with docker
cd to the
dodex-quarkus
install directorymake sure dodex and the spa-react node_modules and application are installed
- in
src/main/resources/META-INF/resources
executenpm install
- in
src/spa-react
executenpm install --legacy-peer-deps
- startup Quarkus in dev mode -
gradlew quarkusDev
- in src/spa-react/devl execute
npx gulp prod
ornpx gulp prd
(does not need dodex-quarkus started) - stop the quarkus server - ctrl-c or enter
q
- build the production uber jar -
./gradlew quarkusBuild -Dquarkus.package.type=uber-jar
- Important When building the Uber jar, set DEFAULT_DB=h2 or mariadb or postgres and USE_HANDICAP=true
- verify the jar's name - if different than
dodex-quarkus-2.1.0-runner.jar
, change in./kube/Dockerfile
- in
execute
cp build/dodex-quarkus-3.3.0-runner.jar
to ./kubeexecute
docker build -t dufferdo2/dodex-quarkus:latest -f kube/Dockerfile ./kube
execute
docker create -t -p 8088:8088 -p 8071:8071 -p 9901:9901 --name dodex_quarkus dufferdo2/dodex-quarkus
execute
docker start dodex_quarkus
use browser to view - http://localhost:8088/handicap.html or http://localhost:8088/ddex or http://localhost:8088/ddex/bootstrap.html, if the spa-react was installed this link should work, http://localhost:8088/spa/react-fusebox/appl/testapp.html
execute
docker stop dodex_quarkus
to clean-up execute
docker rm dodex_quarkus
anddocker rmi dodex-quarkus
. However you should keep the dufferdo2/dodex-quarkus image if trying out podman or minikube.to pull and generate a local image from the docker hub, execute
docker build -t dodex-quarkus:latest -f kube/quarkus/Dockerfile .
you can also build/run dodex-quarkus(image) and dodex_quarkus(container) with;
docker compose -f kube/docker-compose.yaml up -d
Use
run
to test different databases;docker run --rm -p 8088:8088 -p 8071:8071 -p 9901:9901 -e DEFAULT_DB=postgres -e USE_HANDICAP=true --name dodex_quarkus dufferdo2/dodex-quarkus
. To stop, rundocker container stop dodex_quarkus
.
Note: When running a dufferdo2/dodex-quarkus image, there is no need to have envoy running on the machine. Envoy is included in the image.
Building an image and container with podman
- generate an empty pod execute
podman pod create -n quarkus-pod -p 0.0.0.0:8088:8088 -p 0.0.0.0:8071:8071 -p 9901:9901
- generate a container execute
podman create -t --pod quarkus-pod --name quarkus_server dufferdo2/dodex-quarkus:latest
. - 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, you can generate a yaml template. Execute
podman generate kube quarkus_pod > quarkus.yaml
Building a deployment, service and persistent volume with minikube
- Since including the Handicap application(multiple exposed ports, persistent volume) to dodex-quarkus, the minikube deployment must be from configuration files.
- execute
minikube start
- edit kube/quarkus.yml and change env: to desired database(DEFAULT_DB) - defaults to h2(embedded), no database configuration necessary otherwise set DEFAULT_DB to mariadb or postgres
- execute
kubectl create -f kube/h2-volume.yml
- execute
kubectl create -f kube/quarkus.yml
- execute
minikube service quarkus-service
to start dodex-quarkus in the default browser - add --url to get just the URL - verify that dodex-quarkus started properly - execute
./execpod
andcat ./logs/quarkus.log
- enterexit
to exit the pod
For postgres make sure postgres.conf has entry:
listen_addresses = '*' # what IP address(es) to listen on;
and pg_hba.conf has entry:
host all all <ip from minikube vertx-service --url>/32 <whatever you use for security> (default for dodex-vertx "password")
and database_config.json(also in ../dodex-vertx/generate...resources/database(_spa)_confg.json) entry: postgres... (both dev/prod)
"config": {
"host": "<ip value from `hostname -i`>",
netstat -an |grep 5432
should look like this
tcp 0 0 0.0.0.0:5432 0.0.0.0:* LISTEN
tcp6 0 0 :::5432 :::* LISTEN
unix 2 [ ACC ] STREAM LISTENING 57905233 /var/run/postgresql/.s.PGSQL.5432
unix 2 [ ACC ] STREAM LISTENING 57905234 /tmp/.s.PGSQL.5432
Development
- Make changes to the dodex-quarkus code
- execute
gradlew clean
- build the uber jar and image as described in the Operation and Building an image and container with docker sections, e.g.
- build the production uber jar -
./gradlew quarkusBuild -Dquarkus.package.type=uber-jar
- Important When building the Uber jar, set DEFAULT_DB=h2 or mariadb or postgres and USE_HANDICAP=true
- verify the jar's name - if different than dodex-quarkus-3.3.0-runner.jar, change in ./kube/Dockerfile
- copy the build/dodex-quarkus-3.3.0-runner.jar to ./kube
- if the dodex_quarkus and/or the dufferdo2/dodex-quarkus exist, remove them
docker rm dodex_quarkus
anddocker rmi dufferdo2/dodex-quarkus
- build the image
docker build -t dufferdo2/dodex-quarkus:latest -f ./kube/Dockerfile ./kube
- build the production uber jar -
- execute
./deleteapp
- execute
minikube image rm dufferdo2/dodex-quarkus
- execute
minikube load image dufferdo2/qodex-quarkus
- execute
kubectl create -f kube/quarkus.yml
- execute
minikube service quarkus-service
- clean-up execute
./deleteapp
,kubectl delete pvc quarkus-pvc
,kubectl delete pv quarkus-pv
- execute
minikube stop
Exposing the minikube dodex-quarkus container to the internet
- cd .../dodex-quarkus and execute
npm install
- this will install localtunnel - execute
minikube service quarkus-service --url
to view the local host ip address - can be used for the --local-host value - in separate terminals
- execute
npx localtunnel --host https://localtunnel.me --subdomain my-app --port 30088 --local-host $(minikube service quarkus-service --url | cut -d":" -f2 | cut -d"/" -f3)
- for the gRPC tunnel, execute
npx localtunnel --host https://localtunnel.me --subdomain my-app2 --port 30071 --local-host $(minikube service quarkus-service --url | cut -d":" -f2 | cut -d"/" -f3)
- the --subdomain for my-app and my-app2 should be changed to unique values
- the naming convention is required(otherwise edit src/grpc/client/js/client.js and tweak) e.g. coolapp for port 30088 and coolapp2 for port 30071
- view https://YOUR-UNIQUE-APP.loca.lt or https://YOUR-UNIQUE-APP.lt/handicap.html in browser
- 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-quarkus/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
Dodex Groups using OpenAPI
- A default javascript client is included in .../dodex-quarkus/src/main/resources/static/group/. It can be regenerated in .../dodex-quarkus/handicap/src/grpc/client/ by executing
npm run group:prod
. - The group javascript client is in .../src/grpc/client/js/dodex/groups.js and group.js.
Note: The client is included in the Handicap application by default. - See .../src/main/resources/META-INF/openapi.yaml for OpenAPI declarations. You and view the configuration for development at
localhost:8089/q/swagger-ui/
. - The implementation uses a
rest
api in theOpenApiRouter
class.
Installing in Dodex
- Implementing in a javascript module; see .../dodex-quarkus/handicap/src/grpc/client/js/dodex/index.js
import { groupListener } from "./groups";
- in the dodex init configuration, add
... .then(function () { groupListener(); ...
- Implementing with inline html; see .../dodex-quarkus/main/resources/test/index.html
<script src="../group/main.min.js"></script>
- in the dodex init configuration, add
... .then(function () { window.groupListener(); ...
- Using dodex-messaging group functionality
Note: Grouping is only used to limit the list of "handles" when sending private messages.
- Adding a group using
@group+<name>
- select Private Message from the more button dropdown to get the list of handles.
- enter
@group+<name>
for example@group+aces
- select the handles to include and click "Send". Members can be added at any subsequent time.
- Removing a group using
@group-<name>
- enter
@group-<name>
for example@group-aces
and click "Send". Click the confirmation popup to complete.
- enter
- Removing a member
- enter
@group-<name>
for example@group-aces
- select a "handle" from the dropdown list and click "Send"
- enter
- Selecting a group using
@group=<name>
- enter
@group=<name>
for example@group=aces
and click "Send" - Select from reduced set of "handles" to send private message.
- enter
Note: By default the entry "dodex.groups.checkForOwner"
in application-conf.json is set to false. This means that any "handle" can delete a "group" or "member". Setting the entry to true prevents global administration, however, if the owner "handle" changes, group administration is lost.
Also, Groups will work with "sqlite3" without setting USE_HANDICAP=true. For 'h2', 'mariadb' and 'postgres', USE_HANDICAP=true is required.
Kotlin, gRPC Web Application
This web application can be used to maintain golfer played courses and scores and to calculate a handicap index. The application has many moving parts from the envoy proxy server to kotlin, protobuf, gRPC, jooq and code generator, bootstrap, webpack, esbuild, gradle, java and javascript.
See documentation at: https://github.com/DaveO-Home/dodex-quarkus/blob/master/handicap/README.md
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