This tutorial was written by Fidaa Berrjeb.

Who this guide is for

This tutorial is for developers who:

• Need to synchronize their MongoDB database with their offline-first applications.
• Are looking to set up an end-to-end demonstration of bi-directional data synchronization between local ObjectBox databases on client devices and a MongoDB Atlas cluster.
• Want to build a system that ensures offline-first functionality while maintaining data consistency across devices and databases.

Need to sync your MongoDB database and your offline-first apps? In this tutorial, we’ll walk you through setting up an end-to-end demonstration of bi-directional data sync between local ObjectBox databases on client devices and a MongoDB Atlas cluster. Together, we’ll build a system that ensures offline-first functionality while keeping data in sync across devices and databases.

What you’ll learn and achieve

By the end of this tutorial, you’ll have a working demo seamlessly synchronizing local app data from Android and iOS devices with a MongoDB Atlas cluster.

• Changes made on client devices will be pushed to the MongoDB Atlas cluster.
• Updates made in MongoDB will flow back to the connected client apps.

You’ll learn how to:

• Configure the MongoDB Sync Connector.
• Run initial/full sync from MongoDB.
• Verify a two-way data sync across a Java client.

What you’ll be setting up for MongoDB Data Sync:

• MongoDB Atlas cluster: A cloud-based centralized datastore connected to your ObjectBox Sync Server via the ObjectBox MongoDB Sync Connector.
• ObjectBox Sync Server: Acts as the core facilitator for device connectivity, conflict resolution, and real-time data streaming.
• Client applications: Java application, each leveraging local ObjectBox databases for offline-first storage capabilities.

Prerequisites

Before you begin, ensure you have the following:

• A MongoDB Atlas account with the atlasAdmin role (for full administration in Atlas)
• Sample application data to synchronize across both MongoDB Atlas and your client devices
• Basic Java knowledge for setting up the client app Gradle installed

Architecture overview

The system’s architecture revolves around the ObjectBox Sync Server, which functions as the main facilitator of device-to-cloud-to-device data synchronization. Here’s a high-level overview of how the components interact:

• Task application (Java): Two sample clients (CLI or UI) perform local create, read, update, and delete (CRUD) operations using an embedded ObjectBox database. This database is both a local object store and an on-device vector database that uses the Hierarchical Navigable Small Worlds (HNSW) algorithm to enable offline semantic search, on-device.
• ObjectBox Sync Server: This is a central synchronization engine for bidirectional sync. It manages secure connections from numerous ObjectBox clients, efficiently queues data changes, and exposes an admin UI for monitoring and configuration. It’s deployed via Docker in the cloud, on-premises, or at the edge.
• ObjectBox MongoDB Sync Connector: Operating within the ObjectBox Sync Server, it’s specifically engineered to stream changes both ways between ObjectBox and MongoDB, maps types/IDs, and ensures updates are applied consistently on each side.
• MongoDB Atlas: Atlas is a fully managed cloud database service that stores and handles your application’s core data.

Initial configuration steps

1. Configure the MongoDB Atlas cluster

In this section, we are going to set up a MongoDB Atlas cluster that stores and manages our application’s core data.

1. Log in with your MongoDB Cloud user account and create a new MongoDB Atlas cluster. You may reuse an existing cluster.
2. Once the MongoDB Atlas cluster is set up, click the "Connect" button, copy the connection string, and save it for the next step. For this demo, we used the MongoDB Atlas cluster SolutionsAssurance on MongoDB version 8.0, hosted in the AWS region eu-south-2 (Spain).
3. Create the database which you want to sync with ObjectBox. In our case, it was the objectbox_sync database.
4. Create collections which you want to synchronize. We used the Task collection. All collections you wish to synchronize with ObjectBox must exist within MongoDB before setting up the connector.
5. Create a new database user or use an existing one. The connector authenticates to MongoDB using the username and password of a database user. You must have readWrite@ permissions for the specific database that you’re looking to synchronize with ObjectBox. Complete the previous connection string with the newly created database user and password.

You can also configure more granular privileges.

IMPORTANT The minimum supported version for the connector is currently MongoDB 5.0, but 8.0 is recommended. MongoDB Atlas, Community, and Enterprise work. Only a MongoDB replica set instance provides the necessary features for the MongoDB Sync Connector to work.

2. Set up the Sync Server and MongoDB with Docker Compose

Let’s set up the ObjectBox Sync Server, a synchronization engine, and connect it to our MongoDB cluster to perform bidirectional data-sync.

ObjectBox Sync Server connected to the MongoDB Atlas cluster

1. To run the Sync Server, you need to have a Docker engine installed on your local machine. You can download it from the Docker Desktop downloads.
2. Clone the objectbox-sync-examples repository and navigate to the directory to run the Sync Server and a MongoDB instance with Docker Compose.

git clone git@github.com:objectbox/objectbox-sync-examples.git
cd tasks/server-mongo-compose

1. Check the docker-compose.yml file inside the tasks/server-mongo-compose folder. To connect to the MongoDB cluster, you need to adjust the file and add the connection string which we saved in the previous section.

This is an example of my docker-compose.yml file:

services:
sync-server:
image: objectboxio/sync-server-trial
container_name: sync-server
restart: always
# Note: user and group ID 1000 may have to be adjusted to match your user IDs:
user: "${UID:-1000}:${GID:-1000}"
ports:
- "9980:9980"
- "9999:9999"
volumes:
# Expose "current" (this) directory as "/data" in the container.
- .:/data
command: >
- --model
- ./objectbox-model.json
- --admin-bind
- 0.0.0.0:9980
- --mongo-url
- ${MONGO_URL}
- --mongo-db
- ${MONGO_DB}
- --debug

1. Create a .env file inside the current directory and add variables.

MONGO_URL=<MongoDB connection string>
MONGO_DB=<databaseName>

1. Run the server. This command initiates the services/containers as described in the docker-compose.yml script:

docker compose up

1. The output should look something like this:

✔ Network server-mongo-compose_default
✔ Container sync-server

After the start, the following services/ports are available:

• ObjectBox Admin UI at port 9980—open http://localhost:9980/ to access the Admin UI (and activate the trial)

• ObjectBox Sync Server at port 9999—the target for Sync clients

1. Open the Admin UI http://localhost:9980/ and start the trial.

2. Open the "MongoDB Connector" section and check that the connector is running.

3. To start the synchronization with the MongoDB database, you need to perform the initial sync. For this, open the "Full Sync" section and click "Full Sync from MongoDB."

4. After the initial sync completion, go to the "Data" section and check that data from your MongoDB database is present there.

3. Prepare the Java client app

We can use the task manager app for the different languages (Java and Swift) as the clients. To run the JAVA example app, we need to satisfy some prerequisites.

1. Install the Java Development Kit. Any Java LTS release is supported (for example, Java 17 or Java 21) . If running in macOS, you can use Homebrew to install it. Simply run:

brew install openjdk@17

1. Install Gradle. If running in macOS, you can use Homebrew Gradle. Run:

brew install gradle

1. Clone the objectbox-sync-examples repository (if you didn’t before) and navigate to the directory of the Java client app.

git clone git@github.com:objectbox/objectbox-sync-examples.git
cd objectbox-sync-examples/tasks/client-java

1. Build and run the project.

./gradlew build
./gradlew run

1. You should see a message similar to this listing the available commands to use the app. This is a CLI TODO list app. You can add, remove, update, and list tasks from the command line. These tasks will be written in the local ObjectBox database and pushed to the ObjectBox Sync Server and the MongoDB database.

> Task :java-main-sync:run
Welcome to the ObjectBox tasks-list app example
Available commands are:
ls [-a]        list tasks - unfinished or all (-a flag)
new task_text  create a new task with the text 'task_text'
done ID        mark task with the given ID as done
rm ID          delete task with the given ID
exit           close the program
help           display this help

1. To see all data synchronized from the MongoDB database, you can run the command ls -a and you will see the data synchronized from the MongoDB database.

<==<==========---> 80% EXECUTING [25s]
ID    Text                      Date Created         Date Finished
5     taskFromMongoUserSpecific 27-06-2025 02:00:00  27-06-2025 02:00:00
6     taskFromMongoUserSpecific 1 27-06-2025 02:00:00  27-06-2025 02:00:00
7     task2                     01-09-2025 14:57:15  Task not completed yet
<==========---> 80% EXECUTING [37s]
> :app:run

1. The data model file is generated by the Sync client at client-java/app/objectbox-models/default.json.

IMPORTANT The models must be identical (including UIDs) across server and clients. Otherwise, sync can fail or behave unpredictably. If you want to start the client from scratch, you need to remove the database folder tasks/client-java/tasks-synced.

rm -rf tasks/client-java/app/tasks-synced

Congrats! You now have:

• A MongoDB Atlas cluster acting as the cloud source of truth.
• An ObjectBox Sync Server bridging devices and MongoDB via the ObjectBox Sync Server and MongoDB Sync Connector.
• A Java client with local persistence in sync in real time.

Now, simply swap in your own entities, deploy the Sync Server where you need it, and you’re production-ready for offline-first at scale.

Further reading

If you want to go deeper into ObjectBox Sync, offline-first architectures, and hybrid AI use cases, here are some good next reads:

• Bi-directional Offline-First Data Sync with MongoDB and ObjectBox: High-level overview of the same pattern you implemented in this tutorial (devices ↔ ObjectBox ↔ MongoDB Atlas)
• Data Modeling for Offline-First Apps: Practical patterns for designing schemas that work well with sync and schema evolution
• Realm to ObjectBox Migration: Easy steps to migrate from Realm to ObjectBox