​
Docker-compose dev images

You can use docker-compose.dev.yaml to start Keep in a development mode.

First, clone the Keep repo:

git clone https://github.com/keephq/keep.git && cd keep

Next, run

docker compose -f docker-compose.dev.yml up

​
Install Keep CLI

First, clone Keep repository:

git clone https://github.com/keephq/keep.git && cd keep

Install Keep CLI

poetry install

To access the Keep CLI activate the environment, and access from shell.

poetry shell

From now on, Keep should be installed locally and accessible from your CLI, test it by executing:

keep version

​
Enable Auto Completion

Keep’s CLI supports shell auto-completion, which can make your life a whole lot easier 😌

If you’re using zsh

title=~/.zshrc
eval "$(_KEEP_COMPLETE=zsh_source keep)"

If you’re using bash

title=~/.bashrc
eval "$(_KEEP_COMPLETE=bash_source keep)"

Using eval means that the command is invoked and evaluated every time a shell is started, which can delay shell responsiveness. To speed it up, write the generated script to a file, then source that.

​
Testing

Run unittests:

poetry run coverage run --branch -m pytest --ignore=tests/e2e_tests/

Run E2E tests (run Keep locally before):

poetry run playwright install;
poetry run coverage run --branch -m pytest -s tests/e2e_tests/

​
Migrations

Migrations are automatically executed on a server startup. To create a migration:

alembic -c keep/alembic.ini revision --autogenerate -m "Your message"

Hint: make sure your models are imported at ./api/models/db/migrations/env.py for autogenerator to pick them up.

​
VS Code (or Cursor)

Run Keep from your VS Code (or Cursor) after cloning the repo by adding this configurations to your .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Keep Backend",
        "type": "debugpy",
        "request": "launch",
        "program": "keep/cli/cli.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "args": ["--json", "api","--multi-tenant"],
        "env": {
            "PYDEVD_DISABLE_FILE_VALIDATION": "1",
            "PYTHONPATH": "${workspaceFolder}/",
            "PUSHER_APP_ID": "1",
            "SECRET_MANAGER_DIRECTORY": "./state/",
            "PUSHER_HOST": "localhost",
            "PUSHER_PORT": "6001",
            "PUSHER_APP_KEY": "keepappkey",
            "PUSHER_APP_SECRET": "keepappsecret",
            "LOG_FORMAT": "dev_terminal",
        }
      },
      {
        "name": "Keep Simulate Alerts",
        "type": "debugpy",
        "request": "launch",
        "program": "scripts/simulate_alerts.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "env": {
          "PYDEVD_DISABLE_FILE_VALIDATION": "1",
          "PYTHONPATH": "${workspaceFolder}/",
          "KEEP_API_URL": "http://localhost:8080",
          "KEEP_API_KEY": "some-api-key"
        }
      },
      {
        "name": "Keep Frontend",
        "type": "node-terminal",
        "request": "launch",
        "command": "npm run dev",
        "cwd": "${workspaceFolder}/keep-ui",
      }
    ]
}

Install dependencies:

python3.11 -m venv venv;
source venv/bin/activate;
pip install poetry;
poetry install;
cd keep-ui && npm i && cd ..;

Set frontend envs:

cp keep-ui/.env.local.example keep-ui/.env.local;
echo "\n\n\n\nNEXTAUTH_SECRET="$(openssl rand -hex 32) >> keep-ui/.env.local;

Launch Pusher (soketi) container in parallel:

docker run -d -p 6001:6001 -p 9601:9601 -e SOKETI_USER_AUTHENTICATION_TIMEOUT=3000 -e SOKETI_DEFAULT_APP_KEY=keepappkey -e SOKETI_DEFAULT_APP_SECRET=keepappsecret -e SOKETI_DEFAULT_APP_ID=1 quay.io/soketi/soketi:1.4-16-debian

​
VS Code (or Cursor) + Docker

For this guide to work, the VS Code Docker extension is required.
In air-gapped environments, you might consider building the container on an internet-connected computer, exporting the image using docker save, transferring it with docker load in the air-gapped environment, and then using the run configuration.

In cases where you want to develop Keep but are unable to run it directly on your local laptop (e.g., with Windows), or if you lack access to all of its dependencies (e.g., in air-gapped environments), you can still accomplish this using VS Code (or Cursor) and Docker.

To achieve this, follow these steps:

  1. Clone Keep and open it with VS Code (or Cursor)
  2. Create a tasks.json file to build and run the Keep API and Keep UI containers.
  3. Create a launch.json configuration to start the containers and attach a debugger to them.
  4. Profit.

​
Clone Keep and open it with VS Code (or Cursor)

git clone https://github.com/keephq/keep.git && cd keep
code .

​
Create tasks.json

​
including building the containers

{
    "version": "2.0.0",
    "tasks": [
        // The API and UI containers needs to be in the same docker network
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        // Build the api container
        {
            "label": "docker-build-api-dev",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.api",
                "tag": "keep-api-dev:latest"
            }
        },
        // Run the api container
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-build-api-dev", "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        // Build the UI container
        {
            "label": "docker-build-ui",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.ui",
                "tag": "keep-ui-dev:latest"
            }
        },
        // Run the UI container
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-build-ui", "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // Uncomment for fully debug
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB",
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}

​
without building the containers

To start Keep without building the containers, you’ll need to have keep-api-dev and keep-ui-dev images loaded into your docker.
{
    "version": "2.0.0",
    "tasks": [
        # The API and the UI needs to be in the same docker network
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        # Run the API container
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        # Run the UI container
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // Uncomment for fully debug
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}

​
Create launch.json

{
        "name": "Docker: Keep API",
        "type": "docker",
        "request": "launch",
        "preLaunchTask": "docker-run-api-dev",
        "removeContainerAfterDebug": true,
        "containerName": "keep-api",
        "python": {
          "pathMappings": [
            {
              "localRoot": "${workspaceFolder}",
              "remoteRoot": "/app"
            }
          ],
          "module": "keep.cli.cli"
        }
      },
      {
        "name": "Docker: Keep UI",
        "type": "docker",
        "request": "launch",
        "removeContainerAfterDebug": true,
        "preLaunchTask": "docker-run-ui",
        "containerName": "keep-api",
        "platform": "node",
        "node": {
          "package": "${workspaceFolder}/keep-ui/package.json",
          "localRoot": "${workspaceFolder}/keep-ui"
        }
      },