Quick Start
Running Co-Browsing API On-Premise
To run Co-Browsing API on your infrastructure, you'll need to either run a Docker image that contains everything or host the components separately yourself.
If you have fewer than 5,000 Visitors online at any given time and no more than 100 concurrent Sessions, a single server will likely be enough. If you have more, you'll likely need to add more servers and scale Co-Browsing API horizontally by having a separate Redis cluster.
Pull our image from Docker Hub and run it with the environment variables listed below.
docker run -d \
-e BASE_ENDPOINT=https://cobrowsing.acmetech.com/ \
-e LICENSE_KEY=https://api.upscope.io/v1.3/.... \
-e SECRET_KEY=myrandomsecretkey... \
-p 5002:5002 \
upscope/onpremise
See the Configuration section for all available environment variables.
Host MongoDB Connection Issues
net.bindIp to listen on 0.0.0.0 in /etc/mongod.conf, or—if it's a security issue—on the Docker network. This is similar for Redis, which should listen to *:6379.We've created a simple startup script to easily start and configure Co-Browsing API to use with Docker.
- Download the startup script (.sh file).
- Edit its variables according to the data from your Co-Browsing API dashboard
Settings»On Premise. - Make it executable:
chmod +x start-on-premise.sh. - Run it:
./start-on-premise.sh.
Host MongoDB Connection Issues
net.bindIp to listen on 0.0.0.0 in /etc/mongod.conf, or—if it's a security issue—on the Docker network. This is similar for Redis, which should listen to *:6379.If you don't want to use Docker, you'll find Co-Browsing API binaries on the link provided in your Co-Browsing API dashboard Settings » On Premise.
This link never changes, so you can curl the binaries as part of your build process and automatically keep Co-Browsing API up to date. Any breaking change will have a new link, so you don't need to worry about that.
You can start the server by running:
BASE_ENDPOINT=http://localhost:5002 PORT=5002 \
LICENSE_KEY=https://api.upscope.io/v1.3/.... \
SECRET_KEY=myrandomsecretkey... ./upscope-data-linux
Installing Co-Browsing API on Your Website
After you run Co-Browsing API, the output will give you instructions for your JavaScript SDK installation code. It looks like this (notice {BASE_ENDPOINT}):
<script>
(function(w, u, d){if(typeof u!=="function"){var i=function(){i.c(arguments)};i.q=[];i.c=function(args){i.q.push(args)};
w.Upscope=i;var l = function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;
s.src='{BASE_ENDPOINT}/upscope.js';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};l();}}
)(window, window.Upscope, document);
Upscope('init');
Upscope('getWatchLink', console.log);
</script>
You can add that code to pages like you would with our cloud solution.
Your License Key
To run Co-Browsing API, you'll need to retrieve your license key. The license key can be downloaded to your server or read automatically from our server every time the server starts.
You'll need to enter the license key into the LICENSE_KEY environment variable. The LICENSE_KEY environment variable can be one of:
- The license key content (note it's multi-line)
- A file path to the license key content
- The URL to the license key, the preferred method
If you don't have to restrict the instance's interactions with the internet, entering the URL provided on the dashboard as the LICENSE_KEY environment variable is preferable as you won't need to update it when it expires.
Good to Know
Configuration
The following is configurable through environment variables:
| Environment Variable | Description | Default |
|---|---|---|
BASE_ENDPOINT | The base URL where this component will be mounted. For example, https://cobrowsing.acmetech.com/. It can be in a subdirectory. | (nil, required) |
LICENSE_KEY | Your unique Co-Browsing API license key (or a link to it). | (nil, required) |
SECRET_KEY | A unique secret key used to sign internal JWTs. It's very important this key is kept safe and it's at least 32 characters long. | (nil, required) |
AUTH_ENDPOINT | URL watch links will be redirected to for authentication. | https://app.upscope.io/onprem_redirect/TEAM_IDENTIFIER |
HOMEPAGE | URL unrecognized requests will be redirected to. | https://upscope.com/ |
MONGO_URI | URI to a single MongoDB instance, or MongoDB cluster | If omitted, mongodb://localhost:27017/upscope. (In Docker this starts MongoDB within the image). If set to an empty string, it will disable MongoDB. |
PORT | The port the server will listen on. | 5002 |
REDIS_URI | URI to Redis or a Redis cluster. | redis://localhost:6379. (In Docker this starts Redis within the image). |
REST_KEY | The authentication API key for your on-premise REST API. | (nil) |
SSL_REDIRECT | When set to on, the server will automatically redirect all requests to https. | off |
If you use MONGO_URI=mongodb://localhost/upscope with the Docker image, a MongoDB server will be installed inside the container to serve the application.
If you use redis://localhost/ with the Docker image, a Redis server will be installed inside the container to serve the application.
API Endpoint
Check the on-premise REST API docs to know how to make requests to the on-premise instance.
What Doesn't Work On-Premise?
Although we've made our on-premise version as similar as possible to the original, there are a few missing functionalities. You'll need to use Co-Browsing API cloud if you are interested in:
- IP geolocation features
- Session video recording
- Audio/video communication
Usage Without MongoDB
We are aware some of our customers cannot use MongoDB due to compliance reasons.
Co-Browsing API works fine without MongoDB, but the Search feature will be limited. You'll still be able to search by:
- Lookup code
- Unique ID
- Integration IDs