kibana/docs/developer/getting-started/index.asciidoc

[[development-getting-started]]
== Getting started

Get started building your own plugins, or contributing directly to the {kib} repo.

[discrete]
[[developing-on-windows]]
=== Developing on Windows

We do not support Windows native development anymore and in order to develop Kibana on Windows please https://docs.microsoft.com/en-us/windows/wsl/setup/environment[setup a WSL environment] which will 
give you a much better experience.
In addition to that you will also benefit from https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps[run GUI apps on WSL] like Chrome for test and debug purposes.
Once completed, follow the rest of this guide inside the WSL.

[discrete]
[[get-kibana-code]]
=== Get the code

https://help.github.com/en/github/getting-started-with-github/fork-a-repo[Fork], then https://help.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork[clone] the {kib-repo}[{kib} repo] and change directory into it:

[source,bash]
----
git clone https://github.com/[YOUR_USERNAME]/kibana.git kibana
cd kibana
----

[discrete]
=== Install dependencies

Install the version of Node.js listed in the `.node-version` file. This
can be automated with tools such as
https://github.com/nvm-sh/nvm[nvm] or
https://github.com/wbyoung/avn[avn]. As we also include a `.nvmrc` file
you can switch to the correct version when using nvm by running:

[source,bash]
----
nvm use
----

Install the latest version of https://classic.yarnpkg.com/en/docs/install[yarn v1].

Bootstrap {kib} and install all the dependencies:

[source,bash]
----
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 see
https://github.com/nodejs/node-gyp#installation[https://github.com/nodejs/node-gyp#installation]
and follow the guide according your platform.
____

In case you don't have an internet connection, the `yarn kbn bootstrap` command will 
fail. As it is likely you have the required node_modules in the 
offline mirror, you can try to run the step in offline mode by using:

[source,bash]
----
yarn kbn bootstrap --offline
----

In any other circumstance where you want to force the node_modules install step 
you can use:

[source,bash]
----
yarn kbn bootstrap --force-install
----

You can also run `yarn kbn` to see the other available commands.

When switching branches which use different versions of npm packages you
may need to run:

[source,bash]
----
yarn kbn clean
----

NOTE: Running this command is only necessary in rare circumstance where you need to recover
a consistent state when problems arise. If you need to run this command often, complete
this form to provide feedback: https://ela.st/yarn-kbn-clean

If you have failures during `yarn kbn bootstrap` you may have some
corrupted packages in your yarn cache which you can clean with:

[source,bash]
----
yarn cache clean
----

[discrete]
=== Configure environmental settings

[[increase-nodejs-heap-size]]
[discrete]
==== Increase node.js heap size

{kib} is a big project and for some commands it can happen that the
process hits the default heap limit and crashes with an out-of-memory
error. If you run into this problem, you can increase maximum heap size
by setting the `--max_old_space_size` option on the command line. To set
the limit for all commands, simply add the following line to your shell
config: `export NODE_OPTIONS="--max_old_space_size=2048"`.

[discrete]
=== Run {es}

Run the latest {es} snapshot. Specify an optional license with the `--license` flag.

[source,bash]
----
yarn es snapshot --license trial
----

`trial` will give you access to all capabilities.

Read about more options for <<running-elasticsearch>>, like connecting to a remote host, running from source,
preserving data inbetween runs, running remote cluster, etc.

[discrete]
=== Run {kib}

In another terminal window, start up {kib}. Include {kib-repo}tree/{branch}/examples[developer examples] by adding an optional `--run-examples` flag.

[source,bash]
----
yarn start --run-examples
----

View all available options by running `yarn start --help`

Read about more advanced options for <<running-kibana-advanced>>.

[discrete]
=== 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:

[source,bash]
----
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. 

[discrete]
=== Code away!

You are now ready to start developing. Changes to your files should be picked up automatically. Server side changes will
cause the {kib} server to reboot.

[discrete]
=== More information

* <<running-kibana-advanced>>

* <<sample-data>>

* <<kibana-debugging>>

* <<building-kibana>>

* <<development-plugin-resources>>

include::running-kibana-advanced.asciidoc[leveloffset=+1]

include::sample-data.asciidoc[leveloffset=+1]

include::debugging.asciidoc[leveloffset=+1]

include::building-kibana.asciidoc[leveloffset=+1]

include::development-plugin-resources.asciidoc[leveloffset=+1]

include::monorepo-packages.asciidoc[leveloffset=+1]