ObjectBox sync-server
comes as a single command-line application and includes:
ObjectBox core database - used internally by Sync server and HTTP server
ObjectBox Sync server - listens for connections from sync clients
ObjectBox HTTP server - simple database browser and management - should be only used by the administrator
All of these are started when you execute the sync-server
binary and you can control the configuration using command-line arguments and/or using a configuration JSON file.
To start the server you will, at the very least, need to specify the directory path and the database model JSON, as generated by one of the ObjectBox language bindings (Java/Swift/Go/...) or by the objectbox-generator
(download here: ObjectBox Generator releases).
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.
Let's say you already have a model file ready in the current folder and try to run the server. The server will refuse to start because it requires some form of client authentication (e.g. shared key).
$ ./sync-server --model=objectbox-model.json...001-13:05:07.3526 [ERROR] [SySvAp] Runtime error: Authenticator must be set before starting001-13:05:07.4524 [INFO ] [SvSync] Stopped (port 0)Authenticator must be set before starting
For development you can disable authentication altogether, allowing all the clients that have network connectivity. Warning: don't use this setting in production or on networks you don't trust.
$ ./sync-server --model=objectbox-model.json --unsecure-no-authentication001-13:09:15.6995 [INFO ] [SySvAp] Default configuration file sync-server-config.js not found001-13:09:15.6996 [INFO ] [SvrMsg] Registering server transport for ws001-13:09:15.6997 [INFO ] [SySvAp] Database has no schema, loading from objectbox-model.json001-13:09:15.6998 [INFO ] [SySvAp] Model file objectbox-model.json loaded, it has 2563 bytes001-13:09:15.6999 [INFO ] [SchVer] Inserted new schema version ID 1001-13:09:15.6999 [INFO ] [SySvAp] Switching schema version ID to 1001-13:09:15.7002 [INFO ] [SchVer] Update schema version ID 1: acceptClients := true001-13:09:15.7012 [INFO ] [SySvAp] Starting the server with a schema version ID 1001-13:09:15.7018 [INFO ] [SvrUws] UwsServer listening on all interfaces, port 9999 without SSL001-13:09:15.7018 [WARN ] [SvSync] INSECURE no-authentication mode enabled - every client allowed without any validation001-13:09:15.7019 [INFO ] [SvSync] Started on port 9999001-13:09:15.7019 [INFO ] [SySvAp] Starting object browser on http://127.0.0.1:9980001-13:09:15.7020 [INFO ] [HttpSv] Running in single-store mode with an already opened store001-13:09:15.7020 [INFO ] [HttpSv] Listening on http://127.0.0.1:9980001-13:09:15.7020 [INFO ] [HttpSv] User management: enabled001-13:09:15.7021 [INFO ] [SySvAp] ObjectBox sync server started in 2.63 ms
As of now, the server is running and accessible:
sync on all interfaces, port 9999
admin web UI: localhost, port 9980
You can have a look at the admin UI at http://127.0.0.1:9980 in your favourite web browser and start using sync in the client apps.
Let's have a look at sync-server --help
:
ObjectBox Sync ServerUsage:sync-server [OPTION...]​-d, --db-directory arg directory where the database is stored(default: objectbox)-b, --bind arg host/IP and port on which the server shouldlisten on (default: ws://0.0.0.0:9999)-c, --conf arg configuration file path (default:sync-server-config.js)-m, --model arg schema model file to load (JSON) (default: )--cert arg certificate file path (default: )--browser-bind arg host/IP and port on which the object-browsershould listen on (default:http://127.0.0.1:9980)--browser-threads arg number of the worker threads to use for theobject-browser (default: 4)--unsecured-no-authentication[UNSECURE] allow connections withoutauthentication (default: false)--debug enable debug logs (default: false)-h, --help show help
Alternatively, you can choose to provide the configuration in a sync-server-config.js
JSON file:
{"dbDirectory": "objectbox","modelFile": "","bind": "ws://0.0.0.0:9999","browserBind": "http://127.0.0.1:9980","browserThreads": 4,"certificatePath": "","auth": {"sharedSecret": "","google": {"clientIds": []}}}
dbDirectory
directory where the database is stored
modelFile
schema (model) file to create the database with or to use for a schema update
bind
Sync server will bind on this schema, host and port combination, should be in the form ws://hostname:port
for example ws://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 by ifconfig
or ip addr
, e.g. ws://192.168.0.125:9999
.
browserBind
HTTP server (admin/web UI) will bind on this schema, host and port combination
browserThreads
number of threads the HTTP server uses - a low number is enough as it's for admins only but you may
need to increase if running in some cloud setups that keep the connections active (e.g. kubernetes)
certificatePath
Server SSL certificate directory; SSL will be enabled if not empty; expects cert.pem
and key.pem
at certPath
auth.sharedSecret
if not empty, enables the shared secret authentication with the given key
auth.google.clientIds
a list of GoogleAuth client IDs (strings)
You can omit any fields you're not interested to override them. CLI options have precedence (override) the options in the JSON config file.
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).
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:
001-14:09:07.5792 [INFO ] [SySvAp] Default configuration file sync-server-config.js not found001-14:09:07.5793 [INFO ] [SvrMsg] Registering server transport for ws001-14:09:07.5831 [INFO ] [SvrUws] UwsServer listening on all interfaces, port 9999 without SSL001-14:09:07.5832 [WARN ] [SvSync] INSECURE no-authentication mode enabled - every client allowed without any validation001-14:09:07.5883 [INFO ] [SvSync] Started on port 9999001-14:09:07.5884 [INFO ] [SySvAp] Starting object browser on 0.0.0.0:9980001-14:09:07.5885 [INFO ] [HttpSv] Running in single-store mode with an already opened store001-14:09:07.5885 [INFO ] [HttpSv] Listening on 0.0.0.0:9980001-14:09:07.5885 [INFO ] [HttpSv] User management: enabled001-14:09:07.5890 [INFO ] [SySvAp] ObjectBox sync server started in 10 ms
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 happend that you might want to check.
ERROR: reserved for special error occasions ("something bad happend") 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:
014-15:25:18.3188 [DEBUG] [SvrUws] (#1) Connection from 127.0.0.1:50488014-15:25:18.3194 [DEBUG] [SvSync] (#1) Got msg of type LOGIN and length 28014-15:25:18.3195 [DEBUG] [W-Pool] "SrvRead" Submitted new job successfully002-15:25:18.3195 [DEBUG] [SvLgIn] (D10F) Authenticator 0 welcomes a new client002-15:25:18.3195 [DEBUG] [W-Pool] "SrvRead" W#1 finished job in 0.06 ms014-15:25:18.3195 [DEBUG] [SvrUws] Popped 1 messages to send014-15:25:18.3207 [DEBUG] [SvSync] (D10F) Got msg of type APPLY_TX and length 140014-15:25:18.3207 [DEBUG] [W-Pool] "SrvWrite" Submitted new job successfully012-15:25:18.3215 [DEBUG] [TxLogA] Applied 4 commands012-15:25:18.3277 [DEBUG] TX #5492 committed009-15:25:18.3277 [DEBUG] [SvLogM] Applied TX log from D10FDB04A0F0: base=5460B3A444C2CD5377EAE8FBFFAC6B12, old=9A37C8BCA4232AA2D6E502AE2D069C15, new=4B2D216711C60497088B5FB10816CC98009-15:25:18.3277 [DEBUG] [SvApTx] (D10F) Sending ACK_TX #1: 5460B3A4009-15:25:18.3277 [DEBUG] [W-Pool] "SrvWrite" W#1 finished job in 7.01 ms013-15:25:18.3278 [DEBUG] [SvDPsh] Have 116 bytes of data (0 clients).014-15:25:18.3278 [DEBUG] [SvrUws] Popped 1 messages to send
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.
Depending on your use case, there still might be an important feature missing in the sync version you have received: "ID mapping" allows each sync client (and server) to operate in their own "ID space". This ensures clients won't overwrite each other when using the same IDs (by default, IDs start at 1 in ObjectBox). Workarounds exist until ID mapping is operational; e.g. assign IDs yourself so that they cannot collide; or ensure that in product demos you only insert new objects after sync completed. When in doubt, ask the ObjectBox team.
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.