Deploy from Source

OpenReplay can be deployed from source. Its main components (Backend, API and Frontend) need to be built and pushed to your own container registry, before doing the installation.

The minimum specs for the machine running OpenReplay are 2 vCPUs, 8 GB of RAM, 50 GB of storage, otherwise OpenReplay backend services won’t simply start. This should be enough for a low/moderate volume. If you’re expecting high traffic, you should scale from here.

1. Install docker:

sudo apt update
sudo apt install docker.io -y
user=`whoami`
sudo chown $user /var/run/docker.sock

2. Clone OpenReplay repo:

git clone https://github.com/openreplay/openreplay

1. Login to your container registry using docker login <registry_url>. If you have a docker hub account, then simply run docker login.

2. Build the backend components then push them to your container registry:

cd openreplay/backend
sudo IMAGE_TAG=<my_tag_number> PUSH_IMAGE=1 DOCKER_REPO=index.docker.io/<username> bash build.sh 

Note that the tag name can be any string you want, it’ll be created on your Docker Registry and it’ll be used to identify this particular version of the code (useful if you’re also modifying the code).

If everything goes well, you should have, in your Docker registry, a list of images built from the source code you had, ready to be installed. The list of images is:

• Storage
• Sink
• Integrations
• HTTP
• Heuristics
• Ender
• DB
• Assets
• Alerts
• Chalice

1. Create your container registry secret:

kubectl create secret -n app docker-registry my-registry-secret \
        --docker-server=MY_CONTAINER_REGISTRY_URL \ # not required if docker hub
        --docker-username=MY_CONTAINER_REGISTRY_USERNAME \
        --docker-password=MY_CONTAINER_REGISTRY_PASSWORD \
        --docker-email=no@email.local 

2. To use the components you just built and pushed to your container registry, update the vars.yaml file, located inside the openreplay/scripts/helmcharts folder. Just add a section for each image you have on your docker registry with the following information:

• repository: should point to MY_CONTAINER_REGISTRY_URL/COMPONENT_NAME (if you’re using Docker Hub, use the <username>/<component name> format instead)
• pullPolicy: set to “Always”
• tag: the value of IMAGE_TAG used when building Backend and API
• imagePullSecrets: the container registry secret

Note that any image you don’t reference inside the vars.yaml file will be deployed and installed from the official repository of OpenReplay, which means you won’t have the version built from your source code.

Below is an example for the alerts service:

alerts:
  image:
    repository: rg.fr-par.scw.cloud/foss/alerts
    pullPolicy: Always
    tag: "v1.4.2"
  imagePullSecrets: 
    - name: my-registry-secret

1. Open vars.yaml then edit:

• domainName: this is where OpenReplay will be accessible (i.e. openreplay.mycompany.com)

2. Install OpenReplay:

cd openreplay/scripts/helmcharts
helm upgrade --install databases ./databases -n db --create-namespace --wait -f ./vars.yaml --atomic
helm upgrade --install openreplay ./openreplay -n app --create-namespace --wait -f ./vars.yaml --atomic

If you ever modify the source code of the back-end services or the DB service, you’ll have to go back to step 3 and then run the above commands once again.

OpenReplay deals with sensitive user data and therefore requires HTTPS to run. This is mandatory, otherwise the tracker simply wouldn’t start recording. Same thing for the dashboard, without HTTPS you won’t be able to replay user sessions.

You must therefore bring (or generate) your own SSL certificate.

1. First, go to DNS service provider and create an A Record. Use the domain you previously provided during the installation step and point it to your machine using its public IP.

2. If you’re bringing your own certificate, create Kubernetes SSL secret using the following command: kubectl create secret tls openreplay-ssl -n app --key="private_key_file.pem" --cert="certificate.crt".

Note: If you don’t have a certificate, generate one, that auto-renews, for your subdomain (the one provided during installation) using Let’s Encrypt. Run cd openreplay/scripts/helmcharts && bash certmanager.sh and follow the steps.

3. If you wish to enable http to https redirection (recommended), then uncomment the below block, under the ingress-nginx section, in vars.yaml:

ingress-nginx: &ingress-nginx
  controller:
    config:
      ssl-redirect: true
      force-ssl-redirect: true

It’s worth mentioning that our ingress-nginx runs by default on ports 80|443, but this can be easily changed, if needed, in vars.yaml:

ingress-nginx: &ingress-nginx
  controller:
    service:
      ports:
        http: 80
        https: 443

4. Finally reinstall OpenReplay NGINX:

openreplay -R

Finally, if you’re also looking to build the front-end, you’ll have to build the image with the following line:

cd openreplay/frontend
IMAGE_TAG=<your tag> PUSH_IMAGE=1 DOCKER_REPO=myDockerHubID bash build.sh

Once this is done, go back to the vars.yaml file and add a section specific for the front-end, it should look similar to the ones you added before for alerts and chalice:

frontend:
  image:
    repository: <YOUR DOCKER REGISTRY>/frontend
    pullPolicy: Always
    tag: <YOUR TAG>
  imagePullSecrets: 
    - name: <YOUR SECRET>

With the new section added on the file, execute the openreplay -R (which is located inside the scripts/helmcharts folder) command and your new front-end should be running.

You’re all set now, OpenReplay should be accessible on your subdomain. You can create an account by visiting the /signup page (i.e. openreplay.mycompany.com/signup).

If you encounter any issues, connect to our Slack or check out our Forum and get help from our community.