Setting up AppHost Development Environment in Windows
Setup python virtual environment (optional)
This can be useful when working on multiple integrations which are unrelated and require different packages to be installed.
- Install
virtualenv (these steps are specific tovirtualenv but there are numerous other tools out there and they should all serve the same purpose, ie: pyenv)
- Create a location for the virtual environment (these steps create a base directory for all virtual environment but this can be anywhere)
- Create a virtual environment (the below command will create a python3 environment in the directory you pass in place of <name of environment>
virtualenv --python=python3 ~\.python_envs\<name of environment>
- Activate the environment (once activated anything done with Python or installed will be done using the specific environment)
~\.python_envs\<name of environment>\Scripts\activate
Install package to communicate with Resilient
- Install resilient python packages in Python virtual environment. With the environment activated:
pip install resilient-circuits- ... or download packages from here and pip install the
.tar.gz files
pip install resilient-sdk- ... or download packages from here and pip install the
.tar.gz files
That will install the minimum required files to communicate with the Resilient platform.
- (optional) install pytest-resilient-circuits for testing
pip install pytest-resilient-circuits
- (optional) install resilient-lib for a set of methods to help perform common tasks.
pip install resilient-lib
Installing and running Docker
First you will need to get an install file for Docker Desktop from Docker's website
here. After installing you will also need to install the most recent kernel which can be found on Microsoft's website
here. Then you can run docker as an administrator for the first setup.
To run docker from the CommandLine you will also need to add an additional Docker path to your system variables
- Go to the following location in Windows.
- Win + R -> systempropertiesadvanced -> Environment Variables...
- Edit the System variables Path
- Using the New button, add the following location (or the equivalent if you moved the install location).
- C:\Program Files\Docker\Docker\resources
Also whenever you want to use docker you will need to run the EXE as Admin and login. I usually do this from the GUI.
Building/Developing an Integration
The code below is the basic command structure for creating a package in order to start the development of an integration. Not all of what is below will be needed as you only need the items that are part of your integration.
resilient-sdk codegen -p <name_of_package> -m <message_destination> -f <list_of_functions> -w <list_of_workflows> -s "<list_of_scripts>" -r "<list_of_rules>" -a <list_of_artifactTypes> -fd <list_of_fields> -d <list_of_dataTables> -t <list_of_tasks>
Using the package that was created off of the code above, add the python code needed to create your integration. You may also need to change permissions and dockerfile, but IBM KB articles explain when this is needed.
After your python code has been added to the integration package, you will need to finalize the package for testing purposes. The commands below will package, install, and create a docker container to prepare you for testing.
resilient-sdk package -p ./<package_name>/
pip install -e ./<package_name>/
docker build ./<package_name> -t resilient/<package_name>:<version_number>
docker run -v <path_to_app.config>:/etc/rescircuits/app.config resilient/<package_name>:<version_number>
Note: Keep in mind if you have to make any code changes you must rebuild your docker container.
Testing your Package/Container
From here test your package by just installing the .zip file in the dist folder in root package folder (No need to do any configuration or deploying). While your docker is running you can test the rules in Resilient and verify the package is working as wanted.
resilient-sdk codegen -p <package_name> --reload
Publishing to Registry
In order for your container to run in IBM's AppHost, it must be in a tagged and in a registry. The code below will instruct you how to do this for private integrations; however, when publishing to IBM, IBM will do this for you within their registry. With that said, I am assuming you already have a private registry at this point. There are some free ones out there, but if you have questions about setting up GitHub, feel free to ask as that is how I did my testing.
Logging into the Registry with Docker. It will request your password after running the command.
docker login <registry_url> -u <username>
docker tag resilient/<package_name>:<version_number> <registry_path>/ibmresilient/<package_name>:<version_number>
docker push <registry_path>/ibmresilient/<packages_name>:<version_number>
Configuring AppHost to Use Private Registry
Each AppHost uses a Registry. That means that if you are using a Private registry you will either need to have 2 AppHost servers, 1 for the IBM published apps and 1 for the Private registry you are using, or use IBMs script to duplicate their registry onto your registry. The command below will need to be run for either of these options to run off the private registry on the AppHost server itself.
sudo manageAppHost registry --registry <registry_url> --user <username>
------------------------------
Nick Mumaw
------------------------------