Receive the latest in our newsletter. More
Receive the latest in our newsletter. Less
Something went horribly wrong with your application submission. Please try again later.

PINRemote Image

PINRemote Image

User Guide

Requirements

Mobile


iOS: Minimum SDK version: 9.0 or higher

App Configurations

Before deploying all the necessary components to enable the Codavel Performance Service, an App must be configured in Codavel’s private area. In case you have already configured your App, you may skip this section. Otherwise, please follow these steps:the deployment id and the deployment secret



1. Login into
https://private.codavel.com/

a. If you do not have access, please contact your dedicated account manager, he will give you access to the console.


2. Add a new app

a. Go to Home and click “NEW APP”

b. Fill in the fields, namely


1. Give the app a name (descriptive)

2. Add the package name (Android) and/or bundle identifier (iOS) of your app. If it doesn’t match with your app, the traffic will be discarded.

3. Choose the App Type on-premises to use bolina on your own infrastructureChoose the App Type CDN to use Codavel Performance Service.

4. Click in the button CREATE APP


3. The deployment is ready to use. The creation status should say Deployment ready, and you should receive an email notification shortly

4. Click the app info button (?) to see the deployment id and the deployment secret


5. Take note of both deployment id and secret, you will need them later.

Integration

Integrate Mobile SDK

The integration can be achieved by following this instructions:

1. Install Bolina Interceptor into your project through  CocoaPods, a dependency manager for Objective-c and Swift.

a. Install CocoaPods, by running the following commands in a terminal:


sudo gem install cocoapods

pod setup

b. Then, you’ll need to create a file named ‘Podfile’ in the same directory as your Xcode project (.xcodeproj) file with the following content:


target "MyTargetName" do

     platform :ios, '9.0'

     use_frameworks!

    (...)
     pod 'BolinaInterceptor', :http=>'https://artifact.codavel.com:8081/artifactory/ios/BolinaInterceptor_<VERSION>.zip'
    (...)
end 

The most recent version, is available in the private area, inside instructions.

c. Install the dependencies in your project using the command:


pod install

d. To build your app with the dependencies, you need to open the generated Xcode workspace (.xcworkspace) instead of the project file:


open <YourProjectName>.xcworkspace

2. Make sure that, before performing any HTTP request (a good place would be the :didFinishLaunchingWithOptions: method in your AppDelegate), you import and start the interceptor:


a. Import Bolina interceptor:


import BolinaInterceptor

b. Initialize the Bolina Configuration and set the Bolina Configuration domain name:


let config = BolinaConfiguration.initBolinaConfiguration() as! BolinaConfiguration
config.setDomain("<BOLINA_SERVER_URL>")


c. [optional] Configure your Origin:


config.addBolinaURLReplacement(“<your.cdn.com>”, url: “ <your.origin.com>”)


With this configuration, all requests intercepted by Bolina that would originally be sent to <your.cdn.com>, will be sent to a Bolina Server, that then will fetch the resource from <your.origin.com>. In case the Bolina transfer fails, the requests will be sent to <your.cdn.com>, as before. You can add multiple entries to be replaced. Otherwise, without this configuration, Codavel Performance Service servers will perform the same request as your HTTP clients would, to your current CDN or Origin.

d. Start the Bolina interceptor:


BolinaInterceptor.start("<APP_ID>", withSecret: "<APP_SECRET>", with: config)

e. Add the Bolina interceptor as a configuration of PINURLSessionManager and use that session manager to perform the HTTP requests:


let configuration = URLSessionConfiguration.default
if configuration.protocolClasses != nil {
  configuration.protocolClasses!.insert(CdvlURLProtocol.self, at: 0)
}
manager = PINURLSessionManager(sessionConfiguration: configuration)

f. Make sure you stop the interceptor whenever you don’t need it:

BolinaInterceptor.stop()

Other options to integrate:

  • In case you use Alamofire’s default shared manager, we recommend creating a new Alamofire.SessionManager registered with Bolina as a Singleton, and use that instance to perform the HTTP requests. An example of how to create one is below:

class BolinaAlamofireManager {

    static let shared = BolinaAlamofireManager()
    
    private var manager: Alamofire.Session = Alamofire.Session()
    
    init() {
        let configuration = URLSessionConfiguration.default
        BolinaInterceptor.registerBolina(configuration)
        
        manager = Alamofire.Session(configuration: configuration)
    }
}

Then you are able to use this manager in your application using this call:

 BolinaAlamofireManager.shared.manager.request(
(...)


Configure Actions in App

Configure actions in App


Bolina SDK can collect the performance data between two points in your app code. This way you can easily compare the network performance of the app requests with and without bolina in a dashboard in your Bolina Performance Console. Bolina SDK provides a method to start the trace of an action, another one to stop the trace, and another one to add optional metadata.


1. When you want to mark the start of an action, add the following line to your code


String action_id = InterceptorSingleton.getInstance().startAction(“open app”, (bolina ? "BOLINA" : "HTTP"));

2. When you want to mark the stop of the same action, add the following line to your code:


InterceptorSingleton.getInstance().stopAction(action_id);

3. When you want to add metadata to the action, add the following lines to your code:


JSONObject metadata = new JSONObject();
metadata.put(“test”,”testing-metadata”);
metadata.put(“test_int”,123);
InterceptorSingleton.getInstance().addActionMetadata(action_id,metadata);

4. When you finish collecting data to the action, add the following line to your code:


InterceptorSingleton.getInstance().processAction(action_id);

Example:

Trace the time to start a video:

1. Call startAction when the user press the play button and give it a name, e.g. “video start”

2. Call stopAction when the video starts playing

3. Call processAction to save the action and send the action stats to your dashboard


Advanced Configurations

Advanced Configurations


Bolina SDK allows the configuration of some advanced settings for enabling some features, configuring security options and increasing the debug level. Please, before changing these settings make sure you know what you are doing. All the methods below are accessible via the BolinaConfiguration object that you need to pass to InterceptorSingleton.startInterceptor()


App settings


  • addBolinaURLReplacement(String originalURLRegex, String bolinaURL) – Adds a new rule to be executed at each HTTP request. If the URL matches the expression configured, then Bolina will replace the matched expression with the configured URL. In case of Bolina fallback, the original URL will be used


  • addFallbackURLReplacement(String bolinaURLRegex, String originalURL) – Adds a new rule to be executed in case of Bolina fallback or performing A/B testing. If the URL used by bolina matches the expression configured, then Bolina will replace the matched expression with the configured URL.

  • setConfigFolder(String configFolder) – Sets the path used by Bolina core to store cached info. Default: application specific cache directory on the filesystem.


A/B Testing setting


  • setUseABTestingPerSession(boolean useABTestingPerSession) – Enables or disables the ab testing per session. This flag changes the behavior of setABTestPercentage. When this flag is set to true, the ab test percentage is calculated per session, otherwise, it is calculated per request. Here we assume a session is a new app start. Default: false

  • setABTestPercentage(int abTestPercentage)  – Sets the percentage of requests or sessions using Bolina. Should be used with setUseABTestingPerSession to define if the ab testing is per session or per request. Default: 100 , meaning all requests or all sessions are using Bolina.

Verbose settings


  • setVerboseLevel(String verboseLevel) – Changes the verbose level of Bolina client. Accepted values: “critical”(less logs), “info”, “debug”, “trace”(more logs). Default: critical


Protocol settings


  • setBolinaHandlerPattern(Pattern bolinaHandlerPattern) – Sets the URLs to be handled via bolina. Any URL that match this pattern will use bolina, on the other hand, a URL that does not match this pattern will be transferred using regular HTTP. default: Pattern.compile(“.*”), meaning all requests are accelerated

  • setCertsEnabled(boolean enableCerts) – Enables/Disable the use of SSL certificates. Default: true.

  • setAllowSelfSignedCerts(boolean allowSelfSignedCerts) – Enables/Disable the use of self signed SSL certificates. We strongly recommend the use of this option only for testing purposes. Default: false.

  • setMaxMemoryAllowed(long maxMemoryAllowed) – Sets the maximum amount of memory used by bolina core. Default: 10MB

  • setZeroRtt(boolean enableZeroRtt) – Enables or disables the use of 0-RTT in Bolina. Default: enabled

  • setTimeToKeepAlive(int timeToKeepAlive) – Sets the maximum time that a connection will be kept alive, in milliseconds. Default: 120s

Insights settings


  • setMonitorPercentage(int monitorPercentage) – Sets the percentage of requests to be traced for detailed statistics in the insights dashboard. A value of 100 means all requests appear in the dashboard. Default: 100

Installation Guide

Infrastructure Overview

Here you will find all the necessary instructions to deploy all the server infrastructure required to run Codavel Performance Service, while giving a brief overview of the system architecture and behavior.

The Codavel Performance Service is a service that improves content delivery for mobile apps, presenting robustness against latency and packet loss, regardless of the user’s network, device, location, or time.

Regarding its architecture, it is composed by multiple entities, each one with its own responsibility:


  • Bolina SDK: an SDK that can be integrated into any Android or iOS application, and enables the access to the Codavel Performance Service.

  • Management: Automatically orchestrates the number of running Bolina core instances, based on the overall system usage, and propagates the address and availability of each instance to Service discovery.

  • Bolina Core: Handles all Bolina traffic sent from Bolina SDK and translates it to the original protocol. Then, it fetches the resource from the Original Content Server, as a regular HTTP, before sending the data back to Bolina SDK through Bolina protocol. It also propagates periodically its availability to the Management component, which can be one of the following three stages:

  1. Available: Below its capacity, and is ready to accept new clients.


  1. Warning: Reaching its maximum capacity, and it should not accept new clients in order to stabilize its usage and avoid getting into the Critical stage.


  1. Critical: Above its capacity, and the overall performance could be affected. It should stop receiving traffic until it drops at least to a Warning stage.

  • Service Discovery: Has information regarding the address of each running instance of Bolina Core and its availability. This data can be sent to a public HTTP endpoint at each cluster update.

  • Shield (Coming soon): Balances the incoming traffic between all the Bolina Core instances, redirecting all new clients to the most suitable instance, based on their availability, while blocking all the other non-authorized traffic from entering the infrastructure.

  • Cache (Coming soon): Stores the HTTP requests made by Bolina Core during a certain amount of time, in order to reduce the traffic to and usage of the Origin, and also reducing the latency between Bolina Core and the HTTP content.

Deploy Server Components

Requirements


  • A pre-configured Kubernetes cluster with at least 3 worker nodes;
  • Kubeconfig file, to allow access to the cluster during the deployment;
  • Git client, to download our installation project;
  • Docker, to locally run one container during the installation process.


Instructions

The following instructions will deploy all the necessary components to enable the Codavel Performance Service, and must be followed in this order:

1. Download installation project

In order to access all the configuration files necessary for the deployment, enter the following command in a machine with access to the kubernetes cluster through kubectl.

git clone 
https://gitlab.com/codavel/kubernetes-deployment.git
cd kubernetes-deployment

2. Management

The management component of Bolina is composed of two different services:

Control: Receives information from all the running Bolina core instances and aggregates that data into storage. It is based on Consul, and of a cluster of three Consul instances, each one deployed as a replica of a kubernetes statefulset and running in different kubernetes nodes. Every time that a Bolina core instance changes its availability, or the number of instances running changes, it propagates the information to the Scaling service and to the Service Discovery component, if enabled.

Scaling: Watches the control service for any update, and based on the number of running Bolina core instances and its availability, scales the number of machines if necessary to ensure that the percentage of available instances is always above a certain threshold.

To provide access to Consul’s statefulset by the other components, we deploy a kubernetes service that redirects the traffic on the following ports to one Consul running node:

  • 8300 (TCP): Consul’s RPC address
  • 8500 (TCP): Consul’s HTTP API
  • 8600 (TCP and UDP): Consul’s DNS server
  • 8301 (TCP and UDP): Consul’s Serf LAN port
  • 8302 (TCP and UDP): Consul’s Serf WAN port

To deploy the Bolina Management component follow these steps:

  • Generate and store a Consul Gossip Encryption Key, a shared key that will be used to encrypt the communication between consul agents

export CONSUL_KEYGEN=$(sudo docker run -it --entrypoint=/bin/sh consul:latest -c "consul keygen")
kubectl create secret generic consul --from-literal="consul-encryption-key=${CONSUL_ENCRYPTION_KEY}"

  • Store the necessary Consul’s config files, that will be loaded to each consul node


kubectl create configmap consul-config-server --from-file=management/consul/config/server.json
kubectl create configmap consul-config-client --from-file=management/consul/config/client.json

  • Apply the consul’s service and cluster access roles


kubectl apply -f management/consul/consul-service-account.yaml
kubectl apply -f management/consul/consul-cluster-roles.yaml

  • Start the service, that will redirect the traffic on the previously stated ports to one of the three consul pods


kubectl create -f management/consul/consul-service.yaml

  • Deploy the control statefulset, that will start three consul pods


kubectl create -f management/consul/consul-statefulset.yaml

  • In order to orchestrate the number of running Bolina core instances, the scaling service needs a kube-config file that grants access to the kubernetes cluster. This could be done by creating a config-map with that file (replace with the complete path of the kube-config file, which must be named “config”. A common location is .kube/config inside your home folder):


kubectl create configmap kube-config --from-file=<path of kube config>

3. Bolina Core

The Bolina Core is deployed as a kubernetes deployment, where the number of replicas is controlled by the Scaling component, based on the system usage.

Each instance of Bolina core is represented by a kubernetes pod, and must have internet access and to be accessed directly (on port 9001/tcp and 9002/udp) through Bolina Shield (if enabled) or Bolina SDK. In order to achieve this, each pod runs on a different kubernetes node, using hostPort to expose the following ports on the node that hosts the containers:

  • 9001 (TCP): Bolina’s TCP traffic
  • 9002 (UDP): Bolina’s UDP traffic
  • 8300 (TCP): Consul’s RPC address
  • 8500 (TCP): Consul’s HTTP API
  • 8600 (TCP and UDP): Consul’s DNS server
  • 8301 (TCP and UDP): Consul’s Serf LAN port
  • 8302 (TCP and UDP): Consul’s Serf WAN port

The steps to create the deployment for the Bolina Core are the following:

  • Store the default Bolina configuration files, to be loaded by the Bolina container

kubectl create configmap bolina-config --from-file=bolina-core/bolina/config/bolina_config.template.json

  • [optional] Copy your server certificates to the appropriate place (replace and with the full path for your full chain and priv key, respectively). By default, the server will use self-signed certificates, not advised for production environments, and we strongly recommend to replace them with your own certificates with the following commands:


cp bolina-core/bolina/config/certs/

  • Store the server certificates in a kubernetes configmap


kubectl create configmap bolina-certs --from-file=bolina-core/bolina/config/certs/

  • Store your Deployment ID and Secret (see section Create Deployment for instructions on how to obtain that information), to be loaded by the Bolina container

kubectl create secret generic bolina --from-literal="bolina-deployment-id=" --from-literal="bolina-deployment-secret="

  • [optional] By default, each client will advertise the kubernetes node IP address, which is only accessible from inside the kubernetes cluster. If you did not enable the Bolina Shield component and wish to access the service from the outside, edit the line 76 of the file bolina-core/bolina/bolina-deployment.yaml and replace the value $NODE_IP in the expression (…)export PUBLIC_IP=$NODE_IP(…) with the desired expression/command to fetch the machines public IP.


export PUBLIC_IP=$(curl http://169.254.169.254/latest/meta-data/public-ipv4)

  • Start Bolina core Deployment. This will create only the configuration for the deployment, as the number of replicas starts at 0. This value is updated afterwards by the Scaling component

kubectl create -f bolina-core/bolina/bolina-deployment.yaml

  • Start the scaling deployment, what will launch one pod and start orchestrating the number of Bolina core instances

kubectl create -f management/scaling/watcher.yaml


4. [optional] Service Discovery

The information regarding the available Bolina instances can be obtained by using our Service Discovery component. This entity parses the information obtained from our management component and propagates that information to a configurable HTTP endpoint each time there is an update on the number of instances running or its availability.

If you wish to enable this component, follow this instructions:

  • Define the HTTP endpoint to where the information should be sent (replace <https://your_endpoint_url:port/endpoint> with the actual endpoint):

kubectl create secret generic bolina-service-discovery --from-literal="service-discovery-endpoint=<https://your_endpoint_url:port/endpoint>"

  • Start the service discovery, that will launch one pod that will start communicating with the defined endpoint and propagate the information


kubectl create -f service-discovery/control-plane.yaml

For each update, the configured endpoint will receive a POST message containing a JSON message composed by an array of Bolina Endpoints. Each value represents an available connection to a Bolina core endpoint, and has the following information:

  • IP Address (String): [“Address“][“IP“]
  • TCP Port (int): [“Address“][“Port“][“TCP”]
  • UDP Port (int): [“Address“][“Port“][“TCP”]
  • Server ID (String: a random identifier, unique for each Bolina core instance): [“Metadata“][“ServerID“]
  • Status (String: information regarding the instance’s availability): [“Metadata“][“Status“]
  • “passing”: Instance can accept new clients
  • “warning”: Instance should only receive data from current clients
  • “critical”: The instances is not available

Below is an example for two Bolina endpoints, available at the IP address 1.2.3.4 and 4.5.6.7. listening for UDP on port 9002, listening for TCP on port 9001 and with the ID -805390934 and 202130133, respectively:


[
  {
    "Address": {
      "IP": "1.2.3.4",
      "Port": {
        "TCP": 9001,
        "UDP": 9002
      }
    },
    "Metadata": {
      "ServerID": "-805390934",
      "Status": "passing"
    }
  },
  {
    "Address": {
      "IP": "5.6.7.8",
      "Port": {
        "TCP": 9001,
        "UDP": 9002
      }
    },
    "Metadata": {
      "ServerID": "202130133",
      "Status": "passing"
    }
  }
]


User Insights


To get more information about your deployment and the users connected through Codavel Performance Service, we provide an analytics page inside your Codavel account, with data collected from both Servers and Client’s SDKs.

In order to access it, please follow these steps:

1. Login into https://private.codavel.com/

a. If you do not have access, please contact our sales team, they will give you access to the console.

2. Go to the Insights section of the menu.

Network

a. Network – Contains overall HTTP requests information, along with some more detailed and low level statistics.


User

b. User – Contains action information and user behaviour. Note: To view data in this dashboard you need to add action data via SDK. Please see the section Configure Action in App of the respective interceptor.


Debug

c. Debug – Contains detailed information about possible errors that may affect your user experience, that can be used to identify and fix any configuration or deployment issues.


Codavel Open Source Projects.
Want to see examples of open source apps already integrated with Codavel?

access projects
More On-premises Installation Guides