Installation Guide

This guide walks you through setting up the On-Premise Meaning Cloud platform.

The solution can be installed in a physical or virtual server. The minimum hardware requirements for the application servers are:

• 8 CPUs
• 16 GB RAM Memory
• 50 GB free hard disk space

Note

This is equivalent for instance to a c5.2xlarge machine in AWS.

• Recommended Operating System:
  • Ubuntu 22.04 LTS
  • A user with sudo permissions or access to the root user
• Tools
  • Docker >= 23.0.0
  • Docker Compose >= 2.15.1

Note

The platform should work in any machine with a relatively new Docker installation.

You will also need a license of the product to complete this guide.

The platform uses a MySQL database to store data. You will need to provide a database and the connection data in the bootstrap configuration step.

The installation process will connect to the database and set up the schema needed, so the user provided to connect to the database must have permissions to do it.

If you don’t have an external database available you can configure the bootstrap process to use the MySQL extension, it will deploy a MySQL server Docker container.

Disclaimer

It is your responsibility the management of the database, it is recommended to do regular backups to be protected in case of any failure. It is your responsibility the management of the database, it is recommended to do regular backups to be protected in case of any failure.

It is also recommended to perform a backup before starting the platform update process.

1. First, provision the server where the platform is going to be deployed.
2. Remember to install all software requirements and give root permissions to the user that is going to be deploying.

The bootstrap container performs the necessary steps to deploy the platform. The process follows these steps:

1. Run pre-checks to assure that all requirements are met.
2. Platform configuration and customization.
3. Download necessary container images and artifacts.
4. Platform launch.
5. Launch extensions (if configured).

There are some configurations to be made before launching the bootstrap process:

• Prepare the bootstrap volumes.
• Configure the bootstrap installation process.

The bootstrap process is performed inside a Docker container with some volume mounted to store configurations, artifacts, data, and more.

The volumes are:

• sentiment: platform artifact.
• dictionaries: platform artifact.
• lexicalbase: platform artifact.
• deepcatmodels: platform artifact.
• classmodels: platform artifact.
• docker.sock: the docker socket needed to launch containers in the host machine.
• platform_host_path: path where the platform deployment files will be placed.
• data_host_path: path where the platform stores its data.
• extra_vars.yml: file with platform customization parameters. See the configuration reference page.

To configure the volumes run the following commands to set variables and create the necessary directories:

# distribution name (should be 'general')
export dist=general

# path where the platform deployment files will be placed, recommended path /opt/onpremise
export platform_host_path=/opt/onpremise/$dist

# path where the platform stores its data, recommended path /mnt/onpremise
export data_host_path=/mnt/onpremise/data

# ensure the platform_host_path and the data_host_path exist and have the right permissions, they must be empty
mkdir -p $platform_host_path $data_host_path
chown -R $USER:$USER $data_host_path
chmod -R 777 $data_host_path

# platform customization parameters, recommended path: /opt/onpremise/bootstrap/extra_vars.yml
export extra_vars_path=/opt/onpremise/bootstrap/extra_vars.yml

# compose_project_name: docker compose project name (default: mc_onpremise)
export compose_project_name=mc_onpremise

To create the configuration file (extra_vars.yml) visit the bootstrap configuration guide and the reference section.

Once you have created the file, you can proceed to launch the bootstrap process.

To launch the bootstrap process use run this command:

# Start bootstrap process.
docker run --rm -it --name onpremise-bootstrap \
  -v ${compose_project_name:-mc_onpremise}_sentiment:/opt/onpremise/bootstrap/artifacts/sentiment \
  -v ${compose_project_name:-mc_onpremise}_dictionaries:/opt/onpremise/bootstrap/artifacts/dictionaries \
  -v ${compose_project_name:-mc_onpremise}_lexicalbase:/opt/onpremise/bootstrap/artifacts/lexicalbase \
  -v ${compose_project_name:-mc_onpremise}_deepcatmodels:/opt/onpremise/bootstrap/artifacts/deepcatmodels \
  -v ${compose_project_name:-mc_onpremise}_classmodels:/opt/onpremise/bootstrap/artifacts/classmodels \
  -v $extra_vars_path:/opt/onpremise/bootstrap/extra_vars.yml \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $platform_host_path:/opt/onpremise/${dist} \
  -v $data_host_path:/opt/onpremise/data \
  566712155668.dkr.ecr.eu-west-1.amazonaws.com/onpremise/bootstrap:0.1.0

The process should take around 10 minutes depending on the machine resources and the network speed.

Once the bootstrap container starts running you can follow the installation process with this command:

docker logs --follow onpremise-bootstrap

If the process is stopped manually or because an error occurred, it can be re-launched with the same command, but first it is necessary to remove the files of the previous installation, otherwise it will fail fast because the installation directory is not empty:

rm -rf $platform_host_path/<version>

After completion, check the platform is up and running running:

  docker container ls

At end, the installation logs show the url and credentials to access the platform web console.

Now, from the last lines of the installation logs retrieve the url and credentials shown, open a browser and navigate to the platform URL. If you didn’t configure the random password generation then the default credentials are admin for the user and admin for the password.

If you are using http, which does not offer encryption, the browser might complain about your password being leaked.

The next step is to activate the license.

Warning!

Requests to any of the APIs will be denied if there is not a valid license attached!

When you access the console for the first time you will see a warning icon like this in the upper right corner of the console:

That icon is warning that the license is not activated, to activate it refer to the licensing guide.

Once the license is correctly configured and working, just create a Project to start working:

• Go to Management → Users and Projects → Projects and create your first project. Each project has a license key associated, which is what you will be able to use to make calls to any of the APIs.
• If users are going to use the environment (for instance, to create resources in the Customization consoles), you will need to create users for them with the appropriate profile, and give them permission to access one or several projects. You can do this in Management → Users and Projects → Users.

When launching the bootstrap, there are two volumes that are bound to the host file system:

1. One where the platform deployment files are downloaded,
2. and another where the platform generated data will be stored.

As a result, when the bootstrap process finishes, there will be some files available in the host machine.

• Platform deployment files:

  • compose.yml: docker compose file where all services are defined.
  • env-config: file where are parameters of the platform are declared.
  • It is recommended to mount the path /opt/onpremise/$dist where $dist is the distribution of the platform to deploy (usually general). You can also use another path.

• Platform data:

  • It is important to place this information in a disk with enough space. The volume of the data will depend of the use of the platform.
  • For example, you could use an entire disk mounted in /mnt/onpremise/data in your server and then mount it to the bootstrap container.

A typical deployment will look like this when the bootstrap execution finish:

# platform deployment files in the host machine
/opt/onpremise/general/
└── 1.0.0
      ├── compose.yml
      └── env-config

# platform data in the host machine
/mnt/onpremise/data
└── data

The minimum recommended hardware for the On-premise Meaning Cloud platform, to provide a stable service to up to 50 concurrent users who make a non-intensive use of the platform (<= 1 request/sec), is a machine with 16 GB of RAM and 8 cores.

This recommendation is based on load tests, with a load of 50 simultaneous virtual users making a request per second. Which yielded the following results: an average HTTP request response time of ~400ms, with a minimum time of ~160ms and a maximum time of 600ms. Requests below the 90th percentile had an average response time of 536.19ms.

System stress tests suggest that for the above recommended hardware, sustained load limitations of the platform appear to be around 80 requests per second for several concurrent users.

It is important to note that these results are based on specific test conditions and may not scale linearly with additional users or requests. Depending on the use case and based on these limitations, it may be necessary to consider scaling the platform hardware to improve its performance under heavy load.

After installation you can check the platform setup is correct navigating to http://<platform_hostname>/console/install, you should see something like this:

If something is not correct please contact with us here.