archetype-resources.README.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of simpleapp-archetype
This module defines a standard parent POM to use for various Incode applications and modules. Its primary purpose is to make it easy to use a set up maven mixins (https://github.com/odavid/maven-plugins) within child POMs. Specifically this means locking down the versions of plugins using pluginManagement. It does NOT define any mixins for Apache Isis.
There is a newer version: 2.0.0-M2
Show newest version
= SimpleApp

This application was generated by the link:http://isis.apache.org[Apache Isis] link:http://isis.apache.org/guides/ugfun.html#_ugfun_getting-started_simpleapp-archetype[simpleapp archetype].
It is intended as a starting point for developing your own applications.

== Quick start

Build using:

[source,bash]
----
mvn clean install
----

Run using:

[source,bash]
----
mvn -pl webapp jetty:run
----

Login using: 

* username: `sven`
* password: `pass`

The app runs with HSQLDB running in-memory, with sample data set up using link:https://isis.apache.org/guides/ugtst.html#_ugtst_fixture-scripts[fixture scripts].



== Application Structure

The following table explains the contents of each of the directories:

[width="100%",options="header,footer", cols="2a,4a"]
|====================
|Directory
|Description

|`application`
|Defines application-level classes such as menus and the ``AppManifest`` (which defines the modules that make up the application).
It also  holds application-wide integration tests/BDD specs.

|`module-simple`
|Holds the "simple" module, consisting of the `SimpleObject` entity and supporting repository, along with module-specific unit- and integration tests.
Also runs `isis:validate` goal for the domain objects within the module. +

[TIP]
====
Larger applications should consist of multiple modules; each such module can be copied from this starter module.
====

|`webapp`
|Assembles the application into a webapp (comprising both the Wicket viewer and Restful Objects viewer) and also as a docker image, and runs the `isis:swagger` goal.

|`_checks`
|Checkstyle and PMD rule sets for static analysis.

[TIP]
====
Extend/adapt these according to your own standards.
====


|====================

== More advanced use cases

* To enhance all JDO entities prior to running: +
+
[source,bash]
----
mvn -f pom-jdo-enhance-all.xml datanucleus:enhance
----

* To also generate the link:https://github.com/eirbjo/jetty-console[Jetty console], allowing the application to run as a standalone JAR: +
+
[source,bash]
----
mvn install -Dmavenmixin-jettyconsole
----
+
This can then be run using: +
+
[source,bash]
----
cd webapp/target && java -jar simpleapp-webapp-xxx-jetty-console.war
----
+
Add additional arguments ``--headless`` or ``--port 9999``, if required.
+
It can also be run using: +
+
[source,bash]
----
mvn -pl webapp && mvn antrun:run -Dmavenmixin-jettyconsole
----
+
or to specify arguments:
+
[source,bash]
----
mvn -pl webapp && mvn antrun:run -Dmavenmixin-jettyconsole \
    -Dmaven-antrun-plugin.jettyconsole.args="--headless --port 9090"
----


* To also generate source and javadoc JARs:
+
[source,bash]
----
mvn clean package -Dmavenmixin-sourceandjavadoc
----
+
[NOTE]
====
This is configured only for the `module-simple` module.
====

* To create the website (for the `module-simple` module) with source/javadoc and static analysis:
+
[source,bash]
----
mvn -pl module-simple site -Dmavenmixin-sourceandjavadoc -Dmavenmixin-staticanalysis
----
+
[NOTE]
====
This is intended to run only for the `module-simple` module, and will generate a website under`target/site/index.html`.
====


* To disable the running of unit tests: +
+
[source,bash]
----
mvn -DskipUTs 
----
+
[TIP]
====
By default, output of unit tests are in  `target/surefire-unittest-reports` (in the ``module-simple`` modules).
====

* To disable the running of integration tests: +
+
[source,bash]
----
mvn -DskipITs 
----
+
[TIP]
====
By default, output of integration tests are in  `target/surefire-integtest-reports` (in the ``application`` and ``module-simple`` modules).
====

* To disable the running of BDD specs: +
+
[source,bash]
----
mvn -DskipBSs 
----
+
[TIP]
====
By default, output of integration tests are in  `target/surefire-integbddspecs-reports` (in the ``application`` module).
====

* To disable the running of all tests and BDD specs: +
+
[source,bash]
----
mvn -DskipTests 
----

* To disable the running of the `isis:validate` goal: +
+
[source,bash]
----
mvn -Dskip.mavenmixin-isisvalidate  
----


* To disable the generation of cucumber reports: +
+
[source,bash]
----
mvn -Dskip.mavenmixin-cucumberreporting
----
+
[TIP]
====
By default, cucumber reports are generated at `target/cucumber-html-reports/overview-features.html` (in the ``application`` module).
====

* To disable the running of the `isis:swagger` goal:
+
[source,bash]
----
mvn -Dskip.mavenmixin-isisswagger
----
+
[TIP]
====
By default, Swagger schema definition files are generated at `target/generated-resources/isis-swagger` (in the ``webapp`` module).
====

* To package up the application as a docker image (specifying the docker image name as a system property): +
+
[source,bash]
----
mvn install -Dmavenmixin-docker -Ddocker-plugin.imageName=mycompany/myapp
----
+
Alternatively, define the `${docker-plugin.imageName}` in the `webapp` module and use simply: +
+
[source,bash]
----
mvn install -Dmavenmixin-docker
----
+
The packaged image can be viewed using `docker images`.

* To run a docker image previously packaged: +
+
[source,bash]
----
docker container run -d -p 8080:8080 mycompany/myapp
----
+
This can then be accessed at link:http://localhost:8080[localhost:8080].
+
See link:https://github.com/danhaywood/java-mavenmixin-docker#how-to-consume[mavenmixin-docker] for further details on how to run docker images.

* To upload the application as a docker image to link:https://hub.docker.com[docker hub] (or some other docker registry): +
+
[source,bash]
----
mvn -pl webapp deploy -Dmavenmixin-docker
----
+
This assumes that the `${docker-plugin.imageName}` property has been defined, _and_ also that docker registry credentials have been specified in `~/.m2/settings.xml`.
Once more, see link:https://github.com/danhaywood/java-mavenmixin-docker#how-to-configure[mavenmixin-docker] for further details.