ndimiduk commented on a change in pull request #1422: HBASE-24106 Update getting started documentation after HBASE-24086 URL: https://github.com/apache/hbase/pull/1422#discussion_r403146488
########## File path: src/main/asciidoc/_chapters/getting_started.adoc ########## @@ -55,85 +55,67 @@ See <<java,Java>> for information about supported JDK versions. . Choose a download site from this list of link:https://www.apache.org/dyn/closer.lua/hbase/[Apache Download Mirrors]. Click on the suggested top link. This will take you to a mirror of _HBase Releases_. - Click on the folder named _stable_ and then download the binary file that ends in _.tar.gz_ to your local filesystem. - Do not download the file ending in _src.tar.gz_ for now. + Click on the folder named _stable_ and then download the binary file that looks like + _hbase-<version>-bin.tar.gz_. -. Extract the downloaded file, and change to the newly-created directory. +. Extract the downloaded file and change to the newly-created directory. + -[source,subs="attributes"] ---- - -$ tar xzvf hbase-{Version}-bin.tar.gz -$ cd hbase-{Version}/ +$ tar xzvf hbase-<version>-bin.tar.gz +$ cd hbase-<version>/ ---- -. You must set the `JAVA_HOME` environment variable before starting HBase. - To make this easier, HBase lets you set it within the _conf/hbase-env.sh_ file. You must locate where Java is - installed on your machine, and one way to find this is by using the _whereis java_ command. Once you have the location, - edit the _conf/hbase-env.sh_ file and uncomment the line starting with _#export JAVA_HOME=_, and then set it to your Java installation path. +. Set the `JAVA_HOME` environment variable in _conf/hbase-env.sh_. + First, locate the installation of `java` on your machine. On Unix systems, you can use the + _whereis java_ command. Once you have the location, edit _conf/hbase-env.sh_ file, found inside + the extracted _hbase-<version>_ directory, uncomment the line starting with `#export JAVA_HOME=`, + and then set it to your Java installation path. + -.Example extract from _hbase-env.sh_ where _JAVA_HOME_ is set +.Example extract from _conf/hbase-env.sh_ where `JAVA_HOME` is set # Set environment variables here. # The java implementation to use. export JAVA_HOME=/usr/jdk64/jdk1.8.0_112 + -. Edit _conf/hbase-site.xml_, which is the main HBase configuration file. - At this time, you need to specify the directory on the local filesystem where HBase and ZooKeeper write data and acknowledge some risks. - By default, a new directory is created under /tmp. - Many servers are configured to delete the contents of _/tmp_ upon reboot, so you should store the data elsewhere. - The following configuration will store HBase's data in the _hbase_ directory, in the home directory of the user called `testuser`. - Paste the `<property>` tags beneath the `<configuration>` tags, which should be empty in a new HBase install. +. Optionally set the <<hbase.tmp.dir,`hbase.tmp.dir`>> property in _conf/hbase-site.xml_. + At this time, you may consider changing the location on the local filesystem where HBase writes + its application data and the data written by its embedded ZooKeeper instance. By default, HBase + uses paths under <<hbase.tmp.dir,`hbase.tmp.dir`>> for these directories. ++ +NOTE: On most systems, this is a path created under _/tmp_. Many system periodically delete the + contents of _/tmp_. If you start working with HBase in this way, and then return after the + cleanup operation takes place, you're likely to find strange errors. The following + configuration will place HBase's runtime data in a _tmp_ directory found inside the extracted + _hbase-<version>_ directory, where it will be safe from this periodic cleanup. ++ +Open _conf/hbase-site.xml_ and paste the `<property>` tags between the empty `<configuration>` +tags. + .Example _hbase-site.xml_ for Standalone HBase ==== [source,xml] ---- - <configuration> <property> - <name>hbase.rootdir</name> - <value>file:///home/testuser/hbase</value> - </property> - <property> - <name>hbase.zookeeper.property.dataDir</name> - <value>/home/testuser/zookeeper</value> - </property> - <property> - <name>hbase.unsafe.stream.capability.enforce</name> - <value>false</value> - <description> - Controls whether HBase will check for stream capabilities (hflush/hsync). - - Disable this if you intend to run on LocalFileSystem, denoted by a rootdir - with the 'file://' scheme, but be mindful of the NOTE below. - - WARNING: Setting this to false blinds you to potential data loss and - inconsistent system state in the event of process and/or node failures. If - HBase is complaining of an inability to use hsync or hflush it's most - likely not a false positive. - </description> + <name>hbase.tmp.dir</name> + <value>tmp</value> </property> </configuration> ---- ==== + -You do not need to create the HBase data directory. -HBase will do this for you. If you create the directory, -HBase will attempt to do a migration, which is not what you want. +You do not need to create the HBase _tmp_ directory; HBase will do this for you. + -NOTE: The _hbase.rootdir_ in the above example points to a directory -in the _local filesystem_. The 'file://' prefix is how we denote local -filesystem. You should take the WARNING present in the configuration example -to heart. In standalone mode HBase makes use of the local filesystem abstraction -from the Apache Hadoop project. That abstraction doesn't provide the durability -promises that HBase needs to operate safely. This is fine for local development -and testing use cases where the cost of cluster failure is well contained. It is -not appropriate for production deployments; eventually you will lose data. - -To home HBase on an existing instance of HDFS, set the _hbase.rootdir_ to point at a -directory up on your instance: e.g. _hdfs://namenode.example.org:8020/hbase_. -For more on this variant, see the section below on Standalone HBase over HDFS. +NOTE: When unconfigured, HBase uses <<hbase.tmp.dir,`hbase.tmp.dir`>> as a starting point for many +important configurations. Notable among them are <<hbase.rootdir,`hbase.rootdir`>>, the path under +which HBase stores its data. You can specify values for this configuration directly, as you'll see +in the subsequent sections. ++ +NOTE: In this example, HBase is running on Hadoop's `LocalFileSystem`. That abstraction doesn't Review comment: The [book](https://hbase.apache.org/book.html#hadoop) says HBase 2.1 and 2.2 are "untested" with Hadoop 2.10. branch-2.2 builds with `-Dhadoop-two.version=2.10.0` and produces a similar error at runtime: ``` java.lang.IllegalStateException: The procedure WAL relies on the ability to hsync for proper operation during component failures, but the underlying filesystem does not support doing so. Please check th e config value of 'hbase.procedure.store.wal.use.hsync' to set the desired level of robustness and ensure the config value of 'hbase.wal.dir' points to a FileSystem mount that can provide it. at org.apache.hadoop.hbase.procedure2.store.wal.WALProcedureStore.rollWriter(WALProcedureStore.java:1092) at org.apache.hadoop.hbase.procedure2.store.wal.WALProcedureStore.recoverLease(WALProcedureStore.java:424) at org.apache.hadoop.hbase.procedure2.ProcedureExecutor.init(ProcedureExecutor.java:586) at org.apache.hadoop.hbase.master.HMaster.createProcedureExecutor(HMaster.java:1522) at org.apache.hadoop.hbase.master.HMaster.lambda$run$0(HMaster.java:579) at java.lang.Thread.run(Thread.java:748) ``` branch-2.1 does not build with hadoop-2.10.0, ``` [INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (banned-jsr305) @ hbase-client --- [WARNING] Rule 0: org.apache.maven.plugins.enforcer.BannedDependencies failed with message: We don't allow the JSR305 jar from the Findbugs project, see HBASE-16321. Found Banned Dependency: com.google.code.findbugs:jsr305:jar:1.3.9 ``` ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
