Eclipse Ditto: digital twins as five Java microservices over MongoDB

A twin is a server-side record, and Ditto splits it across services

Eclipse Ditto implements the digital twin pattern described in the README as a virtual, cloud based representation of a real world counterpart, where the real world things are devices such as sensors, smart heating, connected cars, smart grids or EV charging stations. The interesting part is that Ditto does not treat the twin as one monolithic server. The Docker Compose deployment brings up a MongoDB instance as the backing datastore and then five Ditto microservices: Policies, Things, Things-Search, Gateway and Connectivity. The repository layout mirrors that split, with separate top level directories for policies, things, thingsearch, gateway and connectivity, plus shared modules for messages, the protocol layer, RQL, JWT handling, and a json-cbor module alongside plain json. Policies is the component that decides who may read or write a twin, Things holds the digital representations, Things-Search answers queries across them, Connectivity is the side that talks to real devices, and Gateway is the entry point. The audience is a platform team that wants a governed API for device state, not a hobbyist with one sensor.

nginx sits in front of the services and holds the basic authentication

In the Compose deployment the microservices are not exposed directly. An nginx instance acts as a reverse proxy and performs a simple basic authentication, listening on port 8080, and it also serves static HTTP content and API documentation on the same address. That is where you open http://localhost:8080 after startup. The arrangement has an operational consequence worth stating plainly: the Compose file brings up MongoDB alongside the Ditto services, and MongoDB is explicitly not part of Ditto even though it is started via Docker. Ditto stores its twins there, so the datastore is a required piece of the deployment and not an optional extra you can swap out casually. The repository also carries a benchmark-tool directory, which suggests the project takes its own throughput seriously, but the README does not publish benchmark results, so any performance figure you see elsewhere is not traceable to this repository.

Starting a local instance with Docker Compose

The quick path needs a running Docker daemon with Docker Compose installed, and for a single instance setup on a local machine the README asks for at least 2 CPU cores that Docker can use and at least 4 GB of RAM that Docker can use. With those in place, the latest built images are pulled from Docker Hub and started with:

cd deployment/docker/
docker-compose up -d

Follow the startup with the logs, which is where connection problems to MongoDB show up:

docker-compose logs -f

When it settles, http://localhost:8080 is the entry point, and the README points at a Hello World walkthrough on the project site for the first request. If Docker Compose is not what you want to use, the README points at a deployment directory in the repository with other options, and the deployment folder in the top level listing holds them.

Building from source means JDK 25, Maven and a local image snapshot

Developing extensions or contributing code is a different path from running the published images, and the toolchain requirements are specific: JDK >= 25, Apache Maven >= 3.9.x installed, and a running Docker daemon. The first step builds the artifacts:

mvn clean install

Tests can be skipped when you are iterating on a change:

mvn clean install -DskipTests

The second step turns that build into local Docker images:

./build-images.sh

The script accepts a proxy when your infrastructure needs one, and the given host and port then apply to both HTTP and HTTPS:

./build-images.sh -p 172.17.0.1:3128

Finally you start the local snapshot images. The detail that trips people up is that Docker Compose needs to know the snapshot number, and the repository handles that with an env file rather than a tag you type yourself:

cd ../deployment/docker/
# the "dev.env" file contains the SNAPSHOT number of Ditto, copy it to ".env" so that docker compose uses it:
cp dev.env .env
docker-compose up -d

If dev.env is not copied to .env, the Compose stack will not pick up the images you just built, and you will end up debugging the wrong container.

The explorer UI can point at a sandbox or at your own instance

Ditto ships a browser based explorer UI, and the README hosts a live version of the latest build at eclipse-ditto.github.io with a primary environment named ditto_sandbox. The same UI can be pointed at a locally running default through an environment named local_ditto, and additional environments can be added so the same frontend can work against a deployed installation. That split is the sensible way to evaluate the project: the sandbox gives you something to click through before you install anything, and the environment mechanism means one UI can cover a local stack and a production deployment without a rebuild. The rest of the documentation lives on the project site rather than in the repository README, and the repository carries a documentation directory as well. For the API semantics themselves, the project site is where the README sends you, and the repository does not repeat them.

Protocol surface, and what the repository does not settle

The top level listing shows how broad the surface is: a protocol module, a wot directory, jwt, rql, messages, an internal module, base, edge, legal and utils, plus a ui directory for the explorer. The wot directory and the repository topics list point at the Web of Things line of work, and rql is the query language directory that Things-Search is built around. Reading the tree is one thing, and the README is thin on several practical points that you will need to answer before committing to the framework. It does not describe how to connect a physical device, only that the Connectivity service exists in the deployment. It does not document a migration path between twin schema versions, a rollback procedure for a bad release, or the authentication model behind the proxy beyond the phrase basic authentication. It also does not state how the policy model maps to your existing user or tenant system. There is a SECURITY.md and a legal directory in the tree, so the project does treat those questions, but the answers are not in the README. The repository also ships a benchmark-tool, a bom for dependency versions and a Jenkinsfile_multibranch_pipeline for its own build, none of which the README explains.

Editorial conclusion

Eclipse Ditto fits a platform team that needs a shared, policy-governed representation of physical devices, with search and Web of Things support in the same tree, and that can run a MongoDB plus five JVM services behind a proxy. It does not fit a single-device project, an edge deployment that must run without a datastore, or a team that needs a turnkey device simulator, since the repository provides the twin runtime rather than the devices themselves. Verify first that a JDK 25 or newer toolchain and Maven 3.9.x are available, that Docker can spare at least 2 CPU cores and 4 GB of RAM for the single instance setup, and that port 8080 is free, because the nginx reverse proxy terminates there with basic authentication. The licence field on the repository says EPL-2.0, releases 3.9.8 and 3.8.14 were both published on 2026-10-08, and the last push was on 2026-10-16.

Frequently asked questions

Official sources

1. eclipse-ditto/ditto on GitHub
2. License: EPL-2.0
3. Project website
4. README
5. Releases