Comment on page
Sync Server Configuration
To setup ObjectBox Sync Server to your needs, there are various configuration options, which are presented on this page.
There are two approaches to configure ObjectBox Sync Server:
- command line parameters (CLI): simple/quick approach for most settings
- configuration file (JSON): recommended for complex settings and required for clusters
A good start is to have a look at the output of running
sync-server --help(your output may vary, e.g. when using a newer version of the Sync Server):
$ sync-server --help
ObjectBox Sync Server
--admin-bind arg host/IP and port the admin http server should
listen on (default: http://127.0.0.1:9980)
--admin-threads arg number of the worker threads used by admin
http server (default: 4)
--admin-off do not start the admin http server
--async-tx-slot arg If async DB TXs are "too fast", this adds a
delay to fill up the slot (default: 3000)
-b, --bind arg host/IP and port the sync server should
listen on (default: ws://0.0.0.0:9999)
-c, --conf arg configuration file path (default:
--cert arg certificate file path (default: )
--cluster-id arg cluster ID to enable cluster mode for servers
--debug enable debug logs
--fixed-follower the server never becomes the leader of the
cluster (default: false)
--fixed-leader make the server the (only!) leader of the
cluster (danger: read docs carefully!) (default:
-d, --db-directory arg directory where the database is stored
--db-max-size arg database size limit; use a number with a unit
(K/M/G/T), e.g. 256G (default: 104857600K)
-h, --help show help
-m, --model arg schema model file to load (JSON) (default: )
[UNSECURE] allow connections without
--workers arg number of workers for the main task pool
(default is hardware dependent, e.g. 3 * CPU
"cores") (default: 0)
More details about the options can be found in the section on the configuration file. Just note that the naming convention is different (e.g.
db-max-size), but both refer to the same underlying option.
Alternatively, you can choose to provide the configuration in a JSON file. This is the preferred choice if the options are getting more complex (e.g. you can checkin the configuration file into version control). Also, it's the only way to configure a cluster.
By default, the configuration file is read from
sync-server-config.jsonin the current working directory. To use a different location, supply it via the
Some options have a default value, so if you are OK with the default, there is no need to specify it.
The available options are:
dbDirectorydirectory where the database is stored (default: "objectbox").
dbMaxSizedatabase size limit; use a number with a unit, e.g. 256G (default: 100G)
Kfor kibibytes, i.e. 1024 bytes
Mfor mebibytes, i.e. 1024 kibibytes
Gfor gibibytes, i.e. 1024 mebibytes
Tfor tebibytes, i.e. 1024 gibibytes
modelFileschema (model) file to create the database with or to use for a schema update
bindSync server will bind on this URL (schema, host and port). It should look like
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
ip addr, e.g.
adminBindHTTP server (admin/web UI) will bind on this URL (schema, host and port combination).
adminThreadsnumber of threads the HTTP server uses (default: 4). A low number is typically enough as it's for admins only. You may need to increase if running in some cloud setups that keep the connections active (e.g. Kubernetes).
certificatePathSupply a SSL certificate directory to enable SSL. This directory must contain the files
auth.sharedSecretif not empty, enables the shared secret authentication with the given key
auth.google.clientIdsa list of GoogleAuth client IDs (strings)
unsecured-no-authentication: allow connections without authentication (note: this is unsecure and shall only be used to simplify test setups.
You can mix both approaches, i.e. have a configuration file and use command line (CLI) options. In this case, CLI options have precedence over the options in the JSON config file. Thus, you can store your base configuration in a file, and override or add settings by providing command line arguments.