Skip to main content
Version: 0.18

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

Steps

  1. Follow steps from CONTRIBUTING.md about running Botkube locally.

  2. 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:
    "plugin-based":
    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:
    "plugin-based":
    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:
    "plugin-based":
    local-repo/echo:
    enabled: true
    config:
    transformResponseToUpperCase: true
    sources:
    "plugin-based":
    local-repo/ticker:
    enabled: true
    config:
    interval: 5s
    communications:
    default-group:
    socketSlack:
    enabled: true
    channels:
    default:
    name: random
    bindings:
    executors:
    - 'plugin-based'
    sources:
    - 'plugin-based'
    appToken: "" # provide your token starting with xapp-1-
    botToken: "" # provide your token starting with xoxb-
    settings:
    clusterName: local-dev
    EOF
  3. 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.

  4. In your plugin project directory open a new terminal window.

  5. Export Botkube plugins cache directory:

    export BOTKUBE_PLUGINS_CACHE__DIR="/tmp/plugins"
  6. Export Botkube repository path cloned in the first step:

    export BOTKUBE_REPO_PATH={botkube_repo_path}
  7. Export configuration files:

    export BOTKUBE_CONFIG_PATHS="${BOTKUBE_REPO_PATH}/helm/botkube/values.yaml,/tmp/config-values.yaml"
  8. Build plugins and start Botkube:

    note

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

  1. Download index builder:
go get github.com/kubeshop/botkube/hack
  1. 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" &&
# remove cached plugins
rm -rf $BOTKUBE_PLUGINS_CACHE__DIR &&
# start Botkube
${BOTKUBE_REPO_PATH}/botkube