A backend service that manages remote control devices via a RESTful API
- Java Temurin JDK 25 LTS - programming language
- Apache Maven 3.10.0 - build automation
- Docker 29.9.3 - containers (alpine)
- Editorconfig - source formatting
- Eclipse Vert.x 5.2.3
- PostgreSQL 18.6
- Clone the git repo
git clone git@github.com:george-haddad/remote-control-device.git- Create a
.envfile in the base repo and put the following values
# API
NAME=remote-control-device-api
DB_HOST=db
DB_PORT=5432
DB_NAME=remote-control
DB_USER=devicebackend
DB_PASS=Tablet9-Saddling-Undocked-Glance
HTTP_PORT=8080
# DB
POSTGRES_USER=postgres
POSTGRES_PASSWORD=P@ssW0rd12345
POSTGRES_DB=postgres
The DB_PASS should not be changed as this value is needed to automatically setup the database. This is because the same password is pre-encrypted in the db/database_setup.sql script. This is mainly for convenience, in production this wouldn't be the case.
- Pull the database docker image
docker pull postgres:18.4-alpine3.23- Build the backend
./mvnw clean package- Build the backend docker image
./mvnw jib:dockerBuild- Bring up both docker images
docker compose upThis should run the backend remotecontrol-api and the database remotecontrol-db on the docker network.
- Test the health end-points
Here we expect the backend to be in a degraded state.
curl http://localhost:8080/health --header 'Accept: application/json'The response will show the database is down due to an authentication failure.
{
"status": "DOWN",
"checks": [
{
"id": "event-bus",
"status": "UP",
"checks": [
{
"id": "remotecontrol.devices",
"status": "UP"
}
]
},
{
"id": "database",
"status": "DOWN",
"data": {
"cause": "FATAL: password authentication failed for user \"devicebackend\" (28P01)"
}
},
{
"id": "api",
"status": "UP"
}
],
"outcome": "DOWN"
}- Setup the database
This command will connect to the database as the admin user and setup the following:
- User named
devicebackendwith a pre-encrypted password (the one from the.envfile in step 2.) - Database named
remote-control - Schema named
appin theremote-controldatabase - Grant
devicebackendprivileges to modify theappschema in theremote-controldatabase - Table named
devicesin theappschema
Note: Be sure to enter the postgres admin password from .env file in step 2. and that you have psql binary installed.
psql -h localhost -U postgres -d postgres -a -f db/database_setup.sqlThere should be the output of the SQL script dumped in the terminal.
- Test the health end-points (again)
Here we expect the backend to be in a healthy state.
curl http://localhost:8080/health --header 'Accept: application/json'The response will show that all resources are UP and running!
{
"status": "UP",
"checks": [
{
"id": "event-bus",
"status": "UP",
"checks": [
{
"id": "remotecontrol.devices",
"status": "UP"
}
]
},
{
"id": "database",
"status": "UP"
},
{
"id": "api",
"status": "UP"
}
],
"outcome": "UP"
}- Start using the backend
View the API documentation in src/main/resources/device-spec.yaml.
Note: The reason the spec file is hidden away there is because the backend uses the spec to create its router with route validations as described in the spec. You may upload the spec into an OpenAPI 3.1 render such as Swagger Editor or any other tool that supports the spec.
Note: The below is not accurate anymore, this was the case when I was doing things locally and pushing the images directly to my k3s cluster. Since I installed ArgoCD I started pushing the images to the github registry and ArgoCD picks up the versioned changes from there and auto-deploys to my k3s cluster; gitops style.
Push docker image to local k3s registry
docker save remote-control-api:latest | sudo k3s ctr images import -Stop / Start / Status of your k3s cluster
sudo systemctl [stop|start|status] k3sInstall the remote-control-device as an ArgoCD application
kubectl apply -f argocd-application.yamlRestart pod because image got updated
kubectl rollout restart deployment devices-app -n remote-controlThe RESTful APIs follow OpenAPI spec v3.1.0
See src/main/resources/device-spec.yaml
This is the kubernetes network layout. This application shares a cluster with another application and thus is using the Separate Envoy Gateway Controllers deployment mode. This is done to use the shared cluster as a multi-tenant cluster. The other applications may have a heavily modified envoy gateway. This keeps the gateways isolated from each other. See envoy docs on deployment mode for more information.
Sequence for Add Device
This application uses a mix of SemVer and TrunkVer.
- SemVer: Used to version the main application and to indicate any backwards compatibility
- TrunkVer: Used to version to container images while still using SemVer as a prefix
How the versioning flow looks like:
- A git branch is created
- Code is committed to the branch using commit prefix convention
- Pull Request is created and labeled
- Version in
pom.xmlfile is updated - Pull Request is merged to main branch
- Pipeline runs and repo is tested and built
- Version is checked in pom file, if release is new create
- Github release is automatically created, pom version is SemVer
- Container is publish to registry using SemVer+TrunkVer
- Changelog is created using labels from Pull Requests
- Add resulting container version to k8s deployment manifest, commit and push
- ArgoCD monitors new image declaration and pulls image to cluster for rollout
The 2 verticles are packaged together in the same container. The ApiVerticle is accessible via an HttpServer to process API requests. The DeviceVerticle is connected to the ApiVerticle via the vertx event-bus under a specific address. This verticle consumes messages from the ApiVerticle and owns persistence to the database.
The database is a standard PostgreSQL relational database. The DB is setup in a secure way so that only the DeviceVerticle has access to perform operations on it.
The event-bus supports publish/subscribe, point-to-point, and request-response messaging styles. Messages are sent to an address assigned to the DeviceVerticle. Vertx will then route them to just one of the handlers registered at that address. If there are many handlers registered at the same address then only one will be chosen using a non-strict round-robin algorithm. When a message is received by the DeviceVerticle, and has been handled, it will reply to the message with a result or a failure. Messaging in vertx is done by "best-effort delivery." This means that vertx event-bus sub-system does its best to deliver the messages and won't consciously discard them. This is one reason we use time-outs at every request-response msg and reply. Should anything fail without the other end getting a fail or acknowledge signal, then the timeout will signify a delivery failure to be handled.
However, in case of catastrophic failure of all or parts of the event bus then there will be a possibility that messages might be lost.
The backend is composed of vertx verticles and these are defined by the feature domain. All verticles are configured and deployed by the main verticle. There is an ApiVerticle that acts as the main api-entry point to the backend. From there requests are routed to their appropriate handlers as defined by the OpenAPI v1.3 spec. The handlers send the request to be processed to the DeviceVerticle as a message over the event-bus. The message is then processed and persisted in a database using a shared connection pool. The DeviceVerticle then replies back with a result or an error. There are timeouts set on every msg request/response to ensure fail fast and a responsive experience. The reason to use an event-bus is so that internal verticle communication does not need to be burdened by HTTP overhead.
- MainVerticle
- ApiVerticle
- DevicesHandler
- DevicesHandlerBase
- Device
- DevicesVerticle
- DevicesMessageHandler
- DeviceService
- Device
- ApiVerticle
Follow best practices of git commit messages.
- A commit prefix must be used.
- A commit is composed of 2 parts
- Header - prefix: and a short descriptive title
- Body - separated by a new line after the header
- Commit messages are always in the present tense stating what it does and not what it did.
- Optional message describing the rationale and implications are in the commit message body.
Below is a short and concise list of commit prefixes with a short description.
- feat: Introduces a new feature.
- fix: Patches a bug.
- docs: Documentation-only changes.
- style: Changes that do not affect the meaning of the code (white-space, formatting, etc).
- refactor: A code change that neither fixes a bug nor adds a feature.
- perf: Improves performance.
- test: Adds missing tests or corrects existing tests.
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation.
- build: Changes that affect the build system or external dependencies
- ci: Changes to the CI configuration files and scripts
- revert: Reverts a previous commit.
References
- https://graphite.com/guides/git-commit-message-best-practices
- https://www.conventionalcommits.org/en/v1.0.0/
- https://jabaltorres.com/blog/common-git-message-prefixes/
- https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type
- Table names are plural.
- Column names are singular.
- Table and Column names are in lowercase snake_case.
- Primary and Foreign Keys
- Use underscore to signify relationship tables.
- Prefer schema namespace over prefixing table names.
- Names of attributes must remain consistent across all tables.
- Key names
- Primary Keys names in format of [singular_of_table_name]_id.
- Foreign Keys use same name as the referenced Primary Key.
- Names of attributes must remain consistent across all tables.
- Use underscore to signify relationship tables table_name_to_table_name.
- Prefixes
- Prefer schema namespace over prefixing table names.
- Do not prefix tables.
- Do not prefix columns.


