Skip to content

Commit c2c67e0

Browse files
nero120nero120
committed
Updated README to include Docker info.
1 parent 983ff41 commit c2c67e0

File tree

1 file changed

+65
-51
lines changed

1 file changed

+65
-51
lines changed

‎README.md

Lines changed: 65 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -12,58 +12,32 @@ This repository contains the source code for the REST service API that client ap
1212

1313
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](https://www.xbrowsersync.org/#getinvolved) also!
1414

15-
## Prerequisites
15+
## Running with Docker
1616

17-
- [Node.js](https://nodejs.org/)
18-
- [mongoDB](https://www.mongodb.com/)
17+
The easiest way to get up and running is by using [Docker](https://www.docker.com/) 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.
1918

20-
## Upgrading from an earlier version
19+
Once you have installed Docker you can use the [xBrowserSync API Docker image](https://hub.docker.com/r/xbrowsersync/api) to get a production-ready xBrowserSync service up and running with minimal effort (view the [README](https://github.com/xbrowsersync/api-docker/blob/master/README.md) for more information).
2120

22-
### <= v1.1.5
21+
## Manual installation
2322

24-
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:
23+
Whilst running in a Docker container is the recommended way to run your xBrowserSync service, you can
2524

26-
```
27-
"db": {
28-
"authSource": "xbrowsersync"
29-
}
30-
```
25+
### Prerequisites
3126

32-
Config settings for logging has also changed so ensure you update your `config/settings.json` file if you have customised logging settings.
33-
34-
### <= v1.0.3
35-
36-
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.
37-
38-
To export existing syncs, run the following command:
39-
40-
```
41-
mongoexport --db xBrowserSync -c bookmarks --out /path/to/export/file
42-
```
43-
44-
Then to delete the database, run the following commands in the mongo shell:
45-
46-
```
47-
use xBrowserSync
48-
db.dropAllUsers()
49-
db.dropDatabase()
50-
```
27+
- [Node.js](https://nodejs.org/)
28+
- [MongoDB](https://www.mongodb.com/)
5129

52-
Once you've upgraded and completed the installation steps below, you can import the syncs by running the following command:
30+
### 1. Clone the xBrowserSync API source repo
5331

54-
```
55-
mongoimport --db xbrowsersync -c bookmarks --file /path/to/export/file
56-
```
32+
$ git clone https://github.com/xbrowsersync/api.git
5733

58-
## Installation
34+
### 2. Install and build xBrowserSync API package
5935

60-
### 1. Install and build xBrowserSync API package
61-
62-
CD into the source directory and install dependencies (use `unsafe-perm` flag if you get any permissions issues whilst trying to install):
36+
(Use the `unsafe-perm` flag if you get any permissions issues whilst trying to install):
6337

6438
$ npm install --unsafe-perm
6539

66-
### 2. Configure mongoDB databases
40+
### 3. Configure MongoDB databases
6741

6842
1. Run the following commands in the mongo shell:
6943

@@ -113,7 +87,7 @@ CD into the source directory and install dependencies (use `unsafe-perm` flag if
11387
db.bookmarks.createIndex( { "lastAccessed": 1 }, { expireAfterSeconds: 21*86400 } )
11488
```
11589
116-
### 3. Modify configuration settings
90+
### 4. Modify configuration settings
11791
11892
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:
11993
@@ -132,12 +106,12 @@ Config Setting | Description | Default Value
132106
`allowedOrigins` | Array of origins permitted to access the service. Each origin can be a `String` or a `RegExp`. For example `[ 'http://example1.com', /\.example2\.com$/ ]` will accept any request from `http://example1.com` or from a subdomain of `example2.com`. If the array is empty, all origins are permitted | `[]` (All origins permitted)
133107
`dailyNewSyncsLimit` | The maximum number of new syncs that a single IP address can create per day. If this setting is enabled, logs are created in newsynclogs collection to track IP addresses (cleared the following day). Set as `0` to disable. | `3`
134108
`db.authSource` | The database to use for authentication. | `admin`
135-
`db.connTimeout` | The connection timeout period to use for mongoDB. Using a high value helps prevent dropped connections in a hosted environment. | `30000` (30 secs)
136-
`db.host` | The mongoDB server address to connect to, either a hostname, IP address, or UNIX domain socket. | `127.0.0.1`
137-
`db.name` | Name of the mongoDB database to use. | `xbrowsersync`
138-
`db.username` | Username of the account used to access mongoDB. Set as empty string to use environment variable `XBROWSERSYNC_DB_USER`. | (Empty string, defers to environment variable)
139-
`db.password` | Password of the account used to access mongoDB. Set as empty string to use environment variable `XBROWSERSYNC_DB_PWD`. | (Empty string, defers to environment variable)
140-
`db.port` | The port to use to connect to mongoDB. | `27017`
109+
`db.connTimeout` | The connection timeout period to use for MongoDB. Using a high value helps prevent dropped connections in a hosted environment. | `30000` (30 secs)
110+
`db.host` | The MongoDB server address to connect to, either a hostname, IP address, or UNIX domain socket. | `127.0.0.1`
111+
`db.name` | Name of the MongoDB database to use. | `xbrowsersync`
112+
`db.username` | Username of the account used to access MongoDB. Set as empty string to use environment variable `XBROWSERSYNC_DB_USER`. | (Empty string, defers to environment variable)
113+
`db.password` | Password of the account used to access MongoDB. Set as empty string to use environment variable `XBROWSERSYNC_DB_PWD`. | (Empty string, defers to environment variable)
114+
`db.port` | The port to use to connect to MongoDB. | `27017`
141115
`log.file.enabled` | If set to true, [Bunyan](https://github.com/trentm/node-bunyan) will be used to capture minimal logging (service start/stop, new sync created, errors) to file. Logged messages are output to `log.file.path` and the log file is rotated automatically each period set by `log.file.rotationPeriod`, resulting in files "`log.file.path`.0", "`log.file.path`.1", etc. | `true`
142116
`log.file.level` | Bunyan log level to capture: `trace`, `debug`, `info`, `warn`, `error`, `fatal`. | `info`
143117
`log.file.path` | File path to log messages to (ensure the account node is running as has permission to write to this location). | `/var/log/xBrowserSync/api.log`
@@ -156,16 +130,16 @@ Config Setting | Description | Default Value
156130
`status.allowNewSyncs` | Determines whether users will be allowed to create new syncs on this server. Note: if this setting is set to false, users who have already synced to this service and have a sync ID will still able to get and update their syncs. | `true`
157131
`status.message` | This message will be displayed in the service status panel of the client app when using this xBrowserSync service. Ideally the message should be 130 characters or less. | (Empty string, no message set)
158132
`status.online` | If set to true no clients will be able to connect to this service. | `true`
159-
`tests.db` | Name of the mongoDB database to use for integration tests. | `xbrowsersynctest`
133+
`tests.db` | Name of the MongoDB database to use for integration tests. | `xbrowsersynctest`
160134
`tests.port` | Port to use for running tests. | `8081`
161135
`throttle.maxRequests` | Max number of connections during `throttle.timeWindow` milliseconds before sending a 429 response. Set as `0` to disable. | `1000`
162136
`throttle.timeWindow` | Amount of time (in milliseconds) before throttle counter is reset. | `300000` (5 mins)
163137
164-
### 4. Create log folder
138+
### 5. Create log folder
165139
166140
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.
167141
168-
### 5. Run xBrowserSync service
142+
### 6. Run xBrowserSync service
169143
170144
$ node dist/api.js
171145
@@ -195,6 +169,44 @@ You can then run the integration tests by running the following command:
195169
196170
$ npm run integrationtests
197171
172+
## Upgrading from an earlier version
173+
174+
### <= v1.1.5
175+
176+
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:
177+
178+
```
179+
"db": {
180+
"authSource": "xbrowsersync"
181+
}
182+
```
183+
184+
Config settings for logging has also changed so ensure you update your `config/settings.json` file if you have customised logging settings.
185+
186+
### <= v1.0.3
187+
188+
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.
189+
190+
To export existing syncs, run the following command:
191+
192+
```
193+
mongoexport --db xBrowserSync -c bookmarks --out /path/to/export/file
194+
```
195+
196+
Then to delete the database, run the following commands in the mongo shell:
197+
198+
```
199+
use xBrowserSync
200+
db.dropAllUsers()
201+
db.dropDatabase()
202+
```
203+
204+
Once you've upgraded and completed the installation steps below, you can import the syncs by running the following command:
205+
206+
```
207+
mongoimport --db xbrowsersync -c bookmarks --file /path/to/export/file
208+
```
209+
198210
## VS Code
199211
200212
If you're using [VS Code](https://code.visualstudio.com/), you have the following launch configurations:
@@ -204,6 +216,8 @@ If you're using [VS Code](https://code.visualstudio.com/), you have the followin
204216
3. Run unit tests: Will run and debug all tests in `test/unit` folder.
205217
4. Run integration tests: Will debug all tests in `test/integration` folder.
206218
207-
## Issues
219+
Note: we recommend [VSCodium](https://github.com/VSCodium/vscodium/) for running VSCode without Microsoft's proprietary binaries and telemetry/tracking.
220+
221+
## Issues and feature requests
208222
209-
If you've found a bug or wish to request a new feature, please submit it [here](https://github.com/xbrowsersync/api/issues/).
223+
Please log Docker-related issues in the [api-docker Issues list](https://github.com/xbrowsersync/api-docker/issues), 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](https://github.com/xbrowsersync/api/issues/).

0 commit comments

Comments
 (0)