blob: e68a9d01bce181f670f1a8745b952bec13511270 [file] [log] [blame]
= HelloWorld
:toc:
This is a minimal link:https://isis.apache.org[Apache Isis] application, intended as a starting point to learn what the framework is all about.
[TIP]
====
For real-world development, we recommend you instead start with the link:https://github.com/apache/isis-app-simpleapp[simpleapp] starter app.
It provides more structure and includes examples of fixtures, unit tests, integration tests, and BDD (Cucumber) specs.
====
== 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" | jar xv
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].