2017-04-17 19:30:31 -04:00
= Elasticsearch X-Pack
2015-07-14 06:49:02 -04:00
2017-04-17 19:30:31 -04:00
A set of Elastic's commercial plugins for Elasticsearch:
2015-07-14 06:49:02 -04:00
- License
2016-05-09 08:05:19 -04:00
- Security
2015-07-14 06:49:02 -04:00
- Watcher
2016-05-09 08:05:19 -04:00
- Monitoring
2017-02-20 06:16:56 -05:00
- Machine Learning
2017-04-17 19:30:31 -04:00
- Graph
2015-11-04 14:19:13 -05:00
2015-11-20 15:02:25 -05:00
= Setup
2017-04-17 19:30:31 -04:00
You must checkout `x-pack-elasticsearch` and `elasticsearch` with a specific directory structure. The
`elasticsearch` checkout will be used when building `x-pack-elasticsearch`. The structure is:
2016-12-20 13:43:32 -05:00
- /path/to/elastic/elasticsearch
2017-02-14 17:16:18 -05:00
- /path/to/elastic/elasticsearch-extra/x-pack-elasticsearch
2016-05-09 08:05:19 -04:00
2017-04-17 19:30:31 -04:00
== Vault Secret
The build requires a Vault Secret ID. You can use a GitHub token by following these steps:
1. Go to https://github.com/settings/tokens
2. Click *Generate new token*
3. Set permissions to `read:org`
4. Copy the token into `~/.elastic/github.token`
5. Set the token's file permissions to `600`
```
$ mkdir ~/.elastic
$ vi ~/.elastic/github.token
# Add your_token exactly as it is into the file and save it
$ chmod 600 ~/.elastic/github.token
```
If you do not create the token, then you will see something along the lines of this as the failure when trying to build X-Pack:
```
* What went wrong:
Missing ~/.elastic/github.token file or VAULT_SECRET_ID environment variable, needed to authenticate with vault for secrets
```
=== Offline Mode
When running the build in offline mode (`--offline`), it will not required to have the vault secret setup.
2017-02-20 06:16:56 -05:00
== Native Code
**This is mandatory as tests depend on it**
Machine Learning requires platform specific binaries, build from https://github.com/elastic/machine-learning-cpp via CI servers.
The native artifacts are stored in S3. To retrieve them infra's team Vault service is utilized, which
requires a github token. Please setup a github token as documented:
https://github.com/elastic/infra/blob/master/docs/vault.md#github-auth
The github token has to be put into ~/.elastic/github.token, while the file rights must be set to 0600.
2016-05-09 08:05:19 -04:00
= Build
- Run unit tests:
+
[source, txt]
-----
gradle clean test
-----
- Run all tests:
+
[source, txt]
-----
gradle clean check
-----
- Run integration tests:
+
[source, txt]
-----
gradle clean integTest
-----
2017-04-17 19:30:31 -04:00
- Package X-Pack (without running tests)
2016-05-09 08:05:19 -04:00
+
[source, txt]
-----
gradle clean assemble
-----
2017-04-17 19:30:31 -04:00
- Install X-Pack (without running tests)
2016-05-09 08:05:19 -04:00
+
[source, txt]
-----
gradle clean install
-----
2017-06-13 17:36:35 -04:00
= Building documentation
2017-06-20 14:49:15 -04:00
The source files in this repository can be included in either the X-Pack Reference or the Elasticsearch Reference.
2017-06-13 17:36:35 -04:00
2017-06-20 14:49:15 -04:00
NOTE: In 5.5 and later, the Elasticsearch Reference includes X-Pack-specific content when it is built from this repo.
2017-06-13 17:36:35 -04:00
2017-06-20 14:49:15 -04:00
To build the Elasticsearch Reference on your local machine:
2017-06-13 17:36:35 -04:00
2017-06-20 14:49:15 -04:00
* Use the `index.asciidoc` file in the docs/en directory.
* Specify the location of the `elasticsearch/docs` directory with the `--resource` option when you run `build_docs.pl`.
2017-06-13 17:36:35 -04:00
For example:
2017-06-13 17:55:45 -04:00
[source, txt]
-----
2017-08-28 14:35:42 -04:00
./docs/build_docs.pl --doc elasticsearch-extra/x-pack-elasticsearch/docs/en/index.asciidoc --resource=elasticsearch/docs --chunk 1
2017-06-13 17:55:45 -04:00
-----
2017-06-13 17:36:35 -04:00
2017-06-20 14:49:15 -04:00
For information about building the X-Pack Reference, see the README in the x-pack repo.
2017-08-15 19:47:24 -04:00
To build a release notes page for the pull requests in this repository:
2017-08-15 19:49:52 -04:00
2017-08-21 17:58:56 -04:00
* Use the dev-tools/xes-release-notes.pl script to pull PRs from the x-pack-elasticsearch repo. Alternatively, use the dev-tools/xescpp_release_notes.pl script to pull PRs from both the x-pack-elasticsearch and machine-learning-cpp repos.
2017-08-15 19:47:24 -04:00
* Specify the version label for which you want the release notes.
* Redirect the output to a new local file.
2017-08-15 19:49:52 -04:00
NOTE: You must have a personal access token called ~/.github_auth with "repo" scope. Use steps similar to "Vault Secret" to create this file.
2017-08-15 19:47:24 -04:00
For example:
[source, txt]
-----
./dev-tools/xes_release_notes.pl v5.5.2 > ~/tmp/5.5.2.asciidoc
-----
2017-06-13 17:36:35 -04:00
== Adding Images
When you include an image in the documentation, specify the path relative to the location of the asciidoc file. By convention, we put images in an `images` subdirectory.
For example to insert `watcher-ui-edit-watch.png` in `watcher/limitations.asciidoc`:
2017-06-13 17:55:45 -04:00
. Add an `images` subdirectory to the watcher directory if it doesn't already exist.
. In `limitations.asciidoc` specify:
+
[source, txt]
-----
2017-06-13 17:36:35 -04:00
image::images/watcher-ui-edit-watch.png["Editing a watch"]
2017-06-13 17:55:45 -04:00
-----
2017-06-13 17:36:35 -04:00
Please note that image names and anchor IDs must be unique within the book, so do not use generic identifiers.