<commit_before>image::https://www.aiticon.com/assets/images/appng_logo_760px.jpg[]
:snapshot: 1.15.0-SNAPSHOT
:stable: 1.14.4
:current: {snapshot}

[caption="Apache License 2.0",link=LICENSE]
image::https://img.shields.io/badge/License-Apache%202-blue.svg?style=flat-square[]

[caption="Maven Central",link=http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.appng%22%20AND%20a%3A%22appng-application%22]
image::https://img.shields.io/maven-central/v/org.appng/appng-application.svg?style=flat-square[]

[caption="Dependency Status",link=https://www.versioneye.com/user/projects/5975fd11368b08000e6d1ddc]
image::https://www.versioneye.com/user/projects/5975fd11368b08000e6d1ddc/badge.svg?style=flat-square[]

== Welcome to appNG
appNG is a *web application platform* and a *web application framework*, based on http://tomcat.apache.org/[Apache Tomcat^] and the https://spring.io[Spring Framework^].

With appNG, you can build your own applications and deploy them to the platform within minutes.

appNG is very well suited to create and operate your own application platform as a service (aPaaS).

== Core Features
* Clear separation of concerns following the *MVC* paradigm
* *Declarative UI definition* using schema-safe XML files
* Writing business logic by implementing a *handful of interfaces*
* Automatic *parameter-binding* and type conversion
* Built-in support for *paging, filtering sorting*
* Out-of-the-box support for *JPA* and http://projects.spring.io/spring-data/[Spring Data^]
* Built-In *connection pooling* using https://github.com/brettwooldridge/HikariCP[HikariCP^]
* Database *schema migrations* powered by https://flywaydb.org/[Flyway^]
* Built-In *role based access control*, which allows using field-based access
* Easily provide your own *SOAP* or *REST* based webservices
* Fully supports *internationalization* (i18n)
* *Easy deployment* by providing a repository mechanism
* Configurable caching powered by http://www.ehcache.org/[Ehcache^]
* Cluster support and *horizontal scaling*
* Powerful *administration tools*, including a graphical user interface (GUI), but also a command line interface (CLI) and a REST-client
* Supports the *Bean Validation API*
* Supports *indexing and searching*, powered by http://lucene.apache.org/[Lucene^]
* Customizable *templating* mechanism
* Configurable and extendable *authentication mechanism* (local, LDAP etc.)
* Provides *job scheduling* powered by http://www.quartz-scheduler.org/[Quartz^]
* Provides *tooling for common tasks* like resizing images, sending emails, geo-locating, report generation etc.
* Provides a large set of commonly used *libraries* such as https://commons.apache.org/[Apache Commons^] or https://github.com/FasterXML/jackson[Jackson^]
* Can serve *JSP*-content that can make use of the appNG *tag library*
* *Multi-tenancy* allows to separate or group applications
* *Rapid protoyping* enables you to design your user interface without writing one line of Java code

== Getting started

[NOTE]
====
The dollar sign ($) at the beginning of a line denotes the command prompt. Depending on your operating system and shell you might see other signs like %, # or >. This sign is not part of the command to be executed.
====

=== Download and run the appNG standalone Version
appNG is available as a standalone version, suitable for evaluation and testing purposes.

The standalone version also comes with *appNGizer*, the REST-based administration tool for appNG.

The standalone version can be found here:
https://appng.org/appng/builds/stable/appng-standalone-{stable}.zip

Check that Java 1.8 is available in your class path:
----
$ java -version
openjdk version "1.8.0_131"
OpenJDK Runtime Environment (build 1.8.0_131-8u131-b11-1~bpo8+1-b11)
OpenJDK 64-Bit Server VM (build 25.131-b11, mixed mode)
----

Unzip the file, change into the extracted folder and run
[source,subs=normal]
----
$ java -jar appng-standalone-{stable}.jar -i -u
----

Wait a few seconds, until the console output stops, then visit http://localhost:8080/manager in your browser.

Sign-in with the username `admin` and the password `<PASSWORD>`.

[NOTE]
====
When executing the jar for the next time, you *must* omit the parameters `-u` and `-i`, as they are only
allowed on the very first run (`-u` unpacks and configures the wrapped web applications, `-i` is for installing the appNG applications and the template).
====

=== Create your first appNG application
Using the *appNG Maven Archetype*, you can easily create your first own application.

Therefore, the following command must be used (replace `mygroupid` and `myartifactid` with the desired values):
[source,subs=normal]
----
$ mvn archetype:generate -DgroupId=mygroupid -DartifactId=myartifactid -DarchetypeGroupId=org.appng -DarchetypeArtifactId=appng-archetype-application -DarchetypeVersion={stable} -DinteractiveMode=false
----

Next, change into the created project folder and run `mvn package`.

In the target folder, a file named `myartifactid-1.0-SNAPSHOT-<yyyyMMdd-HHmm>.zip` should have been generated.
This file is the application archive.

=== Deploying the application
The next step is to deploy the application through a local repository, e.g. the application archives are served from the local file system.

During installation of the *appNG standalone* version, a local repository has been created at `/path/to/appng-standalone-{stable}/repository/`.
So the first step is to copy `myartifactid-1.0-SNAPSHOT-<yyyyMMdd-HHmm>.zip` to this location.

[TIP]
====
You can also build the application archive directly in the repository folder by using the Maven option `-DoutFolder=/path/to/appng-standalone-{stable}/repository/`
====

Next, we use the *appNG CLI* to install the application and to activate it for the site `manager` (that has been created during installation).

In `/path/to/appng-standalone-{stable}/appng/WEB-INF/bin`, execute the following commands:

[source]
----
$ ./appng install-application -n myartifactid -v 1.0-SNAPSHOT -r Local
$ ./appng activate-application -s manager -a myartifactid
----

Both commands should return without any message, meaning they where successful.

[NOTE]
====
You can also use the appNG Manager or the appNGizer to install and activate an application. To see a list of available CLI commands, execute `./appng` or `./appng -h`.

If you configure the appNGizer Maven Plugin for your project, you can automatically install and activate your application after the build.
====

The final step is to __reload__ the site `manager`. Therefore, login at http://localhost:8080/manager and click on the reload-icon shown next to the site in the overview. A message __"Site has been reloaded."__ should appear.

After a re-login (see details below), a new navigation item named `MYAPPLICATION` should appear on the site's navigation on the left. When clicking it, you see the results of your very first appNG application. *Congratulations!*

[NOTE]
====
During installation, the application's role `Admin` has been added to the appNG's built-in `Administrators` group, to which your user belongs to.
Since the groups of a user are determined once during login, you need to re-login to apply the newly received permissions.

For the following updates of your application, this step is therefore not necessary.
====


=== What's next?
You should import the Maven project into your favorite IDE. Then start browsing the code to get an idea of how an appNG application works.
You should also take a look at the https://appng.org/appng/docs/{snapshot}/reference/html/developerguide.html[Developer Guide].

You may also want to check out *appNGizer* at http://localhost:8080/appNGizer. The user manual can be found here:
https://appng.org/appng/docs/{snapshot}/appngizer/html/appngizer-user-manual.html

== Components

[width="100%",options="header"]
|====================
| Name | Type | Description

| https://github.com/appNG/appng[appNG^]
| Web application
| The appNG platform.

| https://github.com/appNG/appng[appNGizer^]
| Web application
| Provides the appNG REST API. The appNGizer is part of the appng Git Repository. During the build a separate appNGizer WAR file is packaged.
<commit_msg>APPNG-2050 "What's next?" should point to current version<commit_after>image::https://www.aiticon.com/assets/images/appng_logo_760px.jpg[]
:snapshot: 1.15.0-SNAPSHOT
:stable: 1.14.4
:current: {snapshot}

[caption="Apache License 2.0",link=LICENSE]
image::https://img.shields.io/badge/License-Apache%202-blue.svg?style=flat-square[]

[caption="Maven Central",link=http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.appng%22%20AND%20a%3A%22appng-application%22]
image::https://img.shields.io/maven-central/v/org.appng/appng-application.svg?style=flat-square[]

[caption="Dependency Status",link=https://www.versioneye.com/user/projects/5975fd11368b08000e6d1ddc]
image::https://www.versioneye.com/user/projects/5975fd11368b08000e6d1ddc/badge.svg?style=flat-square[]

== Welcome to appNG
appNG is a *web application platform* and a *web application framework*, based on http://tomcat.apache.org/[Apache Tomcat^] and the https://spring.io[Spring Framework^].

With appNG, you can build your own applications and deploy them to the platform within minutes.

appNG is very well suited to create and operate your own application platform as a service (aPaaS).

== Core Features
* Clear separation of concerns following the *MVC* paradigm
* *Declarative UI definition* using schema-safe XML files
* Writing business logic by implementing a *handful of interfaces*
* Automatic *parameter-binding* and type conversion
* Built-in support for *paging, filtering sorting*
* Out-of-the-box support for *JPA* and http://projects.spring.io/spring-data/[Spring Data^]
* Built-In *connection pooling* using https://github.com/brettwooldridge/HikariCP[HikariCP^]
* Database *schema migrations* powered by https://flywaydb.org/[Flyway^]
* Built-In *role based access control*, which allows using field-based access
* Easily provide your own *SOAP* or *REST* based webservices
* Fully supports *internationalization* (i18n)
* *Easy deployment* by providing a repository mechanism
* Configurable caching powered by http://www.ehcache.org/[Ehcache^]
* Cluster support and *horizontal scaling*
* Powerful *administration tools*, including a graphical user interface (GUI), but also a command line interface (CLI) and a REST-client
* Supports the *Bean Validation API*
* Supports *indexing and searching*, powered by http://lucene.apache.org/[Lucene^]
* Customizable *templating* mechanism
* Configurable and extendable *authentication mechanism* (local, LDAP etc.)
* Provides *job scheduling* powered by http://www.quartz-scheduler.org/[Quartz^]
* Provides *tooling for common tasks* like resizing images, sending emails, geo-locating, report generation etc.
* Provides a large set of commonly used *libraries* such as https://commons.apache.org/[Apache Commons^] or https://github.com/FasterXML/jackson[Jackson^]
* Can serve *JSP*-content that can make use of the appNG *tag library*
* *Multi-tenancy* allows to separate or group applications
* *Rapid protoyping* enables you to design your user interface without writing one line of Java code

== Getting started

[NOTE]
====
The dollar sign ($) at the beginning of a line denotes the command prompt. Depending on your operating system and shell you might see other signs like %, # or >. This sign is not part of the command to be executed.
====

=== Download and run the appNG standalone Version
appNG is available as a standalone version, suitable for evaluation and testing purposes.

The standalone version also comes with *appNGizer*, the REST-based administration tool for appNG.

The standalone version can be found here:
https://appng.org/appng/builds/stable/appng-standalone-{stable}.zip

Check that Java 1.8 is available in your class path:
----
$ java -version
openjdk version "1.8.0_131"
OpenJDK Runtime Environment (build 1.8.0_131-8u131-b11-1~bpo8+1-b11)
OpenJDK 64-Bit Server VM (build 25.131-b11, mixed mode)
----

Unzip the file, change into the extracted folder and run
[source,subs=normal]
----
$ java -jar appng-standalone-{stable}.jar -i -u
----

Wait a few seconds, until the console output stops, then visit http://localhost:8080/manager in your browser.

Sign-in with the username `admin` and the password `<PASSWORD>`.

[NOTE]
====
When executing the jar for the next time, you *must* omit the parameters `-u` and `-i`, as they are only
allowed on the very first run (`-u` unpacks and configures the wrapped web applications, `-i` is for installing the appNG applications and the template).
====

=== Create your first appNG application
Using the *appNG Maven Archetype*, you can easily create your first own application.

Therefore, the following command must be used (replace `mygroupid` and `myartifactid` with the desired values):
[source,subs=normal]
----
$ mvn archetype:generate -DgroupId=mygroupid -DartifactId=myartifactid -DarchetypeGroupId=org.appng -DarchetypeArtifactId=appng-archetype-application -DarchetypeVersion={stable} -DinteractiveMode=false
----

Next, change into the created project folder and run `mvn package`.

In the target folder, a file named `myartifactid-1.0-SNAPSHOT-<yyyyMMdd-HHmm>.zip` should have been generated.
This file is the application archive.

=== Deploying the application
The next step is to deploy the application through a local repository, e.g. the application archives are served from the local file system.

During installation of the *appNG standalone* version, a local repository has been created at `/path/to/appng-standalone-{stable}/repository/`.
So the first step is to copy `myartifactid-1.0-SNAPSHOT-<yyyyMMdd-HHmm>.zip` to this location.

[TIP]
====
You can also build the application archive directly in the repository folder by using the Maven option `-DoutFolder=/path/to/appng-standalone-{stable}/repository/`
====

Next, we use the *appNG CLI* to install the application and to activate it for the site `manager` (that has been created during installation).

In `/path/to/appng-standalone-{stable}/appng/WEB-INF/bin`, execute the following commands:

[source]
----
$ ./appng install-application -n myartifactid -v 1.0-SNAPSHOT -r Local
$ ./appng activate-application -s manager -a myartifactid
----

Both commands should return without any message, meaning they where successful.

[NOTE]
====
You can also use the appNG Manager or the appNGizer to install and activate an application. To see a list of available CLI commands, execute `./appng` or `./appng -h`.

If you configure the appNGizer Maven Plugin for your project, you can automatically install and activate your application after the build.
====

The final step is to __reload__ the site `manager`. Therefore, login at http://localhost:8080/manager and click on the reload-icon shown next to the site in the overview. A message __"Site has been reloaded."__ should appear.

After a re-login (see details below), a new navigation item named `MYAPPLICATION` should appear on the site's navigation on the left. When clicking it, you see the results of your very first appNG application. *Congratulations!*

[NOTE]
====
During installation, the application's role `Admin` has been added to the appNG's built-in `Administrators` group, to which your user belongs to.
Since the groups of a user are determined once during login, you need to re-login to apply the newly received permissions.

For the following updates of your application, this step is therefore not necessary.
====


=== What's next?
You should import the Maven project into your favorite IDE. Then start browsing the code to get an idea of how an appNG application works.
You should also take a look at the https://appng.org/appng/docs/{current}/reference/html/developerguide.html[Developer Guide].

You may also want to check out *appNGizer* at http://localhost:8080/appNGizer. The user manual can be found here:
https://appng.org/appng/docs/{current}/appngizer/html/appngizer-user-manual.html

== Components

[width="100%",options="header"]
|====================
| Name | Type | Description

| https://github.com/appNG/appng[appNG^]
| Web application
| The appNG platform.

| https://github.com/appNG/appng[appNGizer^]
| Web application
| Provides the appNG REST API. The appNGizer is part of the appng Git Repository. During the build a separate appNGizer WAR file is packaged.

{'fraction_non_alphanumeric': 0.1040599853694221, 'fraction_numerical': 0.015240185320653498, 'mean_word_length': 4.865212727922774, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 11, 'https://': 30, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1910994', 'n_tokens_mistral': 4993, 'n_tokens_neox': 4674, 'n_words': 1887}