[Major] Updated website for easier dev starting
This commit is contained in:
parent
74eb2b7a71
commit
a26534b99a
|
|
@ -3,211 +3,4 @@ title: 'Development'
|
|||
weight: 90
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
To start developing Strolch you need an installed:
|
||||
* Java JDK 17
|
||||
* Apache Maven 3.x
|
||||
|
||||
You can install these using the awesome [SDKMAN!](https://sdkman.io/):
|
||||
```shell
|
||||
$ curl -s "https://get.sdkman.io" | bash
|
||||
source "$HOME/.sdkman/bin/sdkman-init.sh"
|
||||
sdk version
|
||||
|
||||
sdk install java
|
||||
sdk install maven
|
||||
sdk install mvnd
|
||||
```
|
||||
|
||||
Test your Java installation:
|
||||
```shell
|
||||
$ java -version
|
||||
openjdk version "17.0.4" 2022-07-19
|
||||
OpenJDK Runtime Environment Temurin-17.0.4+8 (build 17.0.4+8)
|
||||
OpenJDK 64-Bit Server VM Temurin-17.0.4+8 (build 17.0.4+8, mixed mode, sharing)
|
||||
```
|
||||
|
||||
Test your Maven installation:
|
||||
```shell
|
||||
$ mvn --version
|
||||
Apache Maven 3.8.6 (84538c9988a25aec085021c365c560670ad80f63)
|
||||
Maven home: /home/user/.sdkman/candidates/maven/current
|
||||
Java version: 17.0.4, vendor: Eclipse Adoptium, runtime: /home/user/.sdkman/candidates/java/17.0.4-tem
|
||||
Default locale: en_US, platform encoding: UTF-8
|
||||
OS name: "linux", version: "5.18.11-051811-generic", arch: "amd64", family: "unix"
|
||||
```
|
||||
|
||||
## Building Strolch
|
||||
|
||||
{{% notice tip %}} Note: You don't have to build Strolch if you want to use the
|
||||
version on Maven central, but if you need a snapshot version, or the release you
|
||||
want isn't on central, then go ahead and build Strolch. {{% /notice %}}
|
||||
|
||||
Building Strolch is just a few lines:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/strolch-li/strolch.git
|
||||
cd strolch
|
||||
mvn clean install -DskipTests
|
||||
```
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: To run the tests you will need to configure the PostgreSQL Databases. See
|
||||
the README in the module.
|
||||
{{% /notice %}}
|
||||
|
||||
After running the Maven build, you will have a full build of all Strolch
|
||||
projects. Now you can start modifying the projects, and add your own features,
|
||||
or, far more interesting, start developing your projects using the Strolch
|
||||
agent.
|
||||
|
||||
## Creating a Strolch App
|
||||
|
||||
To create your own Strolch App, you can use Maven's archetype generation. There
|
||||
are two versions, one is a simple Java App which you can use to directly access
|
||||
the Strolch runtime, and the second is to create a Java Web App, which is the
|
||||
usual way to run Strolch runtimes.
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: you need to have installed Strolch to your local maven repo, otherwise the
|
||||
archetype won't be available.
|
||||
{{% /notice %}}
|
||||
|
||||
### Creating a Java Strolch Web App
|
||||
|
||||
The following shows the maven command to create the new maven project. Note that you should replace the placeholders in the brackets:
|
||||
|
||||
{{% notice tip %}}
|
||||
The code is also available on [GitHub](https://github.com/strolch-li/strolch/tree/develop/li.strolch.mvn.archetype.webapp).
|
||||
{{% /notice %}}
|
||||
|
||||
```shell
|
||||
mvn archetype:generate \
|
||||
-DarchetypeGroupId=li.strolch \
|
||||
-DarchetypeArtifactId=li.strolch.mvn.archetype.webapp \
|
||||
-DarchetypeVersion=1.8.0-SNAPSHOT \
|
||||
-DgroupId=<my.groupid> \
|
||||
-DartifactId=<my-artifactId> \
|
||||
-Dversion=<my.version> \
|
||||
-Dpackage=<my.package> \
|
||||
-DappName="<my app name>"
|
||||
```
|
||||
|
||||
#### 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
|
||||
download the relevant platform's package, unpack it, and add the `bin` directory
|
||||
to your path variable.
|
||||
|
||||
Once NodeJS is installed, then you can prepare the web dependencies:
|
||||
|
||||
```shell
|
||||
cd src/main/webapp/
|
||||
npm install bower -g
|
||||
npm install gulp -g
|
||||
npm install
|
||||
gulp
|
||||
cd ../../..
|
||||
```
|
||||
|
||||
{{% notice warning %}} Note: Whenever the bower.json is changed then you should
|
||||
again call npm install inside the webapp folder. {{% /notice %}}
|
||||
|
||||
#### Building and running the WAR
|
||||
Building the WAR uses the `package` maven goal, but to have the optimized WAR
|
||||
use the `release` profile.
|
||||
|
||||
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
|
||||
<env id="test" default="true">
|
||||
<root>/absolute/path/to/<my-artifactId>/runtime</root>
|
||||
<environment>test</environment>
|
||||
</env>
|
||||
```
|
||||
|
||||
Now we can build the project using the configured 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:
|
||||
```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
|
||||
```
|
||||
|
||||
And now you can open a browser and login: `http://localhost:8080/<my-artifactId>`
|
||||
|
||||
The default username and password are `admin` / `admin`. After logging you, you should see the following view:
|
||||
|
||||
|
||||
|
||||
Happy coding =))
|
||||
|
||||
### Creating a simple Java Strolch App
|
||||
|
||||
The following shows the maven command to create the new maven project. Note that
|
||||
you should replace the placeholders in the brackets:
|
||||
|
||||
{{% notice tip %}}
|
||||
The code is also available on [GitHub](https://github.com/strolch-li/strolch/tree/develop/li.strolch.mvn.archetype.main).
|
||||
{{% /notice %}}
|
||||
|
||||
```shell
|
||||
mvn archetype:generate \
|
||||
-DarchetypeGroupId=li.strolch \
|
||||
-DarchetypeArtifactId=li.strolch.mvn.archetype.main \
|
||||
-DarchetypeVersion=1.8.0-SNAPSHOT \
|
||||
-DgroupId=<my.groupid> \
|
||||
-DartifactId=<my-artifactId> \
|
||||
-Dversion=<my.version> \
|
||||
-DappName="<my app name>"
|
||||
```
|
||||
|
||||
You change into the directory of the new project and then build the project by calling:
|
||||
|
||||
```shell
|
||||
cd <my-artifactId>
|
||||
mvn clean package
|
||||
```
|
||||
|
||||
Start the program using:
|
||||
|
||||
```shell
|
||||
mvn exec:java
|
||||
```
|
||||
|
||||
Happy coding =))
|
||||
|
||||
## 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
|
||||
test application using the maven archetypes, so that you can get a feel for the configuration.
|
||||
|
||||
Once that works, use the archetypes configuration to reconfigure your project to start as a Strolch agent.
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: Beware to select the archetype pertaining to your use case:
|
||||
* For a web app use the [li.strolch.mvn.archetype.webapp](/development/#creating-a-java-strolch-web-app)
|
||||
* For a application with a main method use [li.strolch.mvn.archetype.main](/development/#creating-a-simple-java-strolch-app)
|
||||
{{% /notice %}}
|
||||
|
||||
## Tools used
|
||||
|
||||
The following tools are used to develop Strolch and Strolch-based projects:
|
||||
|
||||
* [IntelliJ](https://www.jetbrains.com/idea/download/#section=linux)
|
||||
* [Apache Maven](https://maven.apache.org/)
|
||||
* [Git SCM](http://git-scm.com/)
|
||||
|
||||
{{% children %}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
title: 'Building Strolch'
|
||||
weight: 20
|
||||
---
|
||||
|
||||
## Building Strolch
|
||||
{{% notice tip %}} Note: You don't have to build Strolch if you want to use the
|
||||
version on Maven central. If you need a snapshot version, the release you
|
||||
want isn't on Maven central or you want to use the Strolch Maven archetypes, then go ahead and build Strolch. {{% /notice %}}
|
||||
|
||||
Building Strolch is just a few lines:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/strolch-li/strolch.git
|
||||
cd strolch
|
||||
mvn clean install -DskipTests
|
||||
```
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: To run the tests you will need to configure the PostgreSQL Databases. See
|
||||
the README in the module.
|
||||
{{% /notice %}}
|
||||
|
||||
After running the Maven build, you will have a full build of all Strolch
|
||||
modules. Now you can start modifying the modules, and add your own features,
|
||||
or, far more interesting, start developing your projects using the Strolch
|
||||
agent.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: 'Converting Existing App'
|
||||
weight: 90
|
||||
---
|
||||
|
||||
# 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
|
||||
test application using the maven archetypes, so that you can get a feel for the configuration.
|
||||
|
||||
Once that works, use the archetypes configuration to reconfigure your project to start as a Strolch agent.
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: Beware to select the archetype pertaining to your use case:
|
||||
* For a web app use the [li.strolch.mvn.archetype.webapp](/development/web-app)
|
||||
* For an application with a main method use [li.strolch.mvn.archetype.main](/development/main-class-app)
|
||||
{{% /notice %}}
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: 'Main Class App'
|
||||
weight: 50
|
||||
---
|
||||
|
||||
## Creating a Strolch App
|
||||
|
||||
The following shows the maven command to create the new maven project using Strolch's main 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
|
||||
following command will fail.
|
||||
{{% /notice %}}
|
||||
|
||||
```shell
|
||||
mvn archetype:generate \
|
||||
-DarchetypeGroupId=li.strolch \
|
||||
-DarchetypeArtifactId=li.strolch.mvn.archetype.main \
|
||||
-DarchetypeVersion=0.1.0-SNAPSHOT \
|
||||
-DgroupId=<my.groupid> \
|
||||
-DartifactId=<my-artifactId> \
|
||||
-Dversion=<my.version> \
|
||||
-DappName="<my app name>"
|
||||
```
|
||||
|
||||
You change into the directory of the new project and then build the project by calling:
|
||||
|
||||
```shell
|
||||
cd <my-artifactId>
|
||||
mvn clean package
|
||||
```
|
||||
|
||||
Start the program using:
|
||||
|
||||
```shell
|
||||
mvn exec:java
|
||||
```
|
||||
|
||||
Happy coding =))
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: 'Maven Archetypes'
|
||||
weight: 40
|
||||
---
|
||||
|
||||
## Maven Archetypes
|
||||
|
||||
Maven offers archetypes to generate new projects. Strolch offers the following archetypes, to create new projects:
|
||||
* [li.strolch.mvn.archetype.main](/development/main-class-app) for Java main class applications
|
||||
* [li.strolch.mvn.archetype.webapp](/development/web-app) for Java Web based applications using REST and Polymer 1.x as the frontend.
|
||||
|
||||
To use the archetypes, clone the archetypes repository and install it locally:
|
||||
|
||||
```shell
|
||||
git clone git@github.com:strolch-li/strolch-maven-archetypes.git
|
||||
cd strolch-maven-archetypes
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
Then follow one of the next steps to create the type of application you want.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: 'Prerequisites'
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
To start developing Strolch you need an installed:
|
||||
* Java JDK 17
|
||||
* Apache Maven 3.x
|
||||
|
||||
You can install these using the awesome [SDKMAN!](https://sdkman.io/):
|
||||
```shell
|
||||
$ curl -s "https://get.sdkman.io" | bash
|
||||
source "$HOME/.sdkman/bin/sdkman-init.sh"
|
||||
sdk version
|
||||
|
||||
sdk install java
|
||||
sdk install maven
|
||||
sdk install mvnd
|
||||
```
|
||||
|
||||
Test your Java installation:
|
||||
```shell
|
||||
$ java -version
|
||||
openjdk version "17.0.4" 2022-07-19
|
||||
OpenJDK Runtime Environment Temurin-17.0.4+8 (build 17.0.4+8)
|
||||
OpenJDK 64-Bit Server VM Temurin-17.0.4+8 (build 17.0.4+8, mixed mode, sharing)
|
||||
```
|
||||
|
||||
Test your Maven installation:
|
||||
```shell
|
||||
$ mvn --version
|
||||
Apache Maven 3.8.6 (84538c9988a25aec085021c365c560670ad80f63)
|
||||
Maven home: /home/user/.sdkman/candidates/maven/current
|
||||
Java version: 17.0.4, vendor: Eclipse Adoptium, runtime: /home/user/.sdkman/candidates/java/17.0.4-tem
|
||||
Default locale: en_US, platform encoding: UTF-8
|
||||
OS name: "linux", version: "5.18.11-051811-generic", arch: "amd64", family: "unix"
|
||||
```
|
||||
|
|
@ -0,0 +1,119 @@
|
|||
---
|
||||
title: 'Web App'
|
||||
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.
|
||||
* 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
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
Once NodeJS is installed, then you can prepare the web dependencies:
|
||||
|
||||
```shell
|
||||
npm install -g bower
|
||||
npm install -g gulp
|
||||
```
|
||||
|
||||
And then check that both bower and gulp work as expected:
|
||||
```shell
|
||||
$ bower --version
|
||||
1.8.14
|
||||
|
||||
$ gulp --version
|
||||
[17:22:56] CLI version 2.0.1
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
{{% notice warning %}}
|
||||
Note: you need to have the Strolch Maven archetypes installed to your local maven repo, otherwise the
|
||||
following command will fail.
|
||||
{{% /notice %}}
|
||||
|
||||
```shell
|
||||
mvn archetype:generate \
|
||||
-DarchetypeGroupId=li.strolch \
|
||||
-DarchetypeArtifactId=li.strolch.mvn.archetype.webapp \
|
||||
-DarchetypeVersion=0.1.0-SNAPSHOT \
|
||||
-DgroupId=<my.groupid> \
|
||||
-DartifactId=<my-artifactId> \
|
||||
-Dversion=<my.version> \
|
||||
-Dpackage=<my.package> \
|
||||
-DappName="<my app name>"
|
||||
```
|
||||
|
||||
## Installing the web dependencies
|
||||
In the newly generated artifact, change to the `webapp` folder, and then run `npm install`:
|
||||
|
||||
```shell
|
||||
cd <my-artifactId>/src/main/webapp
|
||||
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
|
||||
again call `npm install` inside the webapp folder. {{% /notice %}}
|
||||
|
||||
### Building the WAR
|
||||
|
||||
|
||||
### Running the WAR
|
||||
Building the WAR uses the `package` maven goal, but to have the optimized WAR
|
||||
use the `release` profile.
|
||||
|
||||
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
|
||||
<env id="test" default="true">
|
||||
<root>/absolute/path/to/<my-artifactId>/runtime</root>
|
||||
<environment>test</environment>
|
||||
</env>
|
||||
```
|
||||
|
||||
Now we can build the project using the configured 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:
|
||||
```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
|
||||
```
|
||||
|
||||
And now you can open a browser and login: `http://localhost:8080/<my-artifactId>`
|
||||
|
||||
The default username and password are `admin` / `admin`. After logging you, you should see the following view:
|
||||
|
||||
|
||||
|
||||
Happy coding =))
|
||||
Loading…
Reference in New Issue