xBrowserSync

API service

xBrowserSync is a free tool for syncing browser data between different browsers and devices, built for privacy and anonymity. For full details, see www.xbrowsersync.org.

This repository contains the source code for the REST service API that client applications communicate with. If you'd like to run your own xBrowserSync service on your Node.js web server, follow the installation steps below.

Once configured, you can begin syncing your browser data to your xBrowserSync service, and if you're feeling generous, allow others to sync their data to your service also!

API documentation

The available API methods are documented on the home page of each xBrowserSync service, respective of the version that service is running. For example, you can view the API documentation for the official xBrowserSync service at api.xbrowsersync.org.

Running with Docker

The easiest way to get up and running is by using Docker to run the xBrowserSync API as a container. Docker is a popular container management and imaging platform that allows you to quickly work with containers on Linux and Windows.

Once you have installed Docker you can use the xBrowserSync API Docker image to get a production-ready xBrowserSync service up and running with minimal effort (view the README for more information).

Manual installation

Whilst running in a Docker container is the recommended way to run your xBrowserSync service, you can self-host xBrowserSync instead by performing a manual installation on your own server by installing the two dependencies listed as prerequisites and following the six easy steps below:

Prerequisites

• Node.js
• MongoDB

1. Clone the xBrowserSync API source repo

$ git clone https://github.com/xbrowsersync/api.git

2. Install and build xBrowserSync API package

(Use the unsafe-perm flag if you get any permissions issues whilst trying to install):

$ npm install --unsafe-perm

3. Configure MongoDB databases

1. Run the following commands in the mongo shell:

   (Replace [password] with a cleartext password of your choice)

     use admin
     db.createUser({ user: "xbrowsersyncdb", pwd: "[password]", roles: [ { role: "readWrite", db: "xbrowsersync" }, { role: "readWrite", db: "xbrowsersynctest" } ] })
     use xbrowsersync
     db.newsynclogs.createIndex( { "expiresAt": 1 }, { expireAfterSeconds: 0 } )
     db.newsynclogs.createIndex({ "ipAddress": 1 })

2. Add the following environment variables to hold xBrowserSync DB account username and password:

   • XBROWSERSYNC_DB_USER

   • XBROWSERSYNC_DB_PWD

     On Windows, open a Command Prompt and type (replacing [password] with the password entered in the mongo shell):

     setx XBROWSERSYNC_DB_USER "xbrowsersyncdb"
     setx XBROWSERSYNC_DB_PWD "[password]"

     On Ubuntu/Debian Linux, open a terminal emulator and type:

     $ pico ~/.profile

     Add the lines (replacing [password] with the password entered in the mongo shell):

     export XBROWSERSYNC_DB_USER=xbrowsersyncdb
     export XBROWSERSYNC_DB_PWD=[password]

     Save and exit, then log out and back in again.

   If exposing your service to the public it is recommended you also perform the following steps:

3. Add a TTL index on bookmarks.lastAccessed to delete syncs that have not been accessed for 3 weeks:

     use xbrowsersync
     db.bookmarks.createIndex( { "lastAccessed": 1 }, { expireAfterSeconds: 21*86400 } )

4. Modify configuration settings

The file config/settings.default.json contains all of the default configuration settings. User configuration values should be stored in config/settings.json and will override the defaults. Should you wish to change any of the configuration settings, copy settings.default.json and rename the copy to settings.json before changing any values as required. Be sure to remove any settings that have not been changed so that any amendments to the default values in future versions are picked up. For example, a basic user configuration to modify the service status message could look like:

{
  "status": {
    "message": "Welcome to my xBrowserSync service!"
  }
}

Any changes to the user configuration will require the service to be restarted before being picked up. The available configuration settings are:

5. Create log folder

Ensure that the path set in the log.path config value exists, and that the account node will be running as can write to that location.

6. Run xBrowserSync service

$ node dist/api.js

Building

If you've made code changes you can run a fresh build with the command:

$ npm run build

Testing

The project includes unit, integration and end to end tests.

To run end to end tests, you will need to create the test database first. Run the following commands in the mongo shell:

(Replace [dbname] with your xBrowserSync database name and [password] with the xBrowserSync database user account password)

  use [dbname]test
  db.createUser({ user: "xbrowsersyncdb", pwd: "[password]", roles: ["readWrite"] })

You can then run the end to end tests by running the following command:

$ npm run test

Upgrading from an earlier version

<= v1.1.5

From v1.1.6, database users are created in the admin database. When upgrading from an earlier version you'll either need to drop the existing users in the xbrowsersync database and recreate them in the admin database, or simply add the following to your config/settings.json file:

  "db": {
    "authSource": "xbrowsersync"
  }

Config settings for logging has also changed so ensure you update your config/settings.json file if you have customised logging settings.

<= v1.0.3

If you are curently running v1.0.3 (or earlier) of the xBrowserSync API, you will need to export existing syncs and delete the xBrowserSync database before upgrading.

To export existing syncs, run the following command:

  mongoexport --db xBrowserSync -c bookmarks --out /path/to/export/file

Then to delete the database, run the following commands in the mongo shell:

  use xBrowserSync
  db.dropAllUsers()
  db.dropDatabase()

Once you've upgraded and completed the installation steps below, you can import the syncs by running the following command:

  mongoimport --db xbrowsersync -c bookmarks --file /path/to/export/file

Other Implementations

Google Cloud

• sbogomolov/xbrowsersync-gcf: An implementation of the xBrowserSync API using Google Cloud Functions with Firestore backend.

Cloudflare Worker

• txchen/xbrowsersync-cfw: An implementation of the xBrowserSync API using Cloudflare worker and KV.

VS Code

If you're using VS Code, you have the following launch configurations:

1. Debug API: Will compile and debug the main API service.
2. Debug docs: Will launch API home page in chrome and attach to debugger for debugging docs issues.
3. Run unit/integration tests: Will debug tests in *.spec.ts files in src folder.
4. Run e2e tests: Will debug tests in test/e2e folder.

Note: we recommend VSCodium for running VSCode without Microsoft's proprietary binaries and telemetry/tracking.

Issues and feature requests

Please log Docker-related issues in the api-docker Issues list, if you have found an issue with the xBrowserSync API itself or wish to request a new feature, do so in the api Issues list.