This is an automated email from the ASF dual-hosted git repository. gk pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/turbine-archetypes.git
commit 8ca59fcb6a238f37af9b664bf5e75eb3e1e88a7d Author: gemkall <[email protected]> AuthorDate: Tue Jul 27 12:00:56 2021 +0200 update documentation, add and move infos --- README.md | 16 ++- src/main/resources/archetype-resources/README.md | 132 +++++++++++++++++++++ .../archetype-resources/docs/DOCKER-README.md | 14 ++- .../resources/archetype-resources/docs/README.md | 105 +++++----------- 4 files changed, 181 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index d05d8bc..7580d3e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# turbine-webapp-5.0 +# turbine-webapp-5.x -Maven Archetype to generate a webapp utilizing Turbine 5.0 +Maven Archetype to generate a webapp utilizing Turbine 5.x ## Getting Started @@ -9,22 +9,28 @@ These instructions will get you a copy of the project up and running on your loc ### Prerequisites * Java 8 JDK or later -* [MySQl](https://www.mysql.com/) - Database Server +* [MySQL](https://www.mysql.com/) - Database Server or [Docker] (https://docs.docker.com/get-docker/) * [Maven](https://maven.apache.org/) - Dependency Management -You should have Java 8 or later installed. The archetype sets up a new application using MySQL as the default database store. However, you can adjust this to use any database supported by Apache Torque 4.0. Therefore, you should be at least have a database instance where you have access rights to create a new database schema and populate it with the tables the application generates. Finally, this is a maven archetype, so of course you should install a local version of Maven (tested wi [...] +You should have Java 8 or later installed. The archetype sets up a new application using MySQL as the default database store. However, you can adjust this to use any database supported by Apache Torque 5.x. If not using Docker, you should therefore be at least have a database instance where you have access rights to create a new database schema and populate it with the tables the application generates. Finally, this is a maven archetype, so of course you should install a local version [...] ### Installing Eclipse integration: -You need to first add the Apache maven archetypes to your IDE so that you can take advantage of using the turbine-webapp-5.0 plugin to generate a new web application. +You need to first add the Apache maven archetypes to your IDE so that you can take advantage of using the turbine-webapp-5.x plugin to generate a new web application. The location of the remote catalog file is: http://repo.maven.apache.org/maven2/archetype-catalog.xml Step-by-step instructions on how to accomplish this can be found here: https://howtodoinjava.com/eclipse/how-to-import-maven-remote-archetype-catalogs-in-eclipse/ +Follow further instructions here: [README] (src/main/resources/archetype-resources/README.md). + +#### Development + +Clone this repository and build it with maven. + ## Built With diff --git a/src/main/resources/archetype-resources/README.md b/src/main/resources/archetype-resources/README.md new file mode 100644 index 0000000..a960e28 --- /dev/null +++ b/src/main/resources/archetype-resources/README.md @@ -0,0 +1,132 @@ +# Quick Guide to using the new Turbine 5.1 maven archetype for skeleton application generation + +## About this archetype + +Turbine Version: Turbine 5.1. + +You may skip Docker and Local Database Setup and read it later. + +### Docker Setup + +- If docker is available you could use the Docker build setup. Follow instructions here: [DOCKER README] (docs/DOCKER-README.md). + +#### Local Database Setup + +First, you should have a local database installed and configured prior to +beginning the application setup below. + +- Find more information about Logs and application structur here: [README] (docs/README.md). + + +### Maven archetype + +Next, you can invoke the Maven archetype for turbine-webapp-5.0 from +the command line as shown below - please update values starting +with 'groupId' as appropriate. + +```sh +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.turbine \ + -DarchetypeArtifactId=turbine-webapp-5.1 \ + -DarchetypeVersion=2.0.0-SNAPSHOT \ + -DgroupId=com.mycompany.webapp \ + -DartifactId=myhelloworld \ + -Dversion=1.0 \ + -Dturbine_app_name=HelloWorld \ + -Dturbine_database_adapter=mysql \ + -Dturbine_database_user=db_username \ + -Dturbine_database_password=db_password \ + -Dturbine_database_name=helloworld \ + -Dturbine_database_timezone=UTC \ + -Dturbine_database_url=jdbc:mysql://localhost:3306/ \ + -Dgoals=generate-sources,integration-test +``` + +#### Docker integration + +N.B. Set docker variable to true to enable Docker setup in building the artifact: + + -Ddocker=true + +to immediately enable docker setup, when generating the archetype. + +Currently only port 3306 is supported, if you do not want ot change the port seetings for the db container in docker-compose.yml + +### Development + +You may use + +```sh +mvn archetype:generate -DarchetypeCatalog=local +``` + +to avoid declaring the *archetype* variables. + +This requires you provide a local catalog in $HOME\.m2\archetype-catalog.xml. Find further information here: https://maven.apache.org/archetype/archetype-models/archetype-catalog/archetype-catalog.html. + +##### Example +<archetype-catalog ...> + <archetype> + <groupId>org.apache.turbine</groupId> + <artifactId>turbine-webapp-5.1</artifactId> + <version>2.0.0-SNAPSHOT</version> + <description>This archetype sets up a web application project based on Apache Turbine 5.0</description> + </archetype> + </archetypes> +</archetype-catalog> + +### Notes (local Database Setup only) + +When invoking archetype:generate like above, you already have set Turbine goals generate-sources,integration-test +and you can then skip them later. + +Be aware, when you set both mvn commands goals (which are maven phases actually), i.e with + +-Dgoals=generate-sources, integration-test + +you have to create the database (see above) before finishing the (interactive) archetype commands. +Otherwise you could catch up doing this later and after that is done calling the phases afterwards as mentioned below. + +#### turbine_database_url + +Note that the database URL (turbine_database_url) +will be appended with your database name +in the final pom.xml, so you do not need to specify that in +the configuration. Be sure that it ends with a slash ('/')! + +## Project Start and Usage + +Next, change into the newly generated project folder, in our case + +```sh +cd myhelloworld +``` + +Skip next two steps, if the build was successfull. + +```sh +mvn generate-sources +``` +This will generate the OM layer and SQL code for creating the corresponding database tables. + + +```sh +mvn integration-test +``` +This executes the SQL code to create the application schema defined in src/main/torque-schema. + +You should now check the database tables and if some data is missing +insert the sample data file in sample-mysql-data (Torque 4.0 has disabled the datasql task). + +```sh +mvn clean install +``` + +If you get an error like *"The driver has not received any packets"* probably the database is not up and running or the port may be another one. + +Last step on the command line is run the server by invoking +mvn -Pjetty + +- Now you can launch your new Turbine application by default [http://localhost:8081/app] (check port in pom.xml, if needed). + +- Find more information about Logs and application structur here: [README] (docs/README.md). diff --git a/src/main/resources/archetype-resources/docs/DOCKER-README.md b/src/main/resources/archetype-resources/docs/DOCKER-README.md index b6be1e2..f5e2b4e 100644 --- a/src/main/resources/archetype-resources/docs/DOCKER-README.md +++ b/src/main/resources/archetype-resources/docs/DOCKER-README.md @@ -59,16 +59,17 @@ N.B. You may use the command *docker compose* or *docker-compose*, but will slig <Set name="url">jdbc:mysql://db:3306/turbine</Set> ``` - - To change velocity templates check webapp in ** src/main/webapp**. Ohter resources might depend on https://www.eclipse.org/jetty/documentation/jetty-9/index.html#jars-scanned-for-annotations. -## Cleanup or restart (optional) +## Start, cleanup or restart -- Optionally Check system or cleanup, e.g. with docker-compose down, docker-compose down -v or docker sytem prune (removes any container on system). +- Optionally check system or cleanup, e.g. with docker-compose down, docker-compose down -v or docker sytem prune (removes any container on system). - If services are already installed, activate/start by docker-compose up +You might do it separately for the db and the app service. The latter will start a maven build process finally starting the jetty server. Maven depends on the Maven settings, which are set in docker-resources/app/settings.xml. The local maven repository is mapped in the docker-compose.yml final to the host's local repository settings.localRepository during the first build, which reads the host's environment. Be sure to check this, if compilation errors occur as the host's maven executabl [...] + Example Logs: [Note] [Entrypoint]: Entrypoint script for MySQL Server 8.0.25-1debian10 started. @@ -97,8 +98,7 @@ N.B. You may use the command *docker compose* or *docker-compose*, but will slig [INFO] --- torque-maven-plugin:5.1-SNAPSHOT:generate (torque-om) @ integrationtest --- [main] INFO | org.apache.torque.generator.control.Controller - readConfiguration() : Starting to read configuration files - -- Starting the app service will build the app and start jetty with Maven on port 8081. +- Starting the app service will build the app and start jetty with Maven on port 8081 by default. This command is set as a **command** in the app service in docker compose. Currently the docker-compose is generated once more, if starting the containers, this will overwrite m2repo and may result in errors. @@ -235,3 +235,7 @@ Error starting userland proxy: mkdir /port/tcp:0.0.0.0:13306:tcp:...:3306: input # stops all running containers docker stop $(docker ps -a -q) + +## License + +This project is licensed under the Apache Software License 2.0 diff --git a/src/main/resources/archetype-resources/docs/README.md b/src/main/resources/archetype-resources/docs/README.md index 6e7674b..b26b963 100644 --- a/src/main/resources/archetype-resources/docs/README.md +++ b/src/main/resources/archetype-resources/docs/README.md @@ -21,19 +21,16 @@ under the License. # Quick Guide to using the new Turbine 5.1 maven archetype for skeleton application generation - ## About this archetype Turbine Version: Turbine 5.1. -### Docker Setup - -Skip Local Database setup and read later DOCKER-README.md +Follow either Local database Setup or Docker Setup ### Local database Setup First, you should have a local database installed and configured prior to -beginning the application setup below. +beginning the application setup. As we are using MySQL by default you need to create the database in MySQL (server version should be at least 5.5, because of new sql driver), e.g. with @@ -43,40 +40,34 @@ mysql> \q or other tools. The database should have been started and the database user granted enough rights. -### Maven archetype - -Next, you can invoke the Maven archetype for turbine-webapp-5.0 from -the command line as shown below - please update values starting -with 'groupId' as appropriate. -```sh -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.turbine \ - -DarchetypeArtifactId=turbine-webapp-5.1 \ - -DarchetypeVersion=2.0.0-SNAPSHOT \ - -DgroupId=com.mycompany.webapp \ - -DartifactId=myhelloworld \ - -Dversion=1.0 \ - -Dturbine_app_name=HelloWorld \ - -Dturbine_database_adapter=mysql \ - -Dturbine_database_user=db_username \ - -Dturbine_database_password=db_password \ - -Dturbine_database_name=helloworld \ - -Dturbine_database_timezone=UTC \ - -Dturbine_database_url=jdbc:mysql://localhost:3306/ \ - -Dgoals=generate-sources,integration-test -``` +### Docker integration (short intro) -#### Docker integration (short intro) +Run this command -N.B. Change dabase url to use service id and set docker environment to true: + mvn clean install -Pdocker - -Dturbine_database_url=jdbc:mysql://db:3306/ \ - -Ddocker=true to immediately enable docker setup, when generating the archetype. Currently only port 3306 is supported, if you do not want ot change the port seetings for the db container in docker-compose.yml + +You then should change to the generated docker resources: + + cd <project>/target/docker-resources + +and follow the instructions in [DOCKER README] (docs/DOCKER-README.md). In short you may do the following (you may have to start docker desktop on windows): + + docker compose configurable + docker compose build --no-cache + docker compose up + + - First time Building might take a couple of minutes. + + - Now you can launch your new Turbine application by default [http://localhost:8081/app] + + +- Read [DOCKER README] (DOCKER-README.md). You then need not to follow the following chapters, but could immediately go to @@ -91,48 +82,6 @@ and then follow the instructions in DOCKER-README.md. In short you may do the fo - Now you can launch your new Turbine application by default [http://localhost:8081/app] -### Development - -You may use - -```sh -mvn archetype:generate -DarchetypeCatalog=local -``` - -to avoid declaring the *archetype* variables. - -This requires you provide a local catalog in $HOME\.m2\archetype-catalog.xml. Find further information here: https://maven.apache.org/archetype/archetype-models/archetype-catalog/archetype-catalog.html. - -##### Example -<archetype-catalog ...> - <archetype> - <groupId>org.apache.turbine</groupId> - <artifactId>turbine-webapp-5.1</artifactId> - <version>2.0.0-SNAPSHOT</version> - <description>This archetype sets up a web application project based on Apache Turbine 5.0</description> - </archetype> - </archetypes> -</archetype-catalog> - -### Notes - -When invoking archetype:generate like above, you already have set Turbine goals generate-sources,integration-test -and you can then skip them later. - -Be aware, when you set both mvn commands goals (which are maven phases actually), i.e with - --Dgoals=generate-sources, integration-test - -you have to create the database (see above) before finishing the (interactive) archetype commands. -Otherwise you could catch up doing this later and after that is done calling the phases afterwards as mentioned below. - -#### turbine_database_url - -Note that the database URL (turbine_database_url) -will be appended with your database name -in the final pom.xml, so you do not need to specify that in -the configuration. - ## Project Start and Usage Next, change into the newly generated project folder, in our case @@ -238,11 +187,15 @@ before running the jetty server. Be aware of settings and some smaller restrictions, which mostly will be fixed in the upcoming releases. -- Keep groups/roles lower case (which should be fixed in Fulcrum Security 1.1.1/Turbine 4.0) +- Keep groups/roles lower case (which should be fixed in current Fulcrum Security 2.x/Turbine 5.x) - abstract classes and managers are included (because of some minor bugs in Fulcrum Security 1.1.0, same as above) -- LogoutUser action is included (fix in Turbine 4.0, getUserFromSession) +- LogoutUser action is included as an custom example - LoginUser action is included (to check for anonymous user, may be fixed in future release) - OM (Torque Object Mapper) stub classes are included (until configurable in schema with Torque version 2.1) -- TurbineConfiguration returns a Commons configuration object, even if field is not assignable (will be fixed in Turbine 4.0, you can then assign e.g. to String instead, cft. SecureScreen) +- TurbineConfiguration returns a Commons configuration object, even if field is not assignable (fixed in Turbine 5.x, you can then assign e.g. to String instead, cft. SecureScreen) - Database connection is done initially by default with JNDI. If you want to change it, check Torque.properties and (1) for Tomcat, META-INF/context.xml or (2) for Jetty, WEB-INF/jetty-env.xml. +## License + +This project is licensed under the Apache Software License 2.0 +
