Version: 1.12

Local testing

This document describes steps for running Botkube core locally together with a local file server for serving your plugins during development phase.

Prerequisite

Node.js, to use npx

Steps

Follow steps from CONTRIBUTING.md about running Botkube locally.

Create a file with your plugins' repository, plugin configuration and bindings for enabled communication platform:

plugins:
  repositories:
    local-repo:
      url: http://localhost:8080/plugins-index.yaml

executors:
  "plugins":
    local-repo/executor-name: # Plugin name syntax: <repo>/<plugin>[@<version>]. If version is not provided, the latest version from repository is used.
      enabled: true
      config: {} # Plugin's specific configuration.
sources:
  "plugins":
    local-repo/source-name: # Plugin name syntax: <repo>/<plugin>[@<version>]. If version is not provided, the latest version from repository is used.
      enabled: true
      config: {} # Plugin's specific configuration.

communications:
  # Enable a given communication platform and define bindings to a given executor and source plugins.

For example, for Slack and example echo and ticker plugins, provide appToken and botToken and run the script:

Create /tmp/config-values.yaml

cat << EOF > /tmp/config-values.yaml
plugins:
  repositories:
    local-repo:
      url: http://localhost:8080/plugins-index.yaml

executors:
  "plugins":
    local-repo/echo:
      enabled: true
      config:
        transformResponseToUpperCase: true
sources:
  "plugins":
    local-repo/ticker:
      enabled: true
      config:
        interval: 5s
communications:
  default-group:
    socketSlack:
      enabled: true
      channels:
        default:
          name: random
          bindings:
            executors:
              - 'plugins'
            sources:
              - 'plugins'
      appToken: "" # provide your token starting with xapp-1-
      botToken: "" # provide your token starting with xoxb-
settings:
  clusterName: local-dev
EOF

In your plugin project directory, start a static plugin server:
```
# Use https://github.com/vercel/serve
npx serve --listen 8080
```
note
If Botkube runs on external Kubernetes cluster, you can use the tunneling software, for example ngrok. It creates an externally addressable URL for a port you open locally on your machine.
In your plugin project directory open a new terminal window.

Export Botkube plugins cache directory:

export BOTKUBE_PLUGINS_CACHE__DIR="/tmp/plugins"

Export Botkube repository path cloned in the first step:
```
export BOTKUBE_REPO_PATH={botkube_repo_path}
```

Export configuration files:

export BOTKUBE_CONFIG_PATHS="${BOTKUBE_REPO_PATH}/helm/botkube/values.yaml,/tmp/config-values.yaml"

Build plugins and start Botkube:

note
Each time you change a plugin source code, re-run the above command.

For scratch projects
For projects created from template repository

Download index builder:

go get github.com/kubeshop/botkube/hack

Build plugins and run Botkube:

# rebuild plugins only for current GOOS and GOARCH
goreleaser build --rm-dist --snapshot --single-target &&
# regenerate index
go run github.com/kubeshop/botkube/hack -binaries-path "./dist" -url-base-path "http://localhost:8080/dist" -use-archive=false &&
# remove cached plugins
rm -rf $BOTKUBE_PLUGINS_CACHE__DIR &&
# start Botkube
${BOTKUBE_REPO_PATH}/botkube

# rebuild plugins only for current GOOS and GOARCH
make build-plugins-single &&
# regenerate index
env PLUGIN_DOWNLOAD_URL_BASE_PATH="http://localhost:8080/dist" make gen-plugin-index &&
# remove cached plugins
rm -rf $BOTKUBE_PLUGINS_CACHE__DIR &&
# start Botkube
${BOTKUBE_REPO_PATH}/botkube