Getting Started

Our dev environment can be used in two ways Docker or Local Installation

• With Docker you don't need to worry about the dependencies needed to run the environment. All you need is Docker.
• With the local installation you get more fine-grained control over your local environment E.g. Limiting the JVM heap size, specifying custom JVM args, and anything else you can come up with. But you have to maintain the local installation yourself. No additional services will be installed or started automatically.

Docker creates OS-level virtualization which allows it to function in it own contained environment and does not touch any of your computer files. The local installation does touch some of our your computers own files, but you get the benefit of speed. Since Docker always creates a new container each time you run a command it is naturally slower than if you run the commands without virtualization and locally stored caches.

Setup

Docker

We set up our Docker environment to be easy to work with. When you start the container it will start a process that listens for change under your classpath, once a change is detected it will automatically rebuild the changed files and restart the servlet container (in our case Tomcat). This allows a simple and easy development process because you never have to rebuild manually, the container knows what it needs to do and it does it for you.

To use Docker, follow these steps:

1. Run docker-compose up -d
2. Then navigate to http://localhost:8080/ in your browser to see the application running.

If you want to run tests it's as easy as

docker-compose run gradle test

If you want to do test driven development you can run

docker-compose run gradle -t test

the -t watches for changes and runs the same command again when a change happens.

NOTE: The first time you run the docker-compose command it will take a bit longer to start so be patient

Local Installation

NOTE: We don't recommend the local installation unless you have worked with Gradle and/or other JVM-based languages before.

The local installation offers more control and more configuration for your own development environment, but we update the Java versions without warning so make sure to keep your local environment up to date and check this guide periodically so you can migrate to the new requirements.

To install locally, follow these steps:

1. Install Java 15
   1. Pro Tip: To manage multiple versions of Java, you can use Jenv.
2. Run ./gradlew bootRun
3. Navigate to http://localhost:8080/ in your browser to see the application running

If you want to run tests it's as easy as ./gradlew test. If you want to do test driven development you can run ./gradlew -t test the -t watches for changes and runs the same command again when a change happens.

After setup

Once everything is working, and you have navigated to http://localhost:8080/ you should see the root API resource in a hal+json format. If you don't see that check the troubleshooting section.

Troubleshooting

When docker-entrypoint.sh runs it will output two log files spring-build.log and spring-run.log (we recommend running tail -f on these files for a more detailed output).

The logs will give you more information about what is going on inside the application.

• spring-build.log informs you in case you have any compile-time errors happening in your code such as syntax or type errors, missing dependencies, etc.
• spring-run.log informs you about the runtime errors such as webserver exceptions, and the Tomcat access log.

If you are having any issues setting up odds are one of these two files will tell you what you need to do.

Debugging

We have added JVM args to the bootRun task. These JVM args enable something called JPDA (Java Platform Debugger Architecture) this allows you to add breakpoints in your code witch get triggered when that part of the code executes.

(Check the documentation for your code editor or IDE for more information about how to set up JPDA).

These are the JVM args we used to enable JPDA:

-Xdebug -Xrunjdwp:transport=dt_socket,address=*:5005,server=y,suspend=n

Reference Documentation

For further reference, please consider the following sections:

• Official Gradle documentation
• Spring Boot Gradle Plugin Reference Guide
• Create an OCI image
• WebSocket

Guides

The following guides illustrate how to use some features concretely:

• Using WebSocket to build an interactive web application

Additional Links

These additional references should also help you:

• Gradle Build Scans – insights for your project's build