Maven Archetype to generate a webapp utilizing Turbine 5.x
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
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 of Maven (tested with 3.5.4 and 3.8.1).
Turbine Version: Turbine 5.1 Turbine-webapp-5.x
N.B.: This builds an integrationtest project in target/test-classes/projects/first/project/integrationtest (if you provide -Ddocker=true with docker enabled configuration, otherwise you need a hosted mysql database). You could start testing this archetype here..
First, you should have a local database installed and configured prior to beginning the application setup below.
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
mysql -u <user> -p mysql> create database helloWorld; mysql> \q
or other tools. The database should have been started and the database user granted enough rights.
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.
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
N.B. Set docker variable to true to enable Docker setup in building the artifact:
to immediately enable docker setup, when generating the archetype. If
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 may use
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.
<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.x</description> </archetype> </archetypes> </archetype-catalog>
Next, change into the newly generated project folder, in our case
Skip next two steps, if the build was successfull.
This will generate the OM layer and SQL code for creating the corresponding database tables.
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).
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
Find the Logs in src/main/webapp/logs and
Open a web browser to [http://localhost:8081/app]
Login should work with user admin/password or user/password.
By default Intake is used as an validation mechanism for authentication. You can change to the default login by setting
action.login=LoginUser in TurbineResources.properties and changing Login.vm appropriately (commented form)
If running from integration test, check/update
The security test is by default skipped as it requires a running mysql. It tests many of the Fulcrum Torque Turbine security aspects, you may activate it by calling
mvn test -DskipTests=false
CAVEAT: If initialization fails, double check your database credentials! If invalid the error might be somewhat hidden behind a Torque exception! Docker: If you have not initialized docker when creating the archetype instance, you have to edit TorqueTest.properties and adapt the url from localhost to db. You may then run the tests from inside the container service app.
To enable application development in Eclipse, run the following command and then import the project into Eclipse.
Once imported, update your project to be managed by Maven -> Right click on the project name -> Configure -> Convert to Maven project
To test the application can be deployed by Eclipse, select the run configuration “Run On Server” if you have a container configured with your eclipse environment.
You even could debug the app by setting the environment variable to something like this
set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n
before running the jetty server.
Be aware of settings and some smaller restrictions, which mostly will be fixed in the upcoming releases.
This project is licensed under the Apache Software License 2.0