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.
For the initial setup you must supply the model file (and an authentication option):
1
$ ./sync-server --model=objectbox-model.json --unsecured-no-authentication
2
001-13:09:15.6995 [INFO ] [SySvAp] Default configuration file sync-server-config.js not found
3
001-13:09:15.6996 [INFO ] [SvrMsg] Registering server transport for ws
4
001-13:09:15.6997 [INFO ] [SySvAp] Database has no schema, loading from objectbox-model.json
5
001-13:09:15.6998 [INFO ] [SySvAp] Model file objectbox-model.json loaded, it has 2563 bytes
6
001-13:09:15.6999 [INFO ] [SchVer] Inserted new schema version ID 1
7
001-13:09:15.6999 [INFO ] [SySvAp] Switching schema version ID to 1
8
001-13:09:15.7002 [INFO ] [SchVer] Update schema version ID 1: acceptClients := true
9
001-13:09:15.7012 [INFO ] [SySvAp] Starting the server with a schema version ID 1
10
001-13:09:15.7018 [INFO ] [SvrUws] UwsServer listening on all interfaces, port 9999 without SSL
11
001-13:09:15.7018 [WARN ] [SvSync] INSECURE no-authentication mode enabled - every client allowed without any validation
12
001-13:09:15.7019 [INFO ] [SvSync] Started on port 9999
13
001-13:09:15.7019 [INFO ] [SySvAp] Starting object browser on http://127.0.0.1:9980
14
001-13:09:15.7020 [INFO ] [HttpSv] Running in single-store mode with an already opened store
15
001-13:09:15.7020 [INFO ] [HttpSv] Listening on http://127.0.0.1:9980
16
001-13:09:15.7020 [INFO ] [HttpSv] User management: enabled
17
001-13:09:15.7021 [INFO ] [SySvAp] ObjectBox sync server started in 2.63 ms
Copied!
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 http://127.0.0.1:9980 in your favorite web browser.
Docker Distribution
ObjectBox Sync Server is also available as a docker image (e.g. to run on Windows). Assuming you already downloaded the Docker image (e.g. via a Sync trial), you can import it with Docker's load command:
1
$ docker load --input ~/Downloads/sync-server.tar
2
c7022781a1ed: Loading layer [================================>] 13.55MB/13.55MB
3
53308e59a2cf: Loading layer [================================>] 1.536kB/1.536kB
4
Loaded image: objectboxio/sync:21.3.1-server
Copied!
Once the image is imported, 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):
1
# Note: assumes objectbox-model.json is in the current directory
2
# Database will be stored in the current directory's "objectbox" subdirectory
3
​
4
docker run --rm -it \
5
-v $(pwd):/data \
6
--publish 127.0.0.1:9999:9999 \
7
--publish 127.0.0.1:9980:9980 \
8
--user $UID \
9
objectboxio/sync:21.3.1-server \
10
--model /data/objectbox-model.json \
11
--unsecured-no-authentication \
12
--browser-bind 0.0.0.0:9980
Copied!
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). 1
# You only need to create the volume once:
2
docker volume create sync-server-data
3
​
4
# If you need to copy the objectbox-model.json file to the volume, you need to map
5
# the volume first. For example, you can use "busybox" utility image to do that:
6
docker run --rm -v $(pwd):/src -v sync-server-data:/data busybox \
7
cp /src/objectbox-model.json /data/
8
​
9
# And start the server, similarly to the example above:
10
docker run --rm -it \
11
--mount source=sync-server-data,target=/data \
12
--publish 127.0.0.1:9999:9999 \
13
--publish 127.0.0.1:9980:9980 \
14
objectboxio/sync:21.3.1-server \
15
--model /data/objectbox-model.json \
16
--unsecured-no-authentication \
17
--browser-bind 0.0.0.0:9980
Copied!
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 do 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 the Docker on Windows, this guide expects you to use Docker Desktop for WSL 2. Check thise setup if you don't have it installed yet.
To follow the best practices to 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 the guide in the previous section to do that.
If you're using PowerShell, make sure to use
${PWD} instead of $(pwd) in the examples.Configuration
Let's have a look at
sync-server --help:1
ObjectBox Sync Server
2
Usage:
3
sync-server [OPTION...]
4
​
5
-d, --db-directory arg directory where the database is stored
6
(default: objectbox)
7
--db-max-size arg database size limit; use a number with a unit
8
(K/M/G/T), e.g. 256G (default: 104857600K)
9
-b, --bind arg host/IP and port on which the server should
10
listen on (default: ws://0.0.0.0:9999)
11
-c, --conf arg configuration file path (default:
12
sync-server-config.js)
13
-m, --model arg schema model file to load (JSON) (default: )
14
--cert arg certificate file path (default: )
15
--browser-bind arg host/IP and port on which the object-browser
16
should listen on (default:
17
http://127.0.0.1:9980)
18
--browser-threads arg number of the worker threads to use for the
19
object-browser (default: 4)
20
--unsecured-no-authentication
21
[UNSECURE] allow connections without
22
authentication (default: false)
23
--debug enable debug logs (default: false)
24
-h, --help show help
Copied!
Configuration file
Alternatively, you can choose to provide the configuration in a
sync-server-config.js JSON file. Supply it via the --conf <path-to-config> flag.The available options are:
1
{
2
"dbDirectory": "objectbox",
3
"dbMaxSize": "100G",
4
"modelFile": "",
5
"bind": "ws://0.0.0.0:9999",
6
"browserBind": "http://127.0.0.1:9980",
7
"browserThreads": 4,
8
"certificatePath": "",
9
"auth": {
10
"sharedSecret": "",
11
"google": {
12
"clientIds": []
13
}
14
}
15
}
Copied!
dbDirectorydirectory where the database is storeddbMaxSizedatabase size limit; use a number with a unit, e.g. 256G (default: 100G)Kfor kibibytes, i.e. 1024 bytesMfor mebibytes, i.e. 1024 kibibytesGfor gibibytes, i.e. 1024 mebibytesTfor tebibytes, i.e. 1024 gibibytes
modelFileschema (model) file to create the database with or to use for a schema updatebindSync server will bind on this schema, host and port combination, should be in the formws://hostname:portfor examplews://127.0.0.1:9000. You can also bind to a specific IP address on the server machine by providing the exact address, as given byifconfigorip addr, e.g.ws://192.168.0.125:9999.browserBind(newer versions: adminBind) HTTP server (admin/web UI) will bind on this schema, host and port combinationbrowserThreads(newer versions: adminThreads) number of threads the HTTP server uses - a low number is enough as it's for admins only but you mayneed to increase if running in some cloud setups that keep the connections active (e.g. kubernetes)certificatePathServer SSL certificate directory; SSL will be enabled if not empty; expectscert.pemandkey.pematcertPathauth.sharedSecretif not empty, enables the shared secret authentication with the given keyauth.google.clientIdsa list of GoogleAuth client IDs (strings)
You can omit any fields you're not interested in overriding.
CLI options have precedence over (i.e. they override) the options in the JSON config file.
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:
1
001-14:09:07.5792 [INFO ] [SySvAp] Default configuration file sync-server-config.js not found
2
001-14:09:07.5793 [INFO ] [SvrMsg] Registering server transport for ws
3
001-14:09:07.5831 [INFO ] [SvrUws] UwsServer listening on all interfaces, port 9999 without SSL
4
001-14:09:07.5832 [WARN ] [SvSync] INSECURE no-authentication mode enabled - every client allowed without any validation
5
001-14:09:07.5883 [INFO ] [SvSync] Started on port 9999
6
001-14:09:07.5884 [INFO ] [SySvAp] Starting object browser on 0.0.0.0:9980
7
001-14:09:07.5885 [INFO ] [HttpSv] Running in single-store mode with an already opened store
8
001-14:09:07.5885 [INFO ] [HttpSv] Listening on 0.0.0.0:9980
9
001-14:09:07.5885 [INFO ] [HttpSv] User management: enabled
10
001-14:09:07.5890 [INFO ] [SySvAp] ObjectBox sync server started in 10 ms
Copied!
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
- 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 gives 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:
1
014-15:25:18.3188 [DEBUG] [SvrUws] (#1) Connection from 127.0.0.1:50488
2
014-15:25:18.3194 [DEBUG] [SvSync] (#1) Got msg of type LOGIN and length 28
3
014-15:25:18.3195 [DEBUG] [W-Pool] "SrvRead" Submitted new job successfully
4
002-15:25:18.3195 [DEBUG] [SvLgIn] (D10F) Authenticator 0 welcomes a new client
5
002-15:25:18.3195 [DEBUG] [W-Pool] "SrvRead" W#1 finished job in 0.06 ms
6
014-15:25:18.3195 [DEBUG] [SvrUws] Popped 1 messages to send
7
014-15:25:18.3207 [DEBUG] [SvSync] (D10F) Got msg of type APPLY_TX and length 140
8
014-15:25:18.3207 [DEBUG] [W-Pool] "SrvWrite" Submitted new job successfully
9
012-15:25:18.3215 [DEBUG] [TxLogA] Applied 4 commands
10
012-15:25:18.3277 [DEBUG] TX #5492 committed
11
009-15:25:18.3277 [DEBUG] [SvLogM] Applied TX log from D10FDB04A0F0: base=5460B3A444C2CD5377EAE8FBFFAC6B12, old=9A37C8BCA4232AA2D6E502AE2D069C15, new=4B2D216711C60497088B5FB10816CC98
12
009-15:25:18.3277 [DEBUG] [SvApTx] (D10F) Sending ACK_TX #1: 5460B3A4
13
009-15:25:18.3277 [DEBUG] [W-Pool] "SrvWrite" W#1 finished job in 7.01 ms
14
013-15:25:18.3278 [DEBUG] [SvDPsh] Have 116 bytes of data (0 clients).
15
014-15:25:18.3278 [DEBUG] [SvrUws] Popped 1 messages to send
Copied!
Setting the Authentication method
If the server is run without specifying an authentication method for clients, it won't start:
1
$ ./sync-server --model=objectbox-model.json
2
...
3
001-13:05:07.3526 [ERROR] [SySvAp] Runtime error: Authenticator must be set before starting
4
001-13:05:07.4524 [INFO ] [SvSync] Stopped (port 0)
5
Authenticator must be set before starting
Copied!
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 database schema and can also be used later to switch the schema to a newer version, by starting the server with an updated model file. Alternatively, the schema version can be changed through the web UI.
Feedback
While we hope that ObjectBox Sync is already useful for your use case, we're also aware that some features are missing. 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.
Please let the ObjectBox team know if you run into issues; we're happy to help. We are aware of rough edges still exist and might be able to help you one way or the other. Feel free to send us a message on contact[at]objectbox.io.
Thank you!
Last modified 1mo ago