Skip to content

Quick start

To run Upscope 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 Agents, a single server will likely be enough. If you have more, you'll likely need to add more servers and scale Upscope horizontally by having a separate REDIS cluster.


At a minimum, to use Upscope on-premise, you'll need:

  • A Redis instance or cluster;
  • A container to run the Upscope binaries in.

To enable our search functionality, you'll also want to run a MongoDB instance.

Usage without MongoDB

We are aware some of our customers cannot use MongoDB due to compliance reasons.

Upscope works fine without MongoDB, but the Search feature will be limited. You'll still be able to search by:

Docker image

You can install our Docker image using the following command:

docker pull upscope/onpremise:latest

Upscope binaries

If you don't want to use Docker, you'll find Upscope binaries on the link provided in your settings.

This link never changes so you can curl the binaries as part of your build process, and automatically keep Upscope up to date.

Any breaking change will have a new link, so you don't need to worry about that.

Your license key

To run Upscope 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 env var. The LICENSE_KEY env var 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 env var is preferable as you won't need to update it when it expires.

Good to know

Your Javascript SDK configuration is also embedded in your license key. This means you can still configure Upscope on your dashboard and then restart the server to apply the changes.


The following is configurable through Environment variables.

Environment variable Description Default
BASE_ENDPOINT The base URL where this component will be mounted. For example, It can be in a subdirectory. (nil, required)
LICENSE_KEY Your unique Upscope 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.
HOMEPAGE URL unrecognized requests will be redirected to.
MONGO_URI URI to a single MongoDB instance, or MongoDB cluster If omitted, mongodb://host.docker.internal:27017/upscope in Docker, or mongodb://localhost:27017/upscope out of Docker. 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://host.docker.internal:6379/0 in Docker, redis://localhost:6379 without Docker
REST_KEY The authentication API key for your on-premise REST API. Leave empty to disable the 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.

Running Upscope

After you have all your environment variables, you'll be able to start the Docker container by running:

docker run --rm -e 'BASE_ENDPOINT=http://localhost:5002' -e 'LICENSE_KEY=' -e 'SECRET_KEY=myrandomsecretkey' ... -e 'DOWNLOAD_USER=user-used-to-download-the-binary' -e 'DOWNLOAD_PASSWORD=password-used-to-download-the-binary' -e 'REST_KEY=the-rest-key' -p ${PORT}:5002/tcp -it upscope/onprem:latest

You can also give a name to the container, and keep it in background:

docker run --name myupscopecontainer -e 'BASE_ENDPOINT=http://localhost:5002' -e 'LICENSE_KEY=' -e 'SECRET_KEY=myrandomsecretkey' ... -e 'DOWNLOAD_USER=user-used-to-download-the-binary' -e 'DOWNLOAD_PASSWORD=password-used-to-download-the-binary' -e 'REST_KEY=the-rest-key' -p ${PORT}:5002/tcp upscope/onprem:latest

Stop the container:

docker stop myupscopecontainer

And then start it again:

docker start myupscopecontainer

Or you can start the server without Docker by running:

BASE_ENDPOINT=http://localhost:5002 PORT=5002 LICENSE_KEY= SECRET_KEY=myrandomsecretkey... ./upscope-data-linux

Unless you have started the Docker without the -it parameter, the output will give you instructions as to your Javascript SDK installation code, but it will generally look like something like this (notice {BASE_ENDPOINT}):

  (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('getWatchLink', console.log);

You can add that code to pages like you would with our cloud solution.

Load balancer?

If you run Upscope behind a load balancer, you'll want to enable the proxy protocol for Upscope to have access to the real IP address of the Visitor.

Integrating with the dashboard

To use the Upscope dashboard with Upscope on-premise, head to your on-prem settings and scroll down to cloud link.

You'll need to enter your BASE_ENDPOINT and your SECRET_KEY, and have an option to enter the email of who should be contacted if we need to reach out to quickly if we find a vulnerability we can't patch from remote.

Good to know

Even if you link on-premise to our cloud, our server will actually never make requests to your instance, and your instance will not report back to our servers.

To your Agents everything will look just like the regular cloud version does, but behind the scenes their browser will be in direct communication with your instance so we never touch your Visitors' data.

If you plan to use the REST API, you'll need to use the on-premise version of the API.

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 Upscope cloud if you are interested in:

  • Integrations with live chat software (other than a simple link in the attributes)
  • Screenshots
  • Session video recording
  • Audio / video communication