README.adoc - isis-app-helloworld - Git at Google

 = HelloWorld
 :toc:

 This is a minimal Apache Isis application, intended as a starting point to learn what Apache Isis is all about.

 For real-world development, we recommend you start with the link:https://github.com/apache/isis-app-simpleapp[simpleapp] starter app, which has more structure and includes unit and integration tests.


 == Quick start

 * install prereqs:

 ** Java 8 LTS (eg link:https://adoptopenjdk.net/[Adopt OpenJDK] distribution)
 ** Maven 3.6 or later (http://maven.apache.org/download.cgi[download])
 * download and unzip
 +
 [source,bash]
 ----
 REPO=isis-app-helloworld
 BRANCH=master

 curl "https://codeload.github.com/apache/$REPO/zip/$BRANCH" > $REPO-$BRANCH.zip
 unzip $REPO-$BRANCH.zip
 mv $REPO-$BRANCH $REPO
 cd $REPO
 ----

 * Build using Maven:
 +
 [source,bash]
 ----
 mvn clean install
 ----

 * Run from Maven:
 +
 [source,bash]
 ----
 mvn spring-boot:run
 ----

 * Login using:

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

 The app runs with H2 running in-memory.


 == Development

 Apache Isis uses DataNucleus as its ORM, which requires that any entities are "enhanced", a post-compile process.

 Normally this is done as part of a "mvn clean install", but the entities can also be enhanced explicity using:

 [source,bash]
 ----
 mvn datanucleus:enhance -o
 ----

 This is useful to know if the application fails to bootstrap, complaining of "unenhanced entities".

 TIP: You can also use `enhance-all.sh`


 == Docker

 To package up the application as a docker image and push to a Docker registry:

 * set `$DOCKER_REGISTRY_USERNAME` and `$DOCKER_REGISTRY_PASSWORD` environment variables

 * modify the `to/image` configuration property for the link:https://github.com/GoogleContainerTools/jib[jib-maven-plugin] in the `pom.xml`
 +
 The default value is `docker.io/apacheisis/simpleapp:latest`:

 ** change `docker.io` prefix to push to a registry other than Docker hub
 ** change `apacheisis/simpleapp` to the name of your app.

 * package up the app with the `docker` profile:
 +
 [source,bash]
 ----
 mvn -pl webapp -DskipTests -Ddocker package
 ----

 Variants:

 * to specify Docker registry credentials through some other mechanism, configure the `pom.xml` for `maven-jib-plugin` (it supports a link:https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#authentication-methods[variety of ways] to specify credentials)

 * to override the image at the command line, use `-Dimage=...`.


 To run a docker image previously packaged:

 [source,bash]
 ----
 docker pull apacheisis/simpleapp:latest
 docker container run -d -p 8080:8080 apacheisis/simpleapp:latest
 ----

 This can then be accessed at link:http://localhost:8080[localhost:8080].


 === Externalized Configuration

 The application is configured to run in the `/run/secrets` directory.
 Configuration can be therefore be externalized by defining an `application.properties` secret for the Kubernetes or Docker Swarm cluster.

 Spring Boot will use these settings in preference to the configuration properties defined in `classpath:config/application.properties`, see link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config[Spring docs].
	= HelloWorld
	:toc:

	This is a minimal Apache Isis application, intended as a starting point to learn what Apache Isis is all about.

	For real-world development, we recommend you start with the link:https://github.com/apache/isis-app-simpleapp[simpleapp] starter app, which has more structure and includes unit and integration tests.


	== Quick start

	* install prereqs:

	** Java 8 LTS (eg link:https://adoptopenjdk.net/[Adopt OpenJDK] distribution)
	** Maven 3.6 or later (http://maven.apache.org/download.cgi[download])
	* download and unzip
	+
	[source,bash]
	----
	REPO=isis-app-helloworld
	BRANCH=master

	curl "https://codeload.github.com/apache/$REPO/zip/$BRANCH" > $REPO-$BRANCH.zip
	unzip $REPO-$BRANCH.zip
	mv $REPO-$BRANCH $REPO
	cd $REPO
	----

	* Build using Maven:
	+
	[source,bash]
	----
	mvn clean install
	----

	* Run from Maven:
	+
	[source,bash]
	----
	mvn spring-boot:run
	----

	* Login using:

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

	The app runs with H2 running in-memory.



	== Development

	Apache Isis uses DataNucleus as its ORM, which requires that any entities are "enhanced", a post-compile process.

	Normally this is done as part of a "mvn clean install", but the entities can also be enhanced explicity using:

	[source,bash]
	----
	mvn datanucleus:enhance -o
	----

	This is useful to know if the application fails to bootstrap, complaining of "unenhanced entities".

	TIP: You can also use `enhance-all.sh`


	== Docker

	To package up the application as a docker image and push to a Docker registry:

	* set `$DOCKER_REGISTRY_USERNAME` and `$DOCKER_REGISTRY_PASSWORD` environment variables

	* modify the `to/image` configuration property for the link:https://github.com/GoogleContainerTools/jib[jib-maven-plugin] in the `pom.xml`
	+
	The default value is `docker.io/apacheisis/simpleapp:latest`:

	** change `docker.io` prefix to push to a registry other than Docker hub
	** change `apacheisis/simpleapp` to the name of your app.

	* package up the app with the `docker` profile:
	+
	[source,bash]
	----
	mvn -pl webapp -DskipTests -Ddocker package
	----

	Variants:

	* to specify Docker registry credentials through some other mechanism, configure the `pom.xml` for `maven-jib-plugin` (it supports a link:https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#authentication-methods[variety of ways] to specify credentials)

	* to override the image at the command line, use `-Dimage=...`.



	To run a docker image previously packaged:

	[source,bash]
	----
	docker pull apacheisis/simpleapp:latest
	docker container run -d -p 8080:8080 apacheisis/simpleapp:latest
	----

	This can then be accessed at link:http://localhost:8080[localhost:8080].


	=== Externalized Configuration

	The application is configured to run in the `/run/secrets` directory.
	Configuration can be therefore be externalized by defining an `application.properties` secret for the Kubernetes or Docker Swarm cluster.

	Spring Boot will use these settings in preference to the configuration properties defined in `classpath:config/application.properties`, see link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config[Spring docs].