From f8c28bf5442f6faa721fdae6546b778414a89b92 Mon Sep 17 00:00:00 2001 From: Robert von Burg Date: Wed, 17 Aug 2022 08:10:50 +0200 Subject: [PATCH] [New] Updated web-app documentation --- content/development/converting-existing.md | 2 +- content/development/web-app.md | 92 +++++++++++++++++----- 2 files changed, 74 insertions(+), 20 deletions(-) diff --git a/content/development/converting-existing.md b/content/development/converting-existing.md index 28bd83d..d677837 100644 --- a/content/development/converting-existing.md +++ b/content/development/converting-existing.md @@ -3,7 +3,7 @@ title: 'Converting Existing App' weight: 90 --- -# Converting an existing application +## Converting an existing application You can convert an existing application to a Strolch agent, but this might be a bit daunting in the beginning. If you are planning on doing this, first create a diff --git a/content/development/web-app.md b/content/development/web-app.md index 12acc6f..cd744d4 100644 --- a/content/development/web-app.md +++ b/content/development/web-app.md @@ -4,21 +4,26 @@ weight: 41 --- ## Prerequisites + To start developing web-based Strolch apps you need the following: -* Apache Tomcat 9.x (10.x isn't supported yet). Just unpack it somewhere, to be used later, when running the application. + +* Apache Tomcat 9.x (10.x isn't supported yet). Just unpack it somewhere, to be used later, when running the + application. * NodeJS v11.x (other versions don't work with [Bower](https://bower.io), the installation is described below. -{{% notice tip %}} Note: Strolch's Web UI is still using -[Polymer 1.x](https://polymer-library.polymer-project.org/1.0/docs/devguide/feature-overview). This isn't a big +{{% notice tip %}} Note: Strolch's Web UI is still using +[Polymer 1.x](https://polymer-library.polymer-project.org/1.0/docs/devguide/feature-overview). This isn't a big concern, as thanks to the polyfills, it works on all browsers, including Internet Explorer 11. {{% /notice %}} ## Install the web dependencies -The Strolch Web App uses [NodeJS v11.x](https://nodejs.org/download/release/v11.15.0/) to build the web dependencies. Please +The Strolch Web App uses [NodeJS v11.x](https://nodejs.org/download/release/v11.15.0/) to build the web dependencies. +Please download the relevant platform's package, unpack it, and add the `bin` directory to your path variable and add a `NODE_HOME` variable pointing to the root directory of the NodeJS folder. Test that NodeJS is working properly: + ```shell $ npm --version 6.8.0 @@ -32,6 +37,7 @@ npm install -g gulp ``` And then check that both bower and gulp work as expected: + ```shell $ bower --version 1.8.14 @@ -42,7 +48,8 @@ $ gulp --version ## Creating a Strolch Web App -The following shows the maven command to create the new maven project using Strolch's webapp maven archetype. Note that you should replace the placeholders in the brackets: +The following shows the maven command to create the new maven project using Strolch's webapp maven archetype. Note that +you should replace the placeholders in the brackets: {{% notice warning %}} Note: you need to have the Strolch Maven archetypes installed to your local maven repo, otherwise the @@ -62,6 +69,7 @@ mvn archetype:generate \ ``` ## Installing the web dependencies + In the newly generated artifact, change to the `webapp` folder, and then run `npm install`: ```shell @@ -71,46 +79,92 @@ npm install This will first install the NodeJS modules, and then call bower to install the bower packages. -{{% notice warning %}} Note: Whenever the bower.json is changed, e.g. updating a version or adding a package, then you should +{{% notice warning %}} Note: Whenever the bower.json is changed, e.g. updating a version or adding a package, then you +should again call `npm install` inside the webapp folder. {{% /notice %}} -### Building the WAR +### Building and running the WAR locally +Once the web dependencies are installed, all components are available to finally build the WAR and run it on a servlet +container. The archetype is pre-configured to run using the `dev-local` Strolch runtime environment configuration. This +can be achieved by compiling using the following command: -### Running the WAR -Building the WAR uses the `package` maven goal, but to have the optimized WAR -use the `release` profile. +```shell +mvn clean package -Prelease -Dstrolch.env=dev.local +``` + +Building the WAR uses the `package` maven goal, but to have the optimized WAR use the `release` profile. The environment +variable `strolch.env=dev.local` configures the WAR to have its runtime point to the absolute path where the sources are +located. + +After the build is complete, the WAR will be located in the `target/` directory. Copy it to Tomcat's `webapps/` +directory and then start tomcat with the +following command: + +```shell +cd tomcat9/bin +./catalina.sh run +``` + +Tomcat should then see the WAR and deploy it. If everything was setup correctly, then you should see the following in +the logs after startup: + +```shell +INFO l.s.a.impl.ComponentContainerImpl:283 start - System: OS: Linux 5.16.15 Arch: amd64 on Java Azul Systems, Inc. 17 CPU Cores: 32 +INFO l.s.a.impl.ComponentContainerImpl:284 start - Memory: Memory available 16.8 GB / Used: 604.0 MB / Free: 540.6 MB +INFO l.s.a.impl.ComponentContainerImpl:285 start - Using locale en with timezone Europe/Zurich +INFO l.s.a.impl.ComponentContainerImpl:288 start - file.encoding: UTF-8 / sun.jnu.encoding UTF-8 +INFO l.s.a.impl.ComponentContainerImpl:307 start - :dev All 12 Strolch Components started. Took 120ms. Strolch is now ready to be used. Have fun =)) +INFO li.strolch.test.web.StartupListener:43 contextInitialized - Started in 557ms +``` + +And now you can open a browser and login: `http://localhost:8080/` + +The default username and password are `admin` / `admin`. After logging in, you should be greeted with the following +screen: +![Strolch Demo App](/assets/images/demo-app.png) + +### Running the WAR on a remote system + +The sources currently are configured for the `dev.local` environment. To use the WAR on a remote system, we need to +configure another environment, and have the path of the runtime updated in the `StrolchBootstrap.xml` file. Open the +file `src/main/resources/StrolchBootstrap.xml` and modify the `root` path in the `test` environment: -To run this WAR, we must configure the path of Strolch's runtime in the `StrolchBootstrap.xml` file, by updating the following block, -setting the absolute path to the `runtime` from the new project: ```xml + - /absolute/path/to/<my-artifactId>/runtime - test + /absolute/path/to/runtime + test ``` -Now we can build the project using the configured environment: +Now you need to copy the existing `runtime` directory to the remote machine at the above location. + +Now we can build the project using the `test` environment: + ```shell mvn clean package -Prelease -Dstrolch.env=test ``` -Now copy the WAR from the `target/` directory to the `webapps/` directory of your Tomcat 9.x installation. Now you can start tomcat using: +Now copy the WAR from the `target/` directory to the `webapps/` directory of your Tomcat 9.x installation. Now you can +start tomcat using: + ```shell catalina.sh run ``` In the console you'll then see something like this: + ```log INFO l.s.a.impl.ComponentContainerImpl:283 start - System: OS: Linux 5.16.15 Arch: amd64 on Java Azul Systems, Inc. 17 CPU Cores: 32 INFO l.s.a.impl.ComponentContainerImpl:284 start - Memory: Memory available 16.8 GB / Used: 604.0 MB / Free: 540.6 MB INFO l.s.a.impl.ComponentContainerImpl:285 start - Using locale en with timezone Europe/Zurich INFO l.s.a.impl.ComponentContainerImpl:288 start - file.encoding: UTF-8 / sun.jnu.encoding UTF-8 -INFO l.s.a.impl.ComponentContainerImpl:307 start - eSyTest:test All 12 Strolch Components started. Took 43ms. Strolch is now ready to be used. Have fun =)) -INFO c.atexxi.esytest.web.StartupListener:43 contextInitialized - Started eSyTest in 244ms +INFO l.s.a.impl.ComponentContainerImpl:307 start - :test All 12 Strolch Components started. Took 43ms. Strolch is now ready to be used. Have fun =)) +INFO c.atexxi.esytest.web.StartupListener:43 contextInitialized - Started in 244ms ``` -And now you can open a browser and login: `http://localhost:8080/` +And now you can open a browser and login: `http://remove-server:8080/` The default username and password are `admin` / `admin`. After logging you, you should see the following view: