Strolch
/
strolch-website
mirror of
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[New] Updated web-app documentation

This commit is contained in:
Robert von Burg 2022-08-17 08:10:50 +02:00
parent 3adbbd6cb4
commit f8c28bf544
2 changed files with 74 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/development/converting-existing.md
View File

@ -3,7 +3,7 @@ title: 'Converting Existing App'
weight: 90 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 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 bit daunting in the beginning. If you are planning on doing this, first create a

92
content/development/web-app.md
View File

@ -4,21 +4,26 @@ weight: 41
--- ---
## Prerequisites ## Prerequisites
To start developing web-based Strolch apps you need the following: 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. * 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 {{% 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 [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 %}} concern, as thanks to the polyfills, it works on all browsers, including Internet Explorer 11. {{% /notice %}}
## Install the web dependencies ## 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 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. 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: Test that NodeJS is working properly:
```shell ```shell
$ npm --version $ npm --version
6.8.0 6.8.0
@ -32,6 +37,7 @@ npm install -g gulp
``` ```
And then check that both bower and gulp work as expected: And then check that both bower and gulp work as expected:
```shell ```shell
$ bower --version $ bower --version
1.8.14 1.8.14
@ -42,7 +48,8 @@ $ gulp --version
## Creating a Strolch Web App ## 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 %}} {{% notice warning %}}
Note: you need to have the Strolch Maven archetypes installed to your local maven repo, otherwise the 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 ## Installing the web dependencies
In the newly generated artifact, change to the `webapp` folder, and then run `npm install`: In the newly generated artifact, change to the `webapp` folder, and then run `npm install`:
```shell ```shell
@ -71,46 +79,92 @@ npm install
This will first install the NodeJS modules, and then call bower to install the bower packages. 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 %}} 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 ```shell
Building the WAR uses the `package` maven goal, but to have the optimized WAR mvn clean package -Prelease -Dstrolch.env=dev.local
use the `release` profile. ```
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 - <my-artifactId>: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 <my app name> in 557ms
```
And now you can open a browser and login: `http://localhost:8080/<my-artifactId>`
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 ```xml
<env id="test" default="true"> <env id="test" default="true">
<root>/absolute/path/to/&lt;my-artifactId&gt;/runtime</root> <root>/absolute/path/to/runtime</root>
<environment>test</environment> <environment>test</environment>
</env> </env>
``` ```
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 ```shell
mvn clean package -Prelease -Dstrolch.env=test 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 ```shell
catalina.sh run catalina.sh run
``` ```
In the console you'll then see something like this: In the console you'll then see something like this:
```log ```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: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: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: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: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 l.s.a.impl.ComponentContainerImpl:307 start - <my-artifactId>: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 c.atexxi.esytest.web.StartupListener:43 contextInitialized - Started <my app name> in 244ms
``` ```
And now you can open a browser and login: `http://localhost:8080/<my-artifactId>` And now you can open a browser and login: `http://remove-server:8080/<my-artifactId>`
The default username and password are `admin` / `admin`. After logging you, you should see the following view: The default username and password are `admin` / `admin`. After logging you, you should see the following view: