Installing Tracardi, an opensource Customer Data Platform

You are probably new to Tracardi. So a good way to start is to tell you what it is and how can you use it.

Tracardi is an open-source system that supports customer engagement and enhances the consumer experience.Tracardi is intended for anyone who carries out some type of customer interaction, be it through sales or service delivery. It automates how you want contact you customers or what data you would like to collect.

Tracardi is a distributed system. The installation I am describing is good for testing the system out. But you may need to go to the system documentation to find out how to install a Tracardi cluster.

Installation

There are basically 3 ways to install Tracardi:

• From docker image
• From source
• Production installation

Docker container installation

The easiest way to run Tracardi is to run it as a docker container.

Start database

Tracardi needs elasticsearch as its back-end. Please pull and run elasticsearch single node docker before you start Tracardi.

You can do it with this command.

docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.13.2

Start Tracardi API

Pull and run Tracardi backend.

docker run -p 8686:80 -e ELASTIC_HOST=http://<your-laptop-ip>:9200 -e USER_NAME=admin -e PASSWORD=admin tracardi/tracardi-api

Tracardi must connect to elasticsearch. To do that you have to set ELASTIC_HOST variable to reference your laptop's or server IP. Notice that we also set default user name and password.

One warning: Notice that when type http://localhost:9200 you try to connect to Elastic on localhost. This means that you're connecting to the docker itself as localhost means local in docker. Obviously elastic is not there, so Tracardi will never connect. Pass external ip for elastic. This may be your laptop IP if you are running Tracardi locally.

Start Tracardi GUI

Pull and run Tracardi Graphical User Interface.

docker run -p 8787:80 -e API_URL=//127.0.0.1:8686 tracardi/tracardi-gui

Visit Tracardi GUI

Visit http://127.0.0.1:8787 and login to Tracardi GUI.

Default username is: admin Default password is: admin

Tracardi API documentation

You can also install Tracardi form source.

Installation from source

Software prerequisites

• Docker
• Python w wersji 3.8
• Pip
• Python Virtual Environment
• PyCharm
• Git

Install the above software and we're ready to start.

Launching Elasticsearch on Ubuntu

We have two options:

• Installing elasticsearch as a service
• Installing elasticsearch as a docker

Elasticsearch as a service

The Elasticsearch components are not available in Ubuntu’s default package repositories. They can, however, be installed
with APT after adding Elastic’s package source list.

All of the packages are signed with the Elasticsearch signing key in order to protect your system from package spoofing.
Packages which have been authenticated using the key will be considered trusted by your package manager. In this step,
you will import the Elasticsearch public GPG key and add the Elastic package source list in order to install
Elasticsearch.

To begin, use cURL, the command line tool for transferring data with URLs, to import the Elasticsearch public GPG key
into APT. Note that we are using the arguments -fsSL to silence all progress and possible errors (except for a server
failure) and to allow cURL to make a request on a new location if redirected. Pipe the output of the cURL command into
the apt-key program, which adds the public GPG key to APT.

Open a terminal and enter:

curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -

Next, add the Elastic source list to the sources.list.d directory, where APT will look for new sources:

echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list

Next, update your package lists so APT will read the new Elastic source:

sudo apt update

Then install Elasticsearch with this command:

sudo apt install elasticsearch

Elasticsearch is now installed and ready to be configured.

Elasticsearch configuration

To configure Elasticsearch, we will edit its main configuration file elasticsearch.yml where most of its configuration
options are stored. This file is located in the /etc/elasticsearch directory.

Use your preferred text editor to edit Elasticsearch’s configuration file. Here, we’ll use nano:

sudo nano /etc/elasticsearch/elasticsearch.yml

The elasticsearch.yml file provides configuration options for your cluster, node, paths, memory, network, discovery, and
gateway. Most of these options are preconfigured in the file but you can change them according to your needs. For the
purposes of our demonstration of a single-server configuration, we will only adjust the settings for the network host.

Elasticsearch listens for traffic from everywhere on port 9200. You will want to restrict outside access to your
Elasticsearch instance to prevent outsiders from reading your data or shutting down your Elasticsearch cluster through
its REST API. To restrict access and therefore
increase security, find the line that specifies network.host, uncomment it, and replace its value with localhost so it
looks like this:

# ---------------------------------- Network -----------------------------------
#
# Set the bind address to a specific IP (IPv4 or IPv6):
#
network.host: localhost

We have specified localhost so that Elasticsearch listens on all interfaces and bound IPs. If you want it to listen only
on a specific interface, you can specify its IP in place of localhost. Save and close elasticsearch.yml. If you’re using
nano, you can do so by pressing CTRL+X, followed by Y and then ENTER .

These are the minimum settings you can start with in order to use Elasticsearch. Now you can start Elasticsearch for the
first time.

Start the Elasticsearch service with systemctl. Give Elasticsearch a few moments to start up. Otherwise, you may get
errors about not being able to connect.

sudo systemctl start elasticsearch

Testing elasticsearch

By now, Elasticsearch should be running on port 9200. You can test it with cURL and a GET request.

curl -X GET 'http://localhost:9200'

You should see the following response:

{
  "name" : "localhost",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "XHATygZ4R1C59dEXDUs-og",
  "version" : {
    "number" : "7.17.0",
    "build_flavor" : "default",
    "build_type" : "deb",
    "build_hash" : "bee86328705acaa9a6daede7140defd4d9ec56bd",
    "build_date" : "2022-01-28T08:36:04.875279988Z",
    "build_snapshot" : false,
    "lucene_version" : "8.11.1",
    "minimum_wire_compatibility_version" : "6.8.0",
    "minimum_index_compatibility_version" : "6.0.0-beta1"
  },
  "tagline" : "You Know, for Search"
}

If you see a response similar to the one above, Elasticsearch is working properly. If not, make sure that you have
followed the installation instructions correctly and you have allowed some time for Elasticsearch to fully start.

Elasticsearch as a docker container

Open a terminal and enter:

docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.13.2

You have run a single instance of elasticsearch in the console. When you want to stop it, press CTRL + C

Tip
If you want elasticsearch to run in the background, type:
docker run -d -p 9200: 9200 -p 9300: 9300 -e "discovery.type = single-node" docker.elastic.co/elasticsearch/elasticsearch:7.13.2

Download the source code

Open a terminal and go to the directory where you want to keep the code. Enter:

git clone https://github.com/Tracardi/tracardi  #(1)
git clone https://github.com/Tracardi/tracardi-api #(2)

1. Clones tracardi repository. Code will be available in tracardi folder.
2. Clones tracardi-api repository

Create virtual environments

Type:

cd tracardi-api
python3.8 -m venv venv  # (1)
cd ..
cd tracardi
python3.8 -m venv venv

1. Installs virtual environment with python 3.8

Tip

Before creating the virtual environment make sure you have version 3.8.x installed. Type python --version to see if the version is correct.

Install dependencies

Linux

```
# Activates virtual environment (1)
cd tracardi-api
source venv/bin/activate

# Install wheel
pip3 install wheel

# Installs dependencies
pip install -r app/requirements.txt

# Run code (2)
USER_NAME=admin PASSWORD=admin uvicorn app.main:application --host 0.0.0.0 --port 8686
```

1. Only tracardi-api is required to run the API. Tracardi library will be installed as dependency.
2. Sets default username: password as admin: admin and runs Tracardi API on port 8686.

Windows

```
cd tracardi-api
venv\Scripts\activate

// Installs dependencies
pip install -r app/requirements.txt

// Run code 
USER_NAME=admin PASSWORD=admin uvicorn app.main:application --host 0.0.0.0 --port 8686
```

Mac OS

```
// Activates virtual environment
cd tracardi-api
source venv/bin/activate

// Installs dependencies
pip install -r app/requirements.txt

// Run code
USER_NAME=admin PASSWORD=admin uvicorn app.main:application --host 0.0.0.0 --port 8686
```

Test access to documentation

Visit http://127.0.0.1:8686/docs for API documentation.