Setting up your local develop environment
When you want to contribute to the LITTIL API you need some tools in order to run the API locally. The API is written in JAVA, based on Quarkus. For data persistence we use a Mysql database.
Don't worry about installing these extra dependencies, when running in dev mode those will be automatically installed
in a docker container for you.
Prerequisites
Before you are able to run the API of LITTIL you need to make sure you have the following software installed on your machine. - Java 17 - Maven - Docker - Quarkus cli
SDKMAN!
SDKMAN! is an util which you can use on all unix based systems. This includes all Linux distributions, but also MacOS.
SDKMAN! makes it really easy to not only install Java on your machine but most utilities which are commonly used within
the Java eco-environment. You can use the following guide to install SDKMAN! on your machine:
You can install SDKMAN! by running the following command on your machine:
To use SDKMAN! you can either run the command below or restart your terminal.
Run the following code snippet to ensure that installation succeeded:
Java
Unix
To see which versions are available for java run:
Then install the latest java 17 version, i.e:
For more information regardingSDKMAN! please visit their website at: https://sdkman.io/
if you which to install java directly you can also download it directly from the Oracle website.
Windows
Please contribute
Maven
This projects ships a Maven wrapper. With this wrapper it's not necessary to install maven locally on your machine.
To run maven on unix use $ ./mvnw <parameters> on a Windows machine your can use $ ./mvnw.cmd <parameters>.
Quarkus CLI
Quarkus ships an CLI tool for better developing experience. This tool is not mandatory in order to work locally on the LITTIL API project. But in case you would like to use it you should follow the instructions below:
Unix
SDKMAN! ships the quarkus cli tool as well. The easiest way to install this tool is by using SDKMAN!. Run the following
command in your terminal to see which versions are available
Then install the desired version, in example:
To verify the installation is successful, run:
Windows
The recommended way to install on Windows is via JBang using the powershell. You can simply run:
If you already have JBang installed on your windows machine you can run:
For more information, please read: Quarkus cli-tooling
Docker
Quarkus uses Docker to spin up containers of middleware which the LITTIL API depends on. For example the mysql
database for persisting data. In order to run these containers Docker must be installed on your machine.
MacOS & Windows
The easiest way to install docker on your Windows or MacOS machine is by installing docker-desktop. You can find the installation files on docker download page.
Linux
Please see the following documentation on how to get Docker installed on your preferred Linux distribution: Official Docker Documentation
Run the LITTIL API locally
Now, with all dependencies installed you can start the API for local development. You use either Maven via:
Or via the quarkus-cli tool
If you run into issues regarding the fact the docker daemon can not be found. Please see: Docker daemon not running
To verify that the environment is running, open your web-browser en go to the health-check.
If the response includes a status:UP you are good to go!
Common used commands
The following commands are useful when contributing to the LITTIL API. You should run these within the project directory.
- $ ./quakus dev / $ ./mvnw quarkus:dev for starting your development environment.
- $ ./quakus build [--native] --[no-]tests / $ ./mvnw quarkus:build [-D[no-]tests] [-Dnative] to build an artifact.
the native and (no-)test parameters are optional.
- $ ./quarkus test / $ ./mvnw quarkus:test to run all tests
For more commands you can run $ ./quarkus --help / $ ./mvnw quarkus:help
Environment variables
Some Quarkus configuration is injected via environment variables so that the same application can run on any environment. To make it easy the configuration has a fallback when no environment variables are found. Those configurations are only applicable for the development (local) environment. Though, some configuration (such as passwords or keys) should not exist within the code.
Booting the application without these configuration will result in errors. To make it easy to set up environment variables
Quarkus has multiple options. Working with an local .env file is recommended. How to implement this in your local environment
is described on the quarkus official documentation site.
You can copy the .env.example file and season it with the correct values to config Auth0
Make sure you never commit this .env file to the repository since it contains sensitive information.
Known issues
Docker daemon not running
If you are developing on a Linux Ubuntu (distro) you might run into issues with Docker for example when running tests. The tests will fail, and you will see logging about the docker daemon. This is due to the fact docker-daemon requires root permissions.
ERROR [org.tes.doc.DockerClientProviderStrategy] (build-4) Could not find a valid Docker environment. Please check configuration. Attempted configurations were:
ERROR [org.tes.doc.DockerClientProviderStrategy] (build-4) UnixSocketClientProviderStrategy: failed with exception TimeoutException (Timeout waiting for result with exception). Root cause LastErrorException ([13] Permission denied)
ERROR [org.tes.doc.DockerClientProviderStrategy] (build-4) As no valid configuration was found, execution cannot continue
---
WARN [io.qua.dat.dep.dev.DevServicesDatasourceProcessor] (build-29) Please configure the datasource URL for the default datasource or ensure the Docker daemon is up and running.
Recoverable I/O exception (java.io.IOException) caught when processing request to {}->unix://localhost:2375
If you see this you are probably running Quarkus within your IDE or use the terminal utility of your IDE.
To solve this issue you can either: - configure Docker for rootless mode. For more information see: Docker rootless (unfortunately, this does not always solve the issue); - or run Quarkus from your OS terminal.