/api-docker

xBrowserSync API for Docker

Primary LanguageJavaScript

xBrowserSync

API for Docker

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 Docker files required to get your own xBrowserSync API service up and running in moments, either by running the API image alone or by orchestrating a production-ready HTTPS service with database and reverse proxy.

Running the API image

Running the API image alone requires that you have a MongoDB instance and (ideally) a web server to reverse proxy the API behind.

  1. Create a file named settings.json and include any required custom settings values, such as those for connecting to your MongoDB instance. For example, if you are running Docker and MongoDB on a windows server, you would point the service at the MongoDB instance running on the host using the following settings:

    {
  "db": {
    "host": "host.docker.internal"
  }
}

  2. (Optionally) create the following environment variables on your host to store the username and password required to access the xBrowserSync database on your MongoDB instance:

    • XBROWSERSYNC_DB_USER
    • XBROWSERSYNC_DB_PWD

  3. Run the following command to start an API container, providing the actual path to the settings.json file created in step 1. The service will be exposed via port 8080. If you did not create the environment variables in step 2, you will need to provide the actual username and password values in line, i.e. -e XBROWSERSYNC_DB_USER=YourDatabaseUsername -e XBROWSERSYNC_DB_PWD=YourDatabasePassword:

    $ sudo docker run --name xbs-api -p 8080:8080 -e XBROWSERSYNC_DB_USER -e XBROWSERSYNC_DB_PWD -v /path/to/settings.json:/usr/src/api/config/settings.json -d xbrowsersync/api

    You can now access your xBrowserSync API service at http://127.0.0.1:8080.

Running a production-ready service

If you do not already have a MongoDB instance or are intending to expose your xBrowserSync service over the internet then it is recommended to use the provided docker-compose.yml which will create fully configured containers for a MongoDB database, the xBrowserSync API and a traefik reverse proxy web server to run in front of the API. Traefik automatically acquires and updates SSL certificates from Let's Encrypt so that your xBrowserSync API service will run securely over HTTPS.

  1. Clone the api-docker GitHub repo:

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

  2. Secure the acme.json file as per traefik's requirements:

    $ sudo chmod 600 acme.json

  3. Open the .env file in a text editor and update the XBS_API_HOSTNAME value to correspond to the host name that the API service will be exposed over (ensure you have configured your DNS provider to point the desired host name to your host's IP address). Also, change the XBS_DB_USERNAME and XBS_DB_PASSWORD values to any of your choosing.

  4. Open the traefik.toml file in a text editor and update the email value on line 18 to your own email address in order to successfully acquire an SSL certificate from Let's Encrypt.

  5. (Optionally) open the settings.json file and include any custom settings values you wish to run on your service. Important: do not change the db.host value.

  6. Run the following command to start the containers:

    $ sudo docker-compose up -d

    You can now access your xBrowserSync API service over HTTPS at the value of XBS_API_HOSTNAME defined in the .env file.

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.

Install Compose on Linux systems On Linux, you can download the Docker Compose binary from the Compose repository release page on GitHub. Follow the instructions from the link, which involve running the curl command in your terminal to download the binaries. These step-by-step instructions are also included below.

For alpine, the following dependency packages are needed: py-pip, python-dev, libffi-dev, openssl-dev, gcc, libc-dev, and make.

Run this command to download the current stable release of Docker Compose:

sudo curl -L "https://github.com/docker/compose/releases/download/1.25.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose To install a different version of Compose, substitute 1.25.0 with the version of Compose you want to use.

If you have problems installing with curl, see Alternative Install Options tab above.

Apply executable permissions to the binary:

sudo chmod +x /usr/local/bin/docker-compose Note: If the command docker-compose fails after installation, check your path. You can also create a symbolic link to /usr/bin or any other directory in your path.

For example:

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose