Developer Guide: Preparing the environment

A Docker host is required to work on the main OpenRemote repository. We are using Docker Compose for most deployment tasks.

An installation of Java 8 (OpenJDK, Oracle Java SE JDK) is also required.

All Docker and Gradle commands must be executed in the project root directory.

Configuring a Docker host

You should be able to execute docker, docker-compose, and ideally docker-machine client commands in a shell and communicate with your Docker host.

If you don't have a Docker host, we recommend installing Docker Community Edition. Our default configuration is prepared for that environment.

Working with Docker might leave exited containers, untagged images, and dangling volumes. The following bash function can be used to clean up:

function dcleanup(){
    docker rm -v $(docker ps --filter status=exited -q 2>/dev/null) 2>/dev/null
    docker rmi $(docker images --filter dangling=true -q 2>/dev/null) 2>/dev/null
    docker volume rm $(docker volume ls -qf dangling=true 2>/dev/null) 2>/dev/null
}

Importing the project in an IDE

IntelliJ IDEA

• Create a New Project From Existing Sources and import as a Gradle project
• Note that IntelliJ might time out if a background Gradle process (for example, running the GWT compiler server) blocks the Gradle import. Stop and start the background process to unblock.

The log messages of the running application can be colour-highlighted with the GrepConsole plugin and our configuration.

Eclipse

• Run ./gradlew eclipse
• In Eclipse go to File > Import and import the project as Existing Projects into Workspace

The working directory in your IDE must always be set to the project root directory. We recommend you set this as the default directory in your IDE for all Run Configurations.

Working with deployment profiles

Before you can work on OpenRemote code, you must start dependencies by selecting one or more Docker Compose configuration profiles.

For example, the DMBS and the identity service are required to work on most of the projects. These containers are started and run in the background, the processes and tests you then execute in your IDE utilize the containers.

The syntax for starting deployment profiles is:

docker-compose -p <your_project_name> -f profile/<profile1>.yml -f profile/<profileN>.yml up

Here your_project_name is a convenient handle that groups all Docker images and containers in a deployment by prefixing their names with your project name. You can pick any name you like.

The default configuration of all services is for Docker host address localhost. If this is not your Docker host, you must set various environment variables and configure your stack, see the individual profiles for more information.