blob: 9da86f646005aa2eb59759490dfb31f59dc4de7b [file] [log] [blame]
= 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
Build using:
[source,bash]
----
mvn clean install
----
Run using:
[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].