archetype-resources.README.adoc Maven / Gradle / Ivy
Go to download
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.
= 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 -pl module-simple datanucleus:enhance -o
----
* 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.