Error

This guide seems to be broken for the current versions of 1.1.13. xbrowsersync don’t work withNode.js in version 18 or newer, we would be happy if you want to work on a solution and create a Pull Request. See also the related issue: https://github.com/Uberspace/lab/issues/1640

xBrowserSync API

xBrowserSync is a free and open-source browser bookmark syncing tool with support for Chrome, Firefox and Android (via app).

The xBrowserSync API provides an individual sync server where your bookmarks stored encrypted.

Note

For this guide you should be familiar with the basic concepts of

domains
supervisord
web backends
Node.js and its package manager npm
MongoDB

Prerequisites

We’re using Node.js in the stable version 8:

[isabell@stardust ~]$ uberspace tools version show node
Using 'Node.js' version: '8'
[isabell@stardust ~]$

MongoDB

Install MongoDB.

Subdomain & Web backends

Setup a web backend on port 8080

[isabell@stardust ~]$ uberspace web backend set / --http --port 8080

Installation

Download xBrowserSync API

Get the xBrowserSync API source code from GitHub and clone it to ~/xbrowsersync/api, be sure to replace the pseudo branch number v1.1.18 here with the latest release branch from the GitHub repository.

[isabell@stardust ~]$ git clone https://github.com/xbrowsersync/api.git --branch v1.1.8 xbrowsersync/api
[...]
Receiving objects: 100% (117/117), 566.29 KiB | 1.45 MiB/s, done.
Resolving deltas: 100% (14/14), done.
[...]
[isabell@stardust ~]$

Creating MongoDB User & Tables

Open a Mongo shell and enter the mongo command listed below. This creates a new database user and the tables needed by xBrowserSync. Replace <password> with a cleartext password of your choice, which is used as password for a new created database user. Afterwards leave the shell with the exit command.

[isabell@stardust ~]$ mongo
[...]
>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 })
 >exit
 [isabell@stardust ~]$

Installation

Now you can install all the dependencies needed for xBrowserSync by using npm. Additionally you can let npm run a so called security audit, which detects and updates insecure dependencies.

[isabell@stardust ~]$ cd ~/xbrowsersync/api
[isabell@stardust api]$ npm install
[isabell@stardust api]$ [...]
[isabell@stardust api]$ npm audit fix
[isabell@stardust api]$ [...]
[isabell@stardust api]$

Configuration

Warning

You are recommended to look also at the other configuration settings. For example: If you plan to use only a single account you should limit the number of accounts.

Copy the sample configuration file:

[isabell@stardust api]$ cp config/settings.default.json config/settings.json

Use a your favourite text editor and edit the file settings.json. At least the server.host and db.username and db.password have to be changed. Furthermore you should change the log path:

{
  "allowedOrigins": [],
  "dailyNewSyncsLimit": 3,
  "db": {
    "authSource": "admin",
    "connTimeout": 30000,
    "host": "127.0.0.1",
    "name": "xbrowsersync",
    "username": "xbrowsersyncdb",
    "password": "<password>",
    "port": 27017
  },
  "log": {
    "file": {
      "enabled": true,
      "level": "info",
      "path": "/home/<username/xbrowsersync/api/log/xbrowsersync.log",
      "rotatedFilesToKeep": 5,
      "rotationPeriod": "1d"
    },
    "stdout": {
      "enabled": true,
      "level": "info"
    }
  },
  "maxSyncs": 5242,
  "maxSyncSize": 512000,
  "server": {
    "behindProxy": false,
    "host": "0.0.0.0",
    "https": {
      "certPath": "",
      "enabled": false,
      "keyPath": ""
    },
    "port": 8080
  },
  "status": {
    "allowNewSyncs": true,
    "message": "",
    "online": true
  },
  "tests": {
    "db": "xbrowsersynctest",
    "port": 8081
  },
  "throttle": {
    "maxRequests": 1000,
    "timeWindow": 300000
  }
}

Create a service & start xBrowserSync

Create a service file under ~/etc/services.d/xbrowsersync.ini and replace <username> with your Uberspace username:

[program:xbrowsersync]
command=node /home/<username>/xbrowsersync/api/dist/api.js
startsecs=60
autostart=yes
autorestart=yes

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

Using xBrowserSync

If your installation was successful you now can reach xBrowserSync by pointing with your browser to your specified domain and see a default status page.

Warning

Always take a backup of your browsers bookmarks. For example by using your browsers bookmark export function before start using xBrowserSync.

Now you can install the xBrowserSync AddOn to your Browser. Open the settings panel and enter your personal xBrowserSync URL. Then go back and follow the AddOn instructions.

Updates

Note

Check the update feed regularly to stay informed about the newest version.

If there is a new version available, update your branch according to the version number (v1.1.18)

[isabell@stardust ~]$ cd ~/xbrowsersync/api
[isabell@stardust api]$ git pull origin v1.1.18
[isabell@stardust api]$

Tested with xBrowserSync 1.1.18, Uberspace 7.2.8.2

Written by: Phil <development@beph.de>