[appng] Running shell script
+ sed s/:current: {snapshot}/:current: {stable}/g README.adoc
image::https://www.aiticon.com/assets/images/appng_logo_760px.jpg[]
:snapshot: 1.15.0-SNAPSHOT
:stable: 1.14.3
:current: {stable}
== 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
=== 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
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 `s3cr3t`.
[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.
| https://github.com/appNG/appng[appng-standalone^]
| Standalone version with bundled Tomcat
| Includes the applications: Manager, Authentication and Scheduler and also the appNG Template
| https://github.com/appNG/appng-manager[appNG Manager^]
| appNG core application
| Provides a web-based interface to administer appNG and to access other appNG applications.
| https://github.com/appNG/appng-authentication[appNG Authentication^]
| appNG core application
| Provides different authentication mechanisms for appNG.
| https://github.com/appNG/appng-scheduler[appNG Scheduler^]
| appNG core application
| Provides job scheduling services.
| https://github.com/appNG/appng-template[appNG Template^]
| appNG template
| The classic XSLT based template, used in conjunction with the appNG Manager.
|====================
NOTE: The appNG and appNGizer web applications run in Apache Tomcat, while appNG applications run on the appNG platform. appNG core applications have elevated permissions to access and control the appNG platform. appNG templates define the visual appearance of appNG applications.
== Documentation
[width="100%",options="header"]
|====================
| Component | Type | Format
|appNG
|JavaDoc
|https://appng.org/appng/docs/{current}/javadoc/[HTML]
|appNG
|Application Developer Guide
|https://appng.org/appng/docs/{current}/reference/html/developerguide.html[HTML^], https://appng.org/appng/docs/{current}/reference/pdf/developerguide.pdf[PDF^]
|appNGizer
|Setup Guide
|https://appng.org/appng/docs/{current}/appngizer/html/appngizer-setup-guide.html[HTML^], https://appng.org/appng/docs/{current}/appngizer/pdf/appngizer-setup-guide.pdf[PDF^]
|appNGizer
|Platform installation guide
|https://appng.org/appng/docs/{current}/appngizer/html/appngizer-platform-installation-guide.html[HTML^], https://appng.org/appng/docs/{current}/appngizer/pdf/appngizer-platform-installation-guide.pdf[PDF^]
|appNGizer
|User Manual
|https://appng.org/appng/docs/{current}/appngizer/html/appngizer-user-manual.html[HTML^], https://appng.org/appng/docs/{current}/appngizer/pdf/appngizer-user-manual.pdf[PDF^]
|====================
== Download Releases
[width="100%",options="header"]
|====================
| Component | Version | Format
|appNG
|{stable}
|https://appng.org/appng/builds/stable/appng-application-{stable}.war[WAR^]
|appNGizer
|{stable}
|https://appng.org/appng/builds/stable/appng-appngizer-{stable}.war[WAR^]
|Standalone
|{stable}
|https://appng.org/appng/builds/stable/appng-standalone-{stable}.zip[ZIP^]
|====================
== Download Snapshots
[width="100%",options="header"]
|====================
| Component | Version | Format
|appNG
|{snapshot}
|https://appng.org/appng/builds/snapshot/appng-application-{snapshot}.war[WAR^]
|appNGizer
|{snapshot}
|https://appng.org/appng/builds/snapshot/appng-appngizer-{snapshot}.war[WAR^]
|Standalone
|{snapshot}
|https://appng.org/appng/builds/snapshot/appng-standalone-{snapshot}.zip[ZIP^]
|====================
WARNING: Snapshots reflect the current development status. We do not recommend to use snapshots in production and might not be able to help, if you are running cutting-edge appNG. However, if you want to take a look at the latest features, feel free to download a copy and try it out.
== Getting help
Please ask your question at https://stackoverflow.com/[Stack Overflow^] and make sure to add the https://stackoverflow.com/questions/tagged/appng[appng^] tag to your question.
If you think you found a bug or want to propose a new feature, please create a ticket in our https://appng.org/jira/[issue tracker^].
If you require an *Enterprise Support Plan*, please contact https://www.aiticon.com[aiticon GmbH^] for further information. aiticon also offers trainings, consulting, development and hosting for appNG.
== How to contribute
Coming soon.
== Developer Links
* https://appng.org/jira/[Issue Tracker^]
* https://appng.org/jenkins/[Continuous Integration^]
* https://appng.org/appng/[Builds and Docs^]
* https://appng.org/schema/[XSD Schemata^]
* Maven Repository - Stable
* Maven Repository - Snapshot
* appNG Application Repository - Stable
* appNG Application Repository - Snapshot
== License
appNG is licensed under the https://www.apache.org/licenses/LICENSE-2.0[Apache License 2.0^].
![[Jenkins]](/jenkins/static/0ac95dd5/images/svgs/logo.svg){kind=logo}
