You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hop.apache.org by ha...@apache.org on 2022/02/12 18:03:17 UTC
[hop] branch master updated: HOP-3754 hop installation and configuration guide, initial version. refactored variable descriptions to snippets
This is an automated email from the ASF dual-hosted git repository.
hansva pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/master by this push:
new d943bf6 HOP-3754 hop installation and configuration guide, initial version. refactored variable descriptions to snippets
new 4e27d1c Merge pull request #1357 from bamaer/HOP-3754
d943bf6 is described below
commit d943bf63adc80724e7a15f920a6c4177ab07065e
Author: Bart Maertens <ba...@know.bi>
AuthorDate: Sat Feb 12 15:23:31 2022 +0100
HOP-3754 hop installation and configuration guide, initial version. refactored variable descriptions to snippets
---
docs/hop-user-manual/modules/ROOT/nav.adoc | 1 +
.../ROOT/pages/installation-configuration.adoc | 131 +++++++++++++++++++++
.../modules/ROOT/pages/protips/index.adoc | 13 +-
.../pages/snippets/variables/hop-audit-folder.adoc | 19 +++
.../snippets/variables/hop-config-folder.adoc | 19 +++
.../variables/hop-plugin-base-folders.adoc | 18 +++
.../snippets/variables/hop-shared-jdbc-folder.adoc | 18 +++
7 files changed, 211 insertions(+), 8 deletions(-)
diff --git a/docs/hop-user-manual/modules/ROOT/nav.adoc b/docs/hop-user-manual/modules/ROOT/nav.adoc
index 6036db7..c6f69d1 100644
--- a/docs/hop-user-manual/modules/ROOT/nav.adoc
+++ b/docs/hop-user-manual/modules/ROOT/nav.adoc
@@ -24,6 +24,7 @@ under the License.
** xref:getting-started/hop-gui-workflows.adoc[Workflows]
** xref:getting-started/hop-next-steps.adoc[Next Steps]
* xref:concepts.adoc[Concepts]
+* xref:installation-configuration.adoc[Installation and Configuration]
* xref:hop-gui/index.adoc[Hop Gui]
** xref:hop-gui/file-dialog.adoc[File Dialog]
** xref:hop-gui/hop-gui-popup-dialog.adoc[Popup Dialog]
diff --git a/docs/hop-user-manual/modules/ROOT/pages/installation-configuration.adoc b/docs/hop-user-manual/modules/ROOT/pages/installation-configuration.adoc
new file mode 100644
index 0000000..5dbb9c0
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/installation-configuration.adoc
@@ -0,0 +1,131 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+[[RequirementsInstallationConfiguration]]
+:imagesdir: ../assets/images
+:description: The requirements and process to install Apache Hop in any environment are intentionally kept as simple as possible. This pages covers the requirements, basic and advanced installations.
+
+= Apache Hop requirements, installation and configuration
+
+== Overview
+
+The requirements and installation process for Apache Hop are intentionally kept as simple as possible.
+
+This page covers everything you need to know to install and run Apache Hop on your local desktop or server, from the very basics to more advanced configurations.
+
+Hop is designed to be as flexible and lightweight as possible, and is intended to blend in with your architecture, not the other way around. This makes the basic installation process extremely easy, but there's a lot of configuration that can be applied to make Hop behave exactly the way you want it to.
+
+TIP: Take a look at the link:/tech-manual/latest/docker-container.html[Docker] page for instructions to run Hop in containers and Kubernetes environments.
+
+== System Requirements
+
+Hop's limited footprint should allow it to run on any modern physical or virtual machine.
+
+For the default Hop distribution, a minimum of 1 CPU/core and 4GB RAM should do, even though you can tweak Hop to run on machines with even less memory.
+
+Hop Runs on the following operating systems:
+
+* Windows 7 or higher
+* Linux (x86_64, ARM)
+* MacOS
+* any modern browser (Hop Web)
+
+== Java Runtime
+
+The only requirement Hop has on any supported operating system is the Java Runtime environment.
+
+Apache Hop is known to work well on the following widely used Java Runtimes:
+
+* https://www.java.com/[Oracle Java Runtime]
+* https://openjdk.java.net/install/[OpenJDK Java Runtime]
+
+Apache Hop works well with these 64-bit java runtimes for version 8 or higher.
+
+Other Java Runtimes may work but haven't been used and tested as extensively as the Oracle and OpenJDK JREs, so you may be pioneering. Feel free to open a https://hop.apache.org/community/tools/#jira[JIRA ticket] if you run into issues, but please mention your JRE and version.
+
+Run `java -version` if you're not sure which Java version is currently installed on your system. Your output should be similar to the one shown below.
+
+[source,shell]
+----
+openjdk version "1.8.0_312"
+OpenJDK Runtime Environment (build 1.8.0_312-b10)
+OpenJDK 64-Bit Server VM (build 25.312-b10, mixed mode)
+----
+
+Make sure to point the `JAVA_HOME` environment variable for your operating system to your desired JRE installation. Refer to your operating system's documentation for more information on environment variables.
+
+== Basic Installation
+
+The basic installation for Apache Hop couldn't be easier:
+
+* https://hop.apache.org/download/[download]
+* unzip
+* change to your newly unzipped `hop` directory
+* run:
+** `hop-gui.bat` (Windows) or `hop-gui.sh` (Linux, MacOS): run link:/manual/latest/hop-gui/index.html[Hop Gui]
+** `hop-run.bat` (Windows) or `hop-run.sh` (Linux, MacOS): link:/manual/latest/hop-run/index.html[run workflows or pipelines] from the command line.
+** `hop-server.bat` (Windows) or `hop-server.sh` (Linux, MacOS): start a link:/manual/latest/hop-server/index.html[Hop Server] instance.
+
+== Additional configuration
+
+=== JVM memory settings
+
+By default, Hop only sets a maximum for the JVM Heap size Hop can allocate.
+
+This parameter can be changed in the `hop-gui.bat` or `hop-gui.sh` or similar scripts for `hop-run` and `hop-server`.
+
+Identify the following line:
+`HOP_OPTIONS="-Xmx2048m"`
+
+The `-Xmx` parameter determines the maximum amount of memory the JVM can allocate and can be specified in MB or GB.
+
+For example:
+
+* `HOP_OPTIONS=-Xmx512m`: start Hop with maximum *512MB* of memory
+* `HOP_OPTIONS=-Xmx2048m`: start Hop with maximum *2048MB* (or 2GB) of memory
+* `HOP_OPTIONS=-Xmx4g`: start Hop with maximum *4GB* of memory
+
+Check the documentation for your JRE for more information about additional JVM configuration, tuning and garbage collection parameters. https://www.baeldung.com/jvm-parameters[This guide] may help you to get started.
+
+TIP: **Developers**: a couple of lines below the `-Xmx` parameter, you'll find another `HOP_OPTIONS` line that contains `-Xdebug`. Uncomment this line to allow debuggers to attach to your running Hop instance. Check the link:/dev-manual/latest/setup-dev-environment.html[developer documentation] for more information.
+
+=== Hop environment variables
+
+The following (operating system) environment variables can add a lot of flexibility to configure Hop to your exact needs.
+
+include::snippets/variables/hop-audit-folder.adoc[]
+
+include::snippets/variables/hop-config-folder.adoc[]
+
+include::snippets/variables/hop-plugin-base-folders.adoc[]
+
+include::snippets/variables/hop-shared-jdbc-folder.adoc[]
+
+=== JDBC Drivers and other plugin dependencies
+
+Hop comes with built-in support for tens of databases and a large number of other technologies.
+
+Depending on the Apache and technology vendor's licenses, the required libraries may not be available in the default Apache Hop distribution.
+
+Download the necessary drivers or other required libraries and add them to your plugin's `lib` directory.
+
+For example, to add a JDBC driver for the MySQL database, download the MySQL JDBC jar file and add it to `<PATH>/hop/plugins/databases/mysql`.
+
+=== Technology configuration
+
+Hop comes with built-in support for lots of technologies that may require their own (installation and) configuration.
+
+Check the link:/manual/latest/technology/technology.html[technology] page for the platform you need to configure to find out more.
diff --git a/docs/hop-user-manual/modules/ROOT/pages/protips/index.adoc b/docs/hop-user-manual/modules/ROOT/pages/protips/index.adoc
index 9b33106..b7e168b 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/protips/index.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/protips/index.adoc
@@ -26,16 +26,13 @@ A lot of Hop's default behavior can be customized through global variables.
Check xref:variables.adoc[full list of variables] to check them all.
A couple of useful and often overlooked environment variables can be set (outside of Hop):
-HOP_AUDIT_FOLDER::
-Set this variable to a valid path on your machine to store Hop's audit information.
-This information includes last opened files per project, zoom size and lots more.
+include::../snippets/variables/hop-audit-folder.adoc[]
-HOP_CONFIG_FOLDER::
-Hop stores your configuration in the `config` folder by default.
-Set this environment variable to point to a folder outside of your Hop installation to keep your configuration, projects and environment list etc, no matter which Hop version or installation you use.
+include::../snippets/variables/hop-config-folder.adoc[]
-HOP_PLUGIN_BASE_FOLDERS::
-Set this variable to point Hop to a comma separated list of folders where you want Hop to look for additional plugins.
+include::../snippets/variables/hop-plugin-base-folders.adoc[]
+
+include::../snippets/variables/hop-shared-jdbc-folder.adoc[]
== Keyboard Shortcuts and Mouse actions
diff --git a/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-audit-folder.adoc b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-audit-folder.adoc
new file mode 100644
index 0000000..3e5923a
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-audit-folder.adoc
@@ -0,0 +1,19 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+HOP_AUDIT_FOLDER::
+Set this variable to a valid path on your machine to store Hop's audit information.
+This information includes last opened files per project, zoom size and lots more.
diff --git a/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-config-folder.adoc b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-config-folder.adoc
new file mode 100644
index 0000000..e0a27c0
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-config-folder.adoc
@@ -0,0 +1,19 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+HOP_CONFIG_FOLDER::
+Hop stores your configuration in the `config` folder by default.
+Set this environment variable to point to a folder outside of your Hop installation to keep your configuration, projects and environment list etc, no matter which Hop version or installation you use.
diff --git a/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-plugin-base-folders.adoc b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-plugin-base-folders.adoc
new file mode 100644
index 0000000..5d66134
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-plugin-base-folders.adoc
@@ -0,0 +1,18 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+HOP_PLUGIN_BASE_FOLDERS::
+Set this variable to point Hop to a comma separated list of folders where you want Hop to look for additional plugins.
diff --git a/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-shared-jdbc-folder.adoc b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-shared-jdbc-folder.adoc
new file mode 100644
index 0000000..275f5d5
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/snippets/variables/hop-shared-jdbc-folder.adoc
@@ -0,0 +1,18 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+HOP_SHARED_JDBC_FOLDER::
+The variable which points to a shared folder with JDBC drivers in them.
\ No newline at end of file