Overview
In this article, you will learn how to install the Kaholo Agents. There are 2 ways of installing the Kaholo Agent, (a) using the recommended 1. Docker, and 2. Native Installation.
1. Using Docker
We highly recommend using the docker agent if possible for consistency and ease of management. The agent image is public and can be found on the DockerHub in Kaholo.io/kaholo-agent.
Follow the steps below to install the Kaholo Agent using Docker:
Step 1: Pulling the Latest Image
| docker pull kaholoio/kaholo-agent:2.0.0 |
Step 2: Create Configuration File
Create a new file and name it kaholo-agent.conf . It will store key-value pairs for the following options:
| Options | Description |
|---|---|
| PORT | The port which the agent will run.
Note: the default port is 8090, if you use any other port, you will also need to adjust the docker run command |
| SERVER_URL | The URL of the Kaholo server that you want to connect to. |
| AGENT_KEY | A unique random 32 characters to identify this specific agent. |
| AMQP_HOST | The host of the queue, usually the same as the server. |
| AMQP_PORT | The port of the AMQP server is usually 5671. |
| AMQP_USER | “twiddlebugs” |
| AMQP_PASSWORD | “twiddlebugs” |
| AMQP_RESULT_QUEUE | “actions-outcome” |
| AMQP_CERT_PATH | The path to the agent crt file. |
| AMQP_KEY_PATH | The path to the agent pem file.
Note: when running inside docker, you will need to mount the local crt and pem files to the container and the path in the variable should be to the mounted path. |
For more examples, click here.
Step 3: Run a New Container
| docker run –restart unless-stopped -v <plugins-dir-path>:/usr/src/app/libs/plugins –env-file <path-to-conf-file> -d -p 8090:8090 kaholoio/kaholo-agent:latest |
Step 4: Extending the Agent
In case of a need for additional CLIs to be installed on the agent image, you can create a custom image based on the kaholo-agent image.
2. Native Installation
In a scenario where you need to have the agent run locally on a machine or to run commands that cannot be executed from within a docker container, you can always install it natively (pm2).
Follow the steps below to install Kaholo Agent on your machine:
Step 1: Install Node.js LTS
For Windows OS, we recommend using Choco. Instructions on Choco can be found on this link: https://chocolatey.org/install.
After installing Choco, run this:
| choco install nodejs-lts |
For any other OS, follow the Node.js instructions using this link: https://nodejs.org/en/download/package-manager/
Step 2: Install pm2 and clone Kaholo-agent
Use the codes below to install pm2 and clone the Kaholo Agent.
| #install pm2 npm i pm2 -g#clone kaholo-agent git clone https://github.com/Kaholo/kaholo-agent#install dependencies cd kaholo-agent && npm install –production |
Step 3: Set Configuration
After doing steps 1 and 2, configure the Kaholo Agent settings. Copy kaholo-agent.conf.example to kaholo-agent.conf. Note that kaholo-agent.conf is the configuration file for the agent and it contains the following options:
| Options | Description |
|---|---|
| PORT | The port which the agent will run.
Note: the default port is 8090, if you use any other port, you will also need to adjust the docker run command. |
| SERVER_URL | The URL of the Kaholo server that you want to connect to. |
| AGENT_KEY | A unique random 64 characters to identify this specific agent. |
| AMQP_HOST | The host of the queue, usually the same as the server. |
| AMQP_PORT | The port of the AMQP server is usually 5671. |
| AMQP_USER | twiddlebugs |
| AMQP_PASSWORD | twiddlebugs |
| AMQP_RESULT_QUEUE | actions-outcome |
| AMQP_CERT_PATH | The path to the agent crt file. |
| AMQP_KEY_PATH | The path to the agent pem file. |
Step 4: Run the Agent
After installing the Kaholo Agent, try a test run to see if it was successfully installed. From the agent directory, run:
| pm2 start app.js –name “kaholo-agent” |
Known Native Installation Issues
The pm2 environment is conservative and when you run a new process, the new environment variables will not be updated into the existing process. This commonly affects native installations on Windows machines.
To resolve the outdated environment variables issue, you need to restart the agent using this command:
| pm2 restart kaholo-agent –update-env |
Note:
Currently, there is a known issue on the agent_key and the port/IP the agent is using for being coupled for agent identification.
This means that you must always use a unique key for each agent, and change the key if you move the agent to any other port/IP. Otherwise, the agent won’t be able to connect correctly and will be marked as a red flag in the system. Rest assured, we are working on a fix for this issue and other agent-related issues to ensure seamless automation.
