ObjectBox Sync Server
How to use standalone ObjectBox Sync Server and set it up as a data synchronization target for clients.
The ObjectBox Sync Server enables ObjectBox Sync. ObjectBox Sync clients connect to Sync Server to exchange data to update each other (data synchronization). You need to contact the ObjectBox team to get your personal copy of Sync Server (plain executable or Docker). It comes as a single command-line application sync-server and includes a web based data browser and management interface for administrator users.
Getting started
To start the server, you need a data model JSON file generated by one of the ObjectBox Sync clients.
If you did not define a data model yet, please do so now as outlined in the client section.
For the initial setup you must supply the model file (and an authentication option):
During development on your private network, you can disable authentication altogether using the option --unsecured-no-authentication. This allows all clients, which know the server's URL, to connect without additional checks.
Warning: it should be obvious that this setting is not intended for production usage.
As of now, the server is already running and accessible:
ObjectBox Sync on all interfaces, port 9999: Use this information (using a reachable IP or host name) to setup Sync clients
Admin web UI on localhost, port 9980: Have a look at http://127.0.0.1:9980 in your favorite web browser.
Docker
ObjectBox Sync Server is also available as a docker image (e.g. to run on Windows). It is not available to public, so ensure to contact us so we can set up individual access for you. We have two models for Docker images: image files or private repository on Docker Hub.
Docker image file distribution
If we sent you a Docker image for download (e.g. via a Sync trial), you can import it with Docker's load command:
Pull image from Docker Hub
If we send you information for a private Docker Hub repository, please ensure that you are logged in using the Docker login that was agreed on using docker login. Then, you can pull the image using docker pull objectboxio/sync-<customer>:sync-server-<version>; with replacing the placeholders <customer> and <version> with actual values (we provide that information to you).
Run a Docker container
Once the image is imported or pulled, you can run the container. The following example starts Sync Server using the current directory as the data folder and exposes the sync-server on localhost:9999 and admin web UI on http://localhost:9980. Ensure to have the file objectbox-model.json in the current directory on your host (it's mapped to /data inside the container):
Note: the following command assumes objectbox-model.json is in the current directory.
The database will be stored in the current directory's "objectbox" subdirectory
The Docker image name "objectboxio/sync:sync-server-2023-01-19" is an example that must be adjusted to the name that you actually got from us.
Using Docker volumes for database files
Alternatively, you could keep data in a separate docker volume. This example shows how to create the volume for the first time and then how to use it to start the Sync Server container (note: the difference to the previous example is in --mount and --user arguments).
If you're running on Windows, you may run into permission issues, with the server unable to create a database directory /data/objectbox. In that case, you can either create the directory with the right permissions (again, using busybox) or pass--user=0 argument to docker run (similar to --user $UID in the first example) - to run the sync-server as a root user (only applies inside the container).
Docker on Windows
When using Docker on Windows, this guide expects you to use Docker Desktop for WSL 2. Check the Install Docker Desktop on Windows instructions if you don't have it installed yet.
To follow the best practices and achieve optimal performance, as described by Microsoft and Docker, use a data volume for the database directory instead of binding to a local directory. Follow Using Docker volumes for database files to do that.
If you're using PowerShell, make sure to use ${PWD} instead of $(pwd) and replace the backward slash (\) for multiline commands with a backtick (`).
Configuration
The setup options for ObjectBox Sync Server are detailed on the configuration page. In summary, you can use command line options (e.g. run sync-server --help for a quick overview), or use a JSON configuration file for more complex setups. Again, please check the configuration page for details.
Admin Web UI
The ObjectBox Sync Server Admin UI runs as part of the sync-server executable and allows you to:
view the data and download it in JSON format,
view current schema information and previous schema versions,
view runtime information, like version number, database size, network interfaces, ...
manage Admin UI user credentials
Sync Stats
**"**Sync" main menu item will bring you to a page with numerous charts with server runtime information. This can be valuable in multiple ways, e.g. during development, you can verify your applications connect to the server (show up in "Connects" and "Connected clients") and synchronize data (see "Client applied *"). Also, there are multiple charts showing errors - watch for those when trying to figure out issues with your clients.
Status
In the main menu, you will find "Status" to open a page with some useful information. While the following layout is still not final, it will give you a first impression of what to expect:
The "Debug logging" switch on the status page enables a very detailed logging (to standard output).
Logging
By default only logs with "info" level and above are enabled, which are relatively rare. For example, there's nothing logged about standard interactions with clients. That might be overwhelming with a few hundred clients already. Info logs should never "spam" you, no matter how many clients are connected.
Let's look at a typical log during startup:
As you can see, logging is structured into the following columns:
Thread: the first three digits are the number of the thread that logged the text message
Time: UTC time using 24 hours format, including 1/10,000 second precision (1/10 milliseconds)
Level: One of the log levels (listed with increasing severity):
DEBUG: extensive logs to help diagnosing a specific behavior. Debug logs are only enabled if the DebugLog feature flag is on (usually the Sync Server ships such feature). You also need to make sure the Debug logging switch is enabled on Admin UI (see the screenshot above).
INFO: "important" information
WARN: something unusual has happened that you might want to check.
ERROR: reserved for special error occasions ("something bad happened") that typically require some action. It might be that the machine is running out of resources (RAM, disk space etc) or an unexpected situation was encountered. When in doubt, reach out to the ObjectBox team to clarify what's going on.
Tag (optional): Most logs include a tag identifying the internal component
Message: the actual log text
After startup, you typically won't see anymore logs by default. In contrast to "info" and above, "debug" level logs give you extensive information including client connects and message interactions with clients.
To give you a feel what debug logs are like have a look at the following example. It shows a new client connecting, logging in and sending data:
Setting the Authentication method
If the server is run without specifying an authentication method for clients, it won't start:
To specify an authentication method for clients provide a configuration file.
During development, it's also possible to use the --unsecured-no-authentication flag to allow any connection from any client.
Never use this option in an app shipped to customers. It is inherently insecure and allows anyone to connect to the sync server.
Updating the data model
The model JSON is used to initialize the data model for sync (and also the database schema). Later, when your data model has evolved, you will want to update model at server. You have two options to supply a newer version:
Starting the server with an updated model file.
Upload the model file through the Admin web UI.
For details, please refer to the data model evolution section.
Feedback
We're looking forward to your feedback to prioritize the most requested features. Please fill in this Sync Feedback Form to tell us what you think.
And if you run into issues, please let the ObjectBox team know; we're happy to help.
Thank you!
Last updated
