Skip to content

Latest commit

 

History

History
125 lines (82 loc) · 7.29 KB

setting_up_a_development_env.mdx

File metadata and controls

125 lines (82 loc) · 7.29 KB
Raw
id slug title description date tags
kibDevTutorialSetupDevEnv
/kibana-dev-docs/getting-started/setup-dev-env
Set up a Development Environment
Learn how to setup a development environment for contributing to the Kibana repository
2024-08-09
kibana
onboarding
dev
architecture
setup
devcontainer

Setting up a development environment is pretty easy.

We do not support Windows native development anymore and in order to develop Kibana on Windows you must use **WSL** which will give you a much better experience. Please check our to know how to setup the environment and then follow the rest of this guide inside **WSL**.

Get the code

Start by forking the Kibana repository on Github so that you have a place to stage pull requests and create branches for development.

Then clone the repository to your machine:

git clone https://github.com/[YOUR_USERNAME]/kibana.git kibana
cd kibana

Install dependencies

Install the version of Node.js listed in the .node-version file. This can be automated with tools such as nvm. As we also include a .nvmrc file you can switch to the correct version when using nvm by running:

nvm use

Then, install the latest version of yarn using:

npm install -g yarn

If you have Yarn installed, make sure you are using 1.22.19 or later. 2.0 and later are unsupported.

. If you are using an unsupported Yarn version, run: +

yarn set version 1.22.19

Finally, bootstrap Kibana and install all of the remaining dependencies:

yarn kbn bootstrap

Node.js native modules could be in use and node-gyp is the tool used to build them. There are tools you need to install per platform and python versions you need to be using. Please follow the node-gyp installation steps for your platform.

Run Elasticsearch

In order to start Kibana you need to run a local version of Elasticsearch. You can startup and initialize the latest Elasticsearch snapshot of the correct version for Kibana by running the following in a new terminal tab/window:

yarn es snapshot

You can pass --license trial to start Elasticsearch with a trial license, or use the Kibana UI to switch the local version to a trial version which includes all features.

Read about more options for Running Elasticsearch during development, like connecting to a remote host, running from source, preserving data inbetween runs, running remote cluster, etc.

Run Kibana

In another terminal tab/window you can start Kibana.

yarn start

Include developer examples by adding an optional --run-examples flag. Read more about the advanced options for Running Kibana. You will find the development server running on (http://localhost:5601) - and you can log in with the elastic:changeme credential pair.

Code away!

You are now ready to start developing. Changes to the source files should be picked up automatically and either cause the server to restart, or be served to the browser on the next page refresh.

Install pre-commit hook (optional)

In case you want to run a couple of checks like linting or check the file casing of the files to commit, we provide a way to install a pre-commit hook. To configure it you just need to run the following:

node scripts/register_git_hook

After the script completes the pre-commit hook will be created within the file .git/hooks/pre-commit. If you choose to not install it, don’t worry, we still run a quick CI check to provide feedback earliest as we can about the same checks.

Using the Kibana Dev Container (optional)

Kibana also supports using a dev container which can integrate with various editors and tools (supported tools). The dev container provides a consistent development environment across different machines and setups which is based on Ubuntu Jammy (22.04). The only prerequisite is having Docker installed locally. VS Code is the recommended editor and will be used for these instructions because it is the most mature, but it is not required.

Setting up the Dev Container

  1. Make a copy of <repo_root>/.devcontainer/.env.template and rename it to <repo_root>/.devcontainer/.env. Edit any values you're interested in.
  2. There are three options for mounting the Kibana repo into the container:
    • Local Filesystem: Clone the repo locally, or use an existing copy, and open it in VS Code. When prompted, select "Reopen in Dev Container". This uses a bind mount, allowing the container to access and modify files directly on your local filesystem. Your git credentials should be automatically mounted in the container as well. Note that Bazel will create symlinks and a cache inside the container file system. So, if switching to working on your local filesystem afterwards, you will need to bootstrap again.
    • Docker Repo Volume: Use the Dev Containers: Clone Repository in Named Container Volume... command from the Command Palette (F1). This clones the repo into a Docker volume, isolating it from your local filesystem. You will need to configure your git credentials manually in this isolated environment.
    • Docker PR Volume: Use the Dev Containers: Clone GitHub Pull Request in Named Container Volume... command from the Command Palette (F1). This is the same as the previous option, but can be useful for testing a PR in insolation of your local filesystem.
  3. VS Code will then build the container, this will take a few minutes the first time, but subsequent builds will utilize Docker caching and be much faster.
  4. Once the container is built and started, it will automatically run yarn kbn bootstrap.
  5. You should see the Kibana repo and your terminal will be inside the container. You can develop as normal now, including running yarn es from inside the container.

Customizing the Dev Container

Installing any extra extensions or making adjustments to the OS environment inside the container will not have an effect on your local OS or VS Code installation. Editing the devcontainer.json or .devcontainer/Dockerfile should be reserved for changes to all dev environments.

FIPS Mode

The dev container is pre-configured to run Kibana in FIPS mode if needed. Simply change the .env file to FIPS=1 and reopen your terminal. There should be a log message in your terminal which indicates FIPS mode enabled.

Troubleshooting

  • Sometimes when rebuilding the container, there will be an error message that it failed. Usually hitting retry will fix this, and is only related to VS Code trying to reconnect to the container too quickly.

Limitations

  • Git worktrees are not supported when using the repo from the Local Filesystem. VSCode issue for tracking, and a possible workaround though it is untested.