Repository: incubator-nifi Updated Branches: refs/heads/develop 6e5469c71 -> d6160a7d0
NIFI-558: Improvements to "Getting Started" instructions for first build. * when we tell folks to go somewhere, give them a link * make sure building of nifi-parent is called out * provide guidance on when to build parent / nar-plugin * include requirements before folks start trying to build * make sure there are shell examples for deployment commands * make sure shell commands work for copy-paste after this version (even if captured responses will have different output later). * include a screenshot of what a correct build + deploy + launch looks like in browser. Signed-off-by: Aldrin Piri <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/incubator-nifi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-nifi/commit/d6160a7d Tree: http://git-wip-us.apache.org/repos/asf/incubator-nifi/tree/d6160a7d Diff: http://git-wip-us.apache.org/repos/asf/incubator-nifi/diff/d6160a7d Branch: refs/heads/develop Commit: d6160a7d07c86aa04905773ab2cea1ba8bfcc70d Parents: 6e5469c Author: Sean Busbey <[email protected]> Authored: Wed Apr 29 19:11:22 2015 -0500 Committer: Aldrin Piri <[email protected]> Committed: Thu Apr 30 12:17:34 2015 -0400 ---------------------------------------------------------------------- README.md | 39 ++++++++++- nifi-nar-maven-plugin/README.md | 18 ++++-- nifi-parent/README.md | 16 +++-- nifi/README.md | 64 ++++++++++++++++--- .../images/nifi_first_launch_screenshot.png | Bin 0 -> 122540 bytes 5 files changed, 114 insertions(+), 23 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/d6160a7d/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 75b79c2..d7a04c4 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,42 @@ Apache NiFi is an easy to use, powerful, and reliable system to process and dist ## Getting Started -- Build the nifi-nar-maven-plugin. Change directory to 'nifi-nar-maven-plugin' and -follow the directions found there. -- Build nifi. Change directory to 'nifi' and follow the directions found there. +- Read through the [quickstart guide for development](http://nifi.incubator.apache.org/development/quickstart.html). + It will include information on getting a local copy of the source, give pointers on issue + tracking, and provide some warnings about common problems with development environments. +- Optional: Build supporting modules. This should only be needed if the current 'nifi' module is in + the process of updating to a new version of either the 'nifi-parent' or 'nifi-nar-maven-plugin' + artifacts. + + If in doubt, just skip to building the main nifi project. If the build fails, come back here and + figure out which optional step you are missing; each entry below will give an example of the + errors you'll receive if that step needs to be followed. The version numbers may change but the + error text should still look very familiar. + - Install the nifi-parent pom. Change directory to 'nifi-parent' and follow the directions found + there in [README.md](nifi-parent/README.md). + + If you don't build the nifi-parent pom and the main nifi code relies on an unreleased version + you'll see an erorr like the following: + + [ERROR] Non-resolvable parent POM: Could not find artifact + org.apache.nifi:nifi-parent:pom:1.0.0-incubating-SNAPSHOT in example.snapshots.repo + (https://repository.example.com/content/repositories/snapshots) and + 'parent.relativePath' points at no local POM @ line 18, column 13 -> [Help 2] + - Build the nifi-nar-maven-plugin. Change directory to 'nifi-nar-maven-plugin' and + follow the directions found there in [README.md](nifi-nar-maven-plugin/README.md). + + If you don't build the nifi-nar-maven-plugin and the main nifi code relies on an unreleased + version you'll see an error like the following: + + [ERROR] Unresolveable build extension: Plugin + org.apache.nifi:nifi-nar-maven-plugin:1.0.1-incubating-SNAPSHOT or one of its + dependencies could not be resolved: Could not find artifact + org.apache.nifi:nifi-nar-maven-plugin:jar:1.0.1-incubating-SNAPSHOT -> [Help 2] +- Build nifi. Change directory to 'nifi' and follow the directions found there in + [README.md](nifi/README.md). +- Run NiFi. The directions found in the [README.md](nifi/README.md) file within the 'nifi' module + will also include how to run an instance of NiFi. For help on how to build your first data flow, + see the [NiFi User Guide](http://nifi.incubator.apache.org/docs/nifi-docs/user-guide.html). ## Documentation http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/d6160a7d/nifi-nar-maven-plugin/README.md ---------------------------------------------------------------------- diff --git a/nifi-nar-maven-plugin/README.md b/nifi-nar-maven-plugin/README.md index 1b554d9..4fd3a27 100644 --- a/nifi-nar-maven-plugin/README.md +++ b/nifi-nar-maven-plugin/README.md @@ -18,16 +18,25 @@ Apache NiFi NAR Maven Plugin helps to build NiFi Archive bundles to support the ## Table of Contents +- [Requirements](#requirements) - [Getting Started](#getting-started) - [Getting Help](#getting-help) -- [Requirements](#requirements) - [License](#license) - [Disclaimer](#disclaimer) +## Requirements +* JDK 1.7 or higher +* Apache Maven 3.0.5 or higher + ## Getting Started -To Build: -- Executed 'mvn clean install' +Building the nifi-nar-maven-plugin module should be rare since it will be released infrequently compared to +the main 'nifi' code tree. + +- Build with `mvn clean install` +- Presuming you need to make use of changes to the nifi-nar-maven-plugin module, you should next + go to the [nifi](../nifi) directory and follow its instructions. + ## Getting Help If you have questions, you can reach out to our mailing list: [email protected] @@ -36,9 +45,6 @@ We're also often available in IRC: #nifi on [irc.freenode.net](http://webchat.freenode.net/?channels=#nifi). -## Requirements -* JDK 1.7 or higher - ## License Except as otherwise noted this software is licensed under the http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/d6160a7d/nifi-parent/README.md ---------------------------------------------------------------------- diff --git a/nifi-parent/README.md b/nifi-parent/README.md index a7dd1ed..d2c10d8 100644 --- a/nifi-parent/README.md +++ b/nifi-parent/README.md @@ -18,16 +18,24 @@ Apache NiFi Parent provides a nice aggregation of shared concerns for all NiFi P ## Table of Contents +- [Requirements](#requirements) - [Getting Started](#getting-started) - [License](#license) - [Disclaimer](#disclaimer) +## Requirements +* JDK 1.7 or higher +* Apache Maven 3.0.5 or higher + ## Getting Started -- Build the nifi-parent module. Then you can go to the 'nifi-nar-maven-plugin' -directory and follow its instructions and finally the 'nifi' directory. Building -the nifi-parent and nifi-nar-maven-plugin should be rarely necessary as these -will be released infrequently by comparison to the 'nifi' tree. +Building the nifi-parent module should be rare since it will be released infrequently compared to +the main 'nifi' code tree. + +- Build the nifi-parent module using `mvn clean install`. +- Presuming you need to make use of changes to the nifi-parent module, you should next + go to the [nifi-nar-maven-plugin](../nifi-nar-maven-plugin) directory and follow its instructions + and finally the [nifi](../nifi) directory. ## Documentation http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/d6160a7d/nifi/README.md ---------------------------------------------------------------------- diff --git a/nifi/README.md b/nifi/README.md index 5545539..e40b997 100644 --- a/nifi/README.md +++ b/nifi/README.md @@ -19,9 +19,9 @@ Apache NiFi is an easy to use, powerful, and reliable system to process and dist ## Table of Contents - [Features](#features) +- [Requirements](#requirements) - [Getting Started](#getting-started) - [Getting Help](#getting-help) -- [Requirements](#requirements) - [License](#license) - [Disclaimer](#disclaimer) - [Export Control] (#export-control) @@ -47,17 +47,64 @@ Apache NiFi was made for dataflow. It supports highly configurable directed grap - SSL, SSH, HTTPS, encrypted content, etc... - Pluggable role-based authentication/authorization +## Requirements +* JDK 1.7 or higher +* Apache Maven 3.0.5 or higher + ## Getting Started To build: -- Execute 'mvn clean install' or for parallel build execute 'mvn -T 2.0C clean install' +- Execute `mvn clean install` or for parallel build execute `mvn -T 2.0C clean install`. On a + modest development laptop that is a couple of years old, the latter build takes a bit under ten + minutes. After a large amount of output you should eventually see a success message. + + laptop:nifi fhampton$ mvn -T 2.0C clean install + [INFO] Scanning for projects... + [INFO] Inspecting build with total of 115 modules... + ...tens of thousands of lines elided... + [INFO] ------------------------------------------------------------------------ + [INFO] BUILD SUCCESS + [INFO] ------------------------------------------------------------------------ + [INFO] Total time: 09:24 min (Wall Clock) + [INFO] Finished at: 2015-04-30T00:30:36-05:00 + [INFO] Final Memory: 173M/1359M + [INFO] ------------------------------------------------------------------------ + +To deploy: - Change directory to 'nifi-assembly'. In the target directory, there should be a build of nifi. -- Unpack the build wherever you like or use the already unpacked build. -To start NiFi: -- Change directory to the location where you installed NiFi -- '<install_location>/bin/nifi.sh start' -- Direct your browser to http://localhost:8080/nifi/ + laptop:nifi fhampton$ cd nifi-assembly + laptop:nifi-assembly fhampton$ ls -lhd target/nifi* + drwxr-xr-x 3 fhampton staff 102B Apr 30 00:29 target/nifi-0.1.0-incubating-SNAPSHOT-bin + -rw-r--r-- 1 fhampton staff 144M Apr 30 00:30 target/nifi-0.1.0-incubating-SNAPSHOT-bin.tar.gz + -rw-r--r-- 1 fhampton staff 144M Apr 30 00:30 target/nifi-0.1.0-incubating-SNAPSHOT-bin.zip + +- For testing ongoing development you could use the already unpacked build present in the directory + named "nifi-*version*-bin", where *version* is the current project version. To deploy in another + location make use of either the tarball or zipfile and unpack them wherever you like. The + distribution will be within a common parent directory named for the version. + + laptop:nifi-assembly fhampton$ mkdir ~/example-nifi-deploy + laptop:nifi-assembly fhampton$ tar xzf target/nifi-*-bin.tar.gz -C ~/example-nifi-deploy + laptop:nifi-assembly fhampton$ ls -lh ~/example-nifi-deploy/ + total 0 + drwxr-xr-x 10 fhampton staff 340B Apr 30 01:06 nifi-0.1.0-incubating-SNAPSHOT + +To run NiFi: +- Change directory to the location where you installed NiFi and run it. + + laptop:~ fhampton$ cd ~/example-nifi-deploy/nifi-* + laptop:nifi-0.1.0-incubating-SNAPSHOT fhampton$ ./bin/nifi.sh start + +- Direct your browser to http://localhost:8080/nifi/ and you should see an screen like this screenshot: +  + +- For help building your first data flow see the [NiFi User Guide](http://nifi.incubator.apache.org/docs/nifi-docs/user-guide.html) + +- If you are testing ongoing development, you will likely want to stop your instance. + + laptop:~ fhampton$ cd ~/example-nifi-deploy/nifi-* + laptop:nifi-0.1.0-incubating-SNAPSHOT fhampton$ ./bin/nifi.sh stop ## Getting Help If you have questions, you can reach out to our mailing list: [email protected] @@ -65,9 +112,6 @@ If you have questions, you can reach out to our mailing list: [email protected] We're also often available in IRC: #nifi on [irc.freenode.net](http://webchat.freenode.net/?channels=#nifi). -## Requirements -* JDK 1.7 or higher - ## License Except as otherwise noted this software is licensed under the http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/d6160a7d/nifi/nifi-docs/src/main/asciidoc/images/nifi_first_launch_screenshot.png ---------------------------------------------------------------------- diff --git a/nifi/nifi-docs/src/main/asciidoc/images/nifi_first_launch_screenshot.png b/nifi/nifi-docs/src/main/asciidoc/images/nifi_first_launch_screenshot.png new file mode 100644 index 0000000..7735f7e Binary files /dev/null and b/nifi/nifi-docs/src/main/asciidoc/images/nifi_first_launch_screenshot.png differ
