From a26534b99aa6837d878813435aef585a4ac66fa5 Mon Sep 17 00:00:00 2001 From: Robert von Burg Date: Tue, 16 Aug 2022 22:18:29 +0200 Subject: [PATCH] [Major] Updated website for easier dev starting --- content/development/_index.md | 209 +-------------------- content/development/building.md | 27 +++ content/development/converting-existing.md | 18 ++ content/development/main-class-app.md | 40 ++++ content/development/maven-archetypes.md | 20 ++ content/development/prerequisites.md | 38 ++++ content/development/web-app.md | 119 ++++++++++++ 7 files changed, 263 insertions(+), 208 deletions(-) create mode 100644 content/development/building.md create mode 100644 content/development/converting-existing.md create mode 100644 content/development/main-class-app.md create mode 100644 content/development/maven-archetypes.md create mode 100644 content/development/prerequisites.md create mode 100644 content/development/web-app.md diff --git a/content/development/_index.md b/content/development/_index.md index a4829e8..c61d262 100644 --- a/content/development/_index.md +++ b/content/development/_index.md @@ -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= \ - -DartifactId= \ - -Dversion= \ - -Dpackage= \ - -DappName="" -``` - -#### 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 - - /absolute/path/to/<my-artifactId>/runtime - test - -``` - -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/` - -The default username and password are `admin` / `admin`. After logging you, you should see the following view: - -![Strolch Demo App](/assets/images/demo-app.png) - -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= \ - -DartifactId= \ - -Dversion= \ - -DappName="" -``` - -You change into the directory of the new project and then build the project by calling: - -```shell -cd -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 %}} diff --git a/content/development/building.md b/content/development/building.md new file mode 100644 index 0000000..9e7b60b --- /dev/null +++ b/content/development/building.md @@ -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. diff --git a/content/development/converting-existing.md b/content/development/converting-existing.md new file mode 100644 index 0000000..28bd83d --- /dev/null +++ b/content/development/converting-existing.md @@ -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 %}} diff --git a/content/development/main-class-app.md b/content/development/main-class-app.md new file mode 100644 index 0000000..02d6e80 --- /dev/null +++ b/content/development/main-class-app.md @@ -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= \ + -DartifactId= \ + -Dversion= \ + -DappName="" +``` + +You change into the directory of the new project and then build the project by calling: + +```shell +cd +mvn clean package +``` + +Start the program using: + +```shell +mvn exec:java +``` + +Happy coding =)) diff --git a/content/development/maven-archetypes.md b/content/development/maven-archetypes.md new file mode 100644 index 0000000..30957ee --- /dev/null +++ b/content/development/maven-archetypes.md @@ -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. \ No newline at end of file diff --git a/content/development/prerequisites.md b/content/development/prerequisites.md new file mode 100644 index 0000000..f616b0d --- /dev/null +++ b/content/development/prerequisites.md @@ -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" +``` diff --git a/content/development/web-app.md b/content/development/web-app.md new file mode 100644 index 0000000..12acc6f --- /dev/null +++ b/content/development/web-app.md @@ -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= \ + -DartifactId= \ + -Dversion= \ + -Dpackage= \ + -DappName="" +``` + +## Installing the web dependencies +In the newly generated artifact, change to the `webapp` folder, and then run `npm install`: + +```shell +cd /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 + + /absolute/path/to/<my-artifactId>/runtime + test + +``` + +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/` + +The default username and password are `admin` / `admin`. After logging you, you should see the following view: + +![Strolch Demo App](/assets/images/demo-app.png) + +Happy coding =))