forked from elastic/kibana
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improvements to our developer guide (elastic#67764)
* contributing guide -> asciidoc * Update docs/developer/contributing/index.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update CONTRIBUTING.md Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update docs/developer/best-practices/stability.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update docs/developer/contributing/index.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * address code review comments * Update docs/developer/contributing/development-documentation.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * review comment updates * fix bad ref Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> # Conflicts: # CONTRIBUTING.md # docs/developer/contributing/development-functional-tests.asciidoc # docs/developer/contributing/development-unit-tests.asciidoc
- Loading branch information
1 parent
4e7f4c5
commit 4b9a61e
Showing
46 changed files
with
1,630 additions
and
1,273 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| [[development-basepath]] | ||
| === Considerations for basepath | ||
|
|
||
| In dev mode, {kib} by default runs behind a proxy which adds a random path component to its URL. | ||
|
|
||
| You can set this explicitly using `server.basePath` in <<settings>>. | ||
|
|
||
| Use the server.rewriteBasePath setting to tell {kib} if it should remove the basePath from requests it receives, and to prevent a deprecation warning at startup. This setting cannot end in a slash (/). | ||
|
|
||
| If you want to turn off the basepath when in development mode, start {kib} with the `--no-basepath` flag | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn start --no-basepath | ||
| ---- | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| [[advanced]] | ||
| == Advanced | ||
|
|
||
| * <<running-elasticsearch>> | ||
| * <<development-es-snapshots>> | ||
| * <<development-basepath>> | ||
|
|
||
| include::development-es-snapshots.asciidoc[] | ||
|
|
||
| include::running-elasticsearch.asciidoc[] | ||
|
|
||
| include::development-basepath.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| [[running-elasticsearch]] | ||
| === Running elasticsearch during development | ||
|
|
||
| There are many ways to run Elasticsearch while you are developing. | ||
|
|
||
| [float] | ||
|
|
||
| ==== By snapshot | ||
|
|
||
| This will run a snapshot of elasticsearch that is usually built nightly. Read more about <<development-es-snapshots>>. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es snapshot | ||
| ---- | ||
|
|
||
| See all available options, like how to specify a specific license, with the `--help` flag. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es snapshot --help | ||
| ---- | ||
|
|
||
| `trial` will give you access to all capabilities. | ||
|
|
||
| **Keeping data between snapshots** | ||
|
|
||
| If you want to keep the data inside your Elasticsearch between usages of this command, you should use the following command, to keep your data folder outside the downloaded snapshot folder: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es snapshot -E path.data=../data | ||
| ---- | ||
|
|
||
| ==== By source | ||
|
|
||
| If you have the Elasticsearch repo checked out locally and wish to run against that, use `source`. By default, it will reference an elasticsearch checkout which is a sibling to the {kib} directory named elasticsearch. If you wish to use a checkout in another location you can provide that by supplying --source-path | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es source | ||
| ---- | ||
|
|
||
| ==== From an archive | ||
|
|
||
| Use this if you already have a distributable. For released versions, one can be obtained on the Elasticsearch downloads page. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es archive <full_path_to_archive> | ||
| ---- | ||
|
|
||
| Each of these will run Elasticsearch with a basic license. Additional options are available, pass --help for more information. | ||
|
|
||
| ==== From a remote host | ||
|
|
||
| You can save some system resources, and the effort of generating sample data, if you have a remote Elasticsearch cluster to connect to. (Elasticians: you do! Check with your team about where to find credentials) | ||
|
|
||
| You'll need to create a kibana.dev.yml (<<customize-kibana-yml>>) and add the following to it: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| elasticsearch.hosts: | ||
| - {{ url }} | ||
| elasticsearch.username: {{ username }} | ||
| elasticsearch.password: {{ password }} | ||
| elasticsearch.ssl.verificationMode: none | ||
| ---- | ||
|
|
||
| If many other users will be interacting with your remote cluster, you'll want to add the following to avoid causing conflicts: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| kibana.index: '.{YourGitHubHandle}-kibana' | ||
| xpack.task_manager.index: '.{YourGitHubHandle}-task-manager-kibana' | ||
| ---- | ||
|
|
||
| ===== Running remote clusters | ||
|
|
||
| Setup remote clusters for cross cluster search (CCS) and cross cluster replication (CCR). | ||
|
|
||
| Start your primary cluster by running: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es snapshot -E path.data=../data_prod1 | ||
| ---- | ||
|
|
||
| Start your remote cluster by running: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| yarn es snapshot -E transport.port=9500 -E http.port=9201 -E path.data=../data_prod2 | ||
| ---- | ||
|
|
||
| Once both clusters are running, start {kib}. {kib} will connect to the primary cluster. | ||
|
|
||
| Setup the remote cluster in {kib} from either Management -> Elasticsearch -> Remote Clusters UI or by running the following script in Console. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| PUT _cluster/settings | ||
| { | ||
| "persistent": { | ||
| "cluster": { | ||
| "remote": { | ||
| "cluster_one": { | ||
| "seeds": [ | ||
| "localhost:9500" | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ---- | ||
|
|
||
| Follow the cross-cluster search instructions for setting up index patterns to search across clusters (<<management-cross-cluster-search>>). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| [[add-data-tutorials]] | ||
| === Add data tutorials | ||
|
|
||
| `Add Data` in the {kib} Home application contains tutorials for setting up data flows in the Elastic stack. | ||
|
|
||
| Each tutorial contains three sets of instructions: | ||
|
|
||
| * `On Premise.` Set up a data flow when both {kib} and Elasticsearch are running on premise. | ||
| * `On Premise Elastic Cloud.` Set up a data flow when {kib} is running on premise and Elasticsearch is running on Elastic Cloud. | ||
| * `Elastic Cloud.` Set up a data flow when both {kib} and Elasticsearch are running on Elastic Cloud. | ||
|
|
||
| [float] | ||
| ==== Creating a new tutorial | ||
| 1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/plugins/home/server/tutorials[tutorials directory]. | ||
| 2. In the new directory, create a file called `index.ts` that exports a function. | ||
| The function must return a function object that conforms to the `TutorialSchema` interface link:{kib-repo}tree/{branch}/src/plugins/home/server/services/tutorials/lib/tutorial_schema.ts[tutorial schema]. | ||
| 3. Register the tutorial in link:{kib-repo}tree/{branch}/src/plugins/home/server/tutorials/register.ts[register.ts] by adding it to the `builtInTutorials`. | ||
| // TODO update path once assets are migrated | ||
| 4. Add image assets to the link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/tutorial_resources[tutorial_resources directory]. | ||
| 5. Run {kib} locally to preview the tutorial. | ||
| 6. Create a PR and go through the review process to get the changes approved. | ||
|
|
||
| If you are creating a new plugin and the tutorial is only related to that plugin, you can also place the `TutorialSchema` object into your plugin folder. Add `home` to the `requiredPlugins` list in your `kibana.json` file. | ||
| Then register the tutorial object by calling `home.tutorials.registerTutorial(tutorialObject)` in the `setup` lifecycle of your server plugin. | ||
|
|
||
| [float] | ||
| ===== Variables | ||
| String values can contain variables that are substituted when rendered. Variables are specified by `{}`. | ||
| For example: `{config.docs.version}` is rendered as `6.2` when running the tutorial in {kib} 6.2. | ||
|
|
||
| link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/np_ready/components/tutorial/replace_template_strings.js#L23[Provided variables] | ||
|
|
||
| [float] | ||
| ===== Markdown | ||
| String values can contain limited Markdown syntax. | ||
|
|
||
| link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled Markdown grammars] | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| [[kibana-architecture]] | ||
| == Architecture | ||
|
|
||
| [IMPORTANT] | ||
| ============================================== | ||
| {kib} developer services and apis are in a state of constant development. We cannot provide backwards compatibility at this time due to the high rate of change. | ||
| ============================================== | ||
|
|
||
| Our developer services are changing all the time. One of the best ways to discover and learn about them is to read the available | ||
| READMEs from all the plugins inside our {kib-repo}tree/{branch}/src/plugins[open source plugins folder] and our | ||
| {kib-repo}/tree/{branch}/x-pack/plugins[commercial plugins folder]. | ||
|
|
||
| A few services also automatically generate api documentation which can be browsed inside the {kib-repo}tree/{branch}/docs/development[docs/development section of our repo] | ||
|
|
||
| A few notable services are called out below. | ||
|
|
||
| * <<development-security>> | ||
| * <<add-data-tutorials>> | ||
| * <<development-visualize-index>> | ||
|
|
||
| include::add-data-tutorials.asciidoc[] | ||
|
|
||
| include::development-visualize-index.asciidoc[] | ||
|
|
||
| include::security/index.asciidoc[] |
Oops, something went wrong.