[incubator-hop] branch master updated: HOP-3303 instructions for manual Hop Web installation

[mc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mcasters pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-hop.git


The following commit(s) were added to refs/heads/master by this push:
     new 9c7385f  HOP-3303 instructions for manual Hop Web installation
     new a5f5dd4  Merge pull request #1210 from bamaer/HOP-3303
9c7385f is described below

commit 9c7385f82ddedfd1a9c37fd210ae74f2ebd701b3
Author: Bart Maertens <ba...@know.bi>
AuthorDate: Thu Dec 2 09:36:25 2021 +0100

    HOP-3303 instructions for manual Hop Web installation
---
 .../modules/ROOT/assets/images/hop-web.png         | Bin 0 -> 273301 bytes
 .../modules/ROOT/pages/hopweb/index.adoc           |  96 ++++++++++++++++++---
 2 files changed, 86 insertions(+), 10 deletions(-)

diff --git a/docs/hop-dev-manual/modules/ROOT/assets/images/hop-web.png b/docs/hop-dev-manual/modules/ROOT/assets/images/hop-web.png
new file mode 100644
index 0000000..79983b1
Binary files /dev/null and b/docs/hop-dev-manual/modules/ROOT/assets/images/hop-web.png differ
diff --git a/docs/hop-dev-manual/modules/ROOT/pages/hopweb/index.adoc b/docs/hop-dev-manual/modules/ROOT/pages/hopweb/index.adoc
index fdc416e..f9b5263 100644
--- a/docs/hop-dev-manual/modules/ROOT/pages/hopweb/index.adoc
+++ b/docs/hop-dev-manual/modules/ROOT/pages/hopweb/index.adoc
@@ -20,28 +20,104 @@ under the License.
 
 == Building or customizing Hop Web
 
-Building and setting up your own Hop Web environment is straightforward.
+Hop Web is available as a Docker container image from Docker Hub. Check the link:/manual/latest/hop-gui/hop-web.html[user manual for Hop Web] for more information.
+
+
+== Build Hop
+
+Hop currently doesn't offer any standalone Hop Web builds.
+
+Running your own Hop Web environment is straightforward but requires you to build Hop. Follow the xref:setup-dev-environment.adoc[development environment setup] guide to get the Hop source code and build Hop.
+
+== Tomcat Configuration
+
+=== Copy files
+
+We'll use Apache Tomcat in this example. If you use another application server, the process should be similar.
+
+Hop 1.x is built with Java 8, so you'll need to https://tomcat.apache.org/download-90.cgi[download the latest Tomcat 9].
 
 The steps to set up the default Docker image are included in a helper script `docker/create_hop_web_container.sh` in the Hop code base.
 This should get you started to make modifications or create your own version entirely.
 
+Copy or extract the following files from your Hop build, where `$CATALINA_HOME` is your Tomcat installation folder.
+
 [source,bash]
 ----
-#set working dir to current location
-cd "${0%/*}"
 
 #unzip files for docker image
-unzip ../assemblies/web/target/hop.war -d ../assemblies/web/target/webapp
-unzip ../assemblies/plugins/dist/target/hop-assemblies-*.zip -d ../assemblies/plugins/dist/target/
+unzip assemblies/web/target/hop.war -d $CATALINA_HOME/webapp
+unzip assemblies/plugins/dist/target/hop-assemblies-*.zip -d $CATALINA_HOME/
+----
 
-#build docker image
-docker build ../ -f Dockerfile.web -t hop-web
+=== Modify startup script
 
-#cleanup
-rm -rf ../assemblies/web/target/webapp
-rm -rf ../assemblies/plugins/dist/target/plugins
+Configure Tomcat to run Hop by adding the information below to  `$CATALINA_HOME/bin/startup.sh`, anywhere before the last line (`exec "$PRGDIR"/"$EXECUTABLE" start "$@"`)
+
+[source,bash]
 ----
 
+HOP_AES_ENCODER_KEY=
+# specify where Hop should store audit information
+HOP_AUDIT_FOLDER="${CATALINA_HOME}/webapps/hop/audit"
+# specify where Hop should manage configuration metadata (e.g. projects and environments information).
+HOP_CONFIG_FOLDER="${CATALINA_HOME}/webapps/hop/config"
+# specify the hop log level
+HOP_LOG_LEVEL="Basic"
+# any additional JRE settings you want to pass on
+#HOP_OPTIONS=
+# default Hop password encoder plugin
+HOP_PASSWORD_ENCODER_PLUGIN="Hop"
+# point Hop to the plugins folder
+HOP_PLUGIN_BASE_FOLDERS="plugins"
+# path to jdbc drivers
+HOP_SHARED_JDBC_FOLDER=
+# the theme to use (dark or light)
+HOP_WEB_THEME="light"
+
+# Set TOMCAT start variables
+export CATALINA_OPTS='${HOP_OPTIONS} -DHOP_AES_ENCODER_KEY="${HOP_AES_ENCODER_KEY}" -DHOP_AUDIT_FOLDER="${HOP_AUDIT_FOLDER}" -DHOP_CONFIG_FOLDER="${HOP_CONFIG_FOLDER}" -DHOP_LOG_LEVEL="${HOP_LOG_LEVEL}" -DHOP_PASSWORD_ENCODER_PLUGIN="${HOP_PASSWORD_ENCODER_PLUGIN}" -DHOP_PLUGIN_BASE_FOLDERS="${HOP_PLUGIN_BASE_FOLDERS}" -DHOP_SHARED_JDBC_FOLDER="${HOP_SHARED_JDBC_FOLDER}" -DHOP_WEB_THEME="${HOP_WEB_THEME}"'
+
+----
+
+If you want to run Hop Web with the `default` and `samples` projects, make sure the project root path in `hop-config.json` is set to `${HOP_CONFIG_FOLDER}.
+
+On Linux or Mac, use the following sed command to fix this in one line:
+
+`sed -i 's/config\/projects/${HOP_CONFIG_FOLDER}\/projects/g' webapps/hop/config/hop-config.json`
+
+On Windows, modify `hop-config.json` to make sure `projectsConf` looks like the one below:
+
+[source, json]
+----
+  "projectsConfig" : {
+    "enabled" : true,
+    "projectMandatory" : true,
+    "defaultProject" : "default",
+    "standardParentProject" : "default",
+    "projectConfigurations" : [ {
+      "projectName" : "default",
+      "projectHome" : "${HOP_CONFIG_FOLDER}/projects/default",
+      "configFilename" : "project-config.json"
+    }, {
+      "projectName" : "samples",
+      "projectHome" : "${HOP_CONFIG_FOLDER}/projects/samples",
+      "configFilename" : "project-config.json"
+    } ]
+  }
+
+----
+
+== Start Tomcat
+
+Run `bin/startup.sh` (Linux/Mac) or `bin/startup.bat` (Windows).
+
+Hop Web should only take a couple of seconds to start.
+
+Access through http://localhost:8080/hop/ui to test.
+
+image:hop-web.png[Hop Web, width="90%"]
+
 == Additional Guides
 
 * xref:hopweb/developer-guide.adoc[Developer Guide]