306 document the webforj war deployment method (#311)

* feat: moving old install section into advanced, creating simpler getting started with WAR method

* feat: added skeleton article, restructured based on Hyyan's feedback

* feat: updated install section, renaming and linking changes, added missing property descriptions

* feat: revise getting started guide, update section titles and streamline instructions

* feat: update installation title to 'Running with BBjServices'

* feat: update redirect path and rename 'Quick start' to 'Getting Started'

* feat: updated the app basics to reflect current hello world skeleton program

* refactor: rename 'Intro' to 'Introduction' in category JSON

* refactor: remove unnecessary disabled comment in overview.md

* refactor: update app basics documentation to reflect changes in Application and HomeView classes

* feat: adding deploy and reload articles

* refactor: update terminology in deploy and reload documentation for clarity

* chore: hiding TOC from JRebel

* chore: hiding TOC from JRebel

* feat: created a draft licensing section

* feat: added getting started with archetype

* docs: updated current BBj docs to reflect archetype usage

* docs: update getting started guide to reflect webforJ archetypes

* docs: update getting started guide to include archetype version

* docs: update basics documentation and add HelloWorldView example

* docs: disable pagination_next field to basics documentation

* docs: remove welcome-file-list entry from properties documentation

* docs: update JRebel and Maven Jetty documentation for clarity and configuration changes

* feat: Adding release blog for 24.20

* docs: update release notes for version 24.20, highlighting WAR deployment features and configuration

* feat: added web.xml section to the release blog

* refactor: remove unnecessary text

* chore: updating version number

* docs: updating licensing section

* docs: added table to archetype, still need to create component to get latest version

* docs: update getting started guide with specific archetype details

* docs: fix typo in getting started guide for archetypeGroupId explanation

* docs: add prerequisites section to getting started guide

* docs: rename intro directory to introduction and update references

* docs: BROKEN LINKS

* docs: remove obsolete installation and getting started documentation

* docs: rename maven-jetty.md to maven-jetty-plugin.md and update scan interval to 1 second

* style: update blog-wrapper to use 'main' instead of schema.org itemtype

* style: add 'disabled' to the accept vocabulary list

* style: remove 'JVM' and 'webforJ' from the accept vocabulary list

* docs: updated to remove blsconf to make sure it isn't confusing

---------

Co-authored-by: Hyyan Abo Fakher <hyyanaf@gmail.com>

blog/2024-11-25-webforj-v24.20/24.20.md

@@ -0,0 +1,107 @@
+---
+title: What's new in version 24.20?
+description: Get to know the features, fixes, and functionality new in webforJ version 24.20.
+slug: whats-new-v24.20
+date: 2024-11-25
+authors:
+  - name: webforJ Team
+    url: https://github.com/webforj
+    image_url: /img/webforj_icon.svg
+tags: [webforJ, v24.20, release]
+image: 'https://documentation.webforj.com/release_blog/_images/social-cover-24.20.png'
+hide_table_of_contents: false
+---
+
+![cover image](../../static/release_blog/_images/24.20.png)
+
+webforJ version `24.20` is live and available for development. Learn more about what main features and fixes are included in this release.
+
+<!-- truncate -->
+
+# 24.20
+
+As always, see the [GitHub release overview](https://github.com/webforj/webforj/releases/tag/24.20) for a more comprehensive list of changes. Highlighted below are some of the most exciting changes:
+
+## New features and enhancements 🎉
+
+We’re excited to introduce version `24.20` which brings a game-changing update to webforJ - the shift to **WAR deployment**.
+
+<!-- vale off -->
+### WAR Deployment in webforJ
+<!-- vale on -->
+
+In `24.20`, webforJ fully embraces the WAR (Web Application Archive) pattern for packaging and deploying apps. WAR files are a tried-and-true standard in Java development, bundling everything your app needs - code, resources, and dependencies - into a single, deployable archive.
+
+
+### Updating your project for WAR deployment
+
+Switching your project to use WAR deployment in webforJ is straightforward. To do so, ensure the following components are in place:
+
+1. **Include the Maven Jetty Plugin**:
+
+Add the Maven Jetty plugin to your pom.xml to handle the deployment process. The Jetty plugin allows you to package and deploy your app as a WAR file effortlessly.
+
+```xml
+<plugin>
+    <groupId>org.eclipse.jetty</groupId>
+    <artifactId>jetty-maven-plugin</artifactId>
+    <version>11.0.15</version>
+</plugin>
+```
+
+:::info Replacing the webforJ install plugin
+In projects using the webforJ install plugin, remove this plugin from your POM to ensure that it isn't triggered when running `mvn install`.
+:::
+
+2. **Add the required configuration and resources:**
+
+Include the following essential files in your project to ensure it runs as a WAR:
+
+- `webapp/WEB-INF/web.xml`:
+Defines the app's deployment descriptor, specifying how the app should be deployed and managed by the server.
+
+- `resources/webforj.conf`:
+Centralized configuration file for customizing your app's behavior.
+
+- `resources/certificate.bls`:
+A license certificate file required to run your app. You’ll receive this file when registering for a license.
+
+- `resources/blsclient.conf`:
+Configuration file for license properties.
+
+Once added, an example project structure may look like this:
+
+```bash 
+src/main/
+    java/                      # Java source files
+    resources/
+        webforj.conf           # App configuration
+        blsclient.conf         # License configuration
+        certificate.bls        # License certificate
+    webapp/
+        WEB-INF/
+            web.xml            # Deployment descriptor
+```
+### Configuration with `webforj.conf`
+
+The `webforj.conf` file centralizes app configuration in HOCON format. With this file, you can tweak key settings for your app, such as the app's entry point, and whether or not to run in `DEBUG` mode.
+
+Here are some of the most useful settings you can define in `webforj.conf`:
+| **Property**                | **Description**                                                                                                                                     | **Default**       |
+|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
+| `webforj.entry`             | The fully qualified name of the class that extends `App`, acting as the entry point for your app.                                                 | *Not Set*         |
+| `webforj.debug`             | Enables debug mode, showing detailed errors in the browser and printing debug logs to the console.                                                | `false`           |
+| `webforj.reloadOnServerError` | Automatically reloads the app if the server temporarily becomes unavailable during development.                                                  | `on`              |
+| `webforj.clientHeartbeatRate` | Sets the interval for client pings to the server to query availability. Use shorter intervals in development and longer ones in production.         | `50s`             |
+
+### Configuring the `web.xml` file
+
+The `web.xml` file is a crucial part of Java web app deployment, serving as the deployment descriptor for your app. In webforJ, it defines key settings like the servlet configuration and URL mappings. This file must be located in the `WEB-INF` directory of your project’s deployment structure.
+
+| **Setting**                     | **Explanation**                                                                                                            | **Default Value**        |
+|----------------------------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------|
+| `<display-name>`                | Sets the display name for the web app, typically derived from the project name. This name appears in app servers' management consoles. | `${project.name}`        |
+| `<servlet>` and `<servlet-mapping>` | Defines the `WebforjServlet`, the core servlet for handling webforJ requests. This servlet is mapped to all URLs (`/*`), making it the main entry point for web requests. | `WebforjServlet`         |
+| `<load-on-startup>`             | Specifies that `WebforjServlet` should be loaded when the app starts. Setting this to `1` ensures the servlet loads immediately, improving initial request handling. | `1`                      |
+
+To learn more about the various configuration options available, as well as other options for configuring your webforJ project, browse [this article](../../docs/configuration/overview) detailing configuration in webforJ.

docs/advanced/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Advanced Topics",
-  "position": 8,
+  "position": 45,
   "link": {
     "type": "doc",
     "id": "overview"

docs/architecture/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Architecture",
-  "position": 9,
+  "position": 50,
   "link": {
     "type": "doc",
     "id": "overview"

docs/building-ui/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Building UIs",
-  "position": 4,
+  "position": 25,
   "link": {
     "type": "doc",
     "id": "overview"

docs/components/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Components",
-  "position": 6,
+  "position": 35,
   "link": {
     "type": "doc",
     "id": "overview"

docs/getting-started/_category_.json → docs/configuration/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Getting Started",
-  "position": 3,
+  "label": "Configuration",
+  "position": 42,
   "link": {
     "type": "doc",
     "id": "overview"

docs/configuration/bbj-installation/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Running with BBjServices",
+  "position": 10,
+  "link": {
+    "type": "doc",
+    "id": "overview"
+  }
+}

docs/getting-started/configuration.md → docs/configuration/bbj-installation/configuration.md

@@ -1,12 +1,31 @@
 ---
-sidebar_position: 1
+title: Install Plugin
+sidebar_position: 4
 displayed_sidebar: documentationSidebar
 ---
 
-# Configuration
-
 You can configure webforJ using a project's POM file, which is designed to make deploying an app easy. The following sections outline the various options you can change to achieve a desired result.
 
+## Engine exclusion
+
+When running with `BBjServices`, the `webforj-engine` dependency should be excluded, as the features provided by the engine are already available.
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>com.webforj</groupId>
+    <artifactId>webforj</artifactId>
+    <version>${webforj.version}</version>
+    <exclusions>
+      <exclusion>
+        <groupId>com.webforj</groupId>
+        <artifactId>webforj-engine</artifactId>
+      </exclusion>
+    </exclusions> 
+  </dependency>
+</dependencies>
+```
+
 ## POM file tags
 
 Tags within the `<configuration>` tag can be changed to configure your app. Editing the following lines in the default POM file that comes with the [`HelloWorldJava`](https://github.com/webforj/HelloWorldJava) starting repository will result in these changes:
@@ -32,7 +51,7 @@ Tags within the `<configuration>` tag can be changed to configure your app. Edit
 </plugin>
 ```
 
-- **`<deployurl>`** This tag is the URL where the webforJ endpoint for the project installation can be reached. For users running their app locally, a default port of 8888 is used. For users running Docker, the port should be changed to the port that was entered when [configuring the Docker container](../installation/docker.md#2-configuration).
+- **`<deployurl>`** This tag is the URL where the webforJ endpoint for the project installation can be reached. For users running their app locally, a default port of 8888 is used. For users running Docker, the port should be changed to the port that was entered when [configuring the Docker container](./docker#2-configuration).
 
 - **`<classname>`** This tag should contain the package and class name of the app you wish to run. This will be the single class in your project that extends the `App` class and runs from the base URL.
 
@@ -45,7 +64,7 @@ Tags within the `<configuration>` tag can be changed to configure your app. Edit
 There are two ways to run a specific program in your app:
 
 1. Place the program within the `run()` method of the class that extends `App`.
-2. Utilze [routing](../../docs/routing/overview) in your webforJ app to give the program a dedicated URL.
+2. Utilze [routing](../../routing/overview) in your webforJ app to give the program a dedicated URL.
 
 ## How webforJ selects an entry point
 

docs/installation/docker.md → docs/configuration/bbj-installation/docker.md

@@ -6,7 +6,7 @@ title: Docker
 # Docker installation
 
 This section of the documentation will cover the steps required for users who wish to develop using Docker. Changes to your code
-will be made on your development machine, and the resulting application will be run in Docker. 
+will be made on your development machine, and the resulting app will be run in Docker. 
 
 ## 1. Downloading Docker
 
@@ -77,7 +77,7 @@ Open the "Optional settings" menu
 
 ![DWCJ Image Search](./_images/docker/Step_6l.png#rounded-border)
 
-Select a desired host port where you can see your application running within Docker
+Select a desired host port where you can see your app running within Docker
 
 ![DWCJ Image Search](./_images/docker/Step_7l.png#rounded-border)
 
@@ -86,20 +86,20 @@ Click "Run" to start the container
 ![DWCJ Image Search](./_images/docker/Step_8l.png#rounded-border)
 
 <!-- Click the `Run` button, which will pop up a configuration window. These settings are optional, but it is highly recommended to
-supply the `Host port` configuration setting, as this will be necessary later when running your application.
+supply the `Host port` configuration setting, as this will be necessary later when running your app.
 
 ![Configuration](./_images/docker/2.png)
 
 Once this is finished, click the `Run` button at the bottom of the window, which will create a new container with your specified settings. -->
 
-:::success Important!
+:::success Important
 Make sure to take note of the custom Host port number you provide, as this will be needed later.
 :::
 
 ## 3. Running your app
 
 Once the container has been created, webforJ applications can be run within the container instead of locally. First, it is necessary to configure
-the POM file of your project correctly. Once this is done, going to a specific URL in the browser will show the application.
+the POM file of your project correctly. Once this is done, going to a specific URL in the browser will show the app.
 
 ### Configuring your POM file
 
@@ -139,22 +139,39 @@ Once an entry similar to the one above has been created, customize the following
 - Change the `<deployurl>` entry to use the port number that you match the **Host port** that you configured for your container
 in the previous step.
 
-- Ensure that the `<classname>` entry matches the name of the application you want to run.
+- Ensure that the `<classname>` entry matches the name of the app you want to run.
 
 - If your `<username>` and `<password>` credentials are different for your installation of BBj, change these.
 
-:::info
-The [webforj-hello-world](https://github.com/webforj/HelloWorldJava) project will come with the POM file already mostly configured - with other settings remaining the same, only the `<deployurl>` tag will need to be changed.
-:::
 
-### Launching the application
+### Using the starter project
+To create and scaffold a new project, follow these steps:
+
+1) **Navigate to the proper directory**:
+Open a terminal and move to the folder where you want to create your new project.
+
+2) **Run the archetype command**:
+Use the Maven command below, and customize the `groupId`, `artifactId`, and `version` as needed for your project. To proceed with the webforJ starter project, use the following command:
+
+```bash
+mvn -B archetype:generate \
+-DarchetypeGroupId=com.webforj \
+-DarchetypeArtifactId=webforj-archetype-bbj-hello-world \
+-DgroupId=org.example \
+-DartifactId=my-hello-world-app \
+-Dversion=1.0-SNAPSHOT
+```
+
+After running the command, Maven will generate the project files necessary to run the starter project.
+
+### Launching the app
 
 Once this has been done, run a `mvn install` in your project directory. This will run the webforJ install plugin, and allow
-you to access your application. To see the application, you'll want to go to the following URL:
+you to access your app. To see the app, you'll want to go to the following URL:
 
 `http://localhost:YourHostPort/webapp/YourPublishName`
 
 Replace `YourHostPort` with the Host port you configured with Docker, and `YourPublishName` is replaced by the text inside the `<publishname>` tag of the POM. 
-If done correctly, you should see your application render!
+If done correctly, you should see your app render.
 
 <!-- <UnderConstruction /> -->

docs/installation/github-codespaces.md → docs/configuration/bbj-installation/github-codespaces.md

@@ -1,48 +1,48 @@
----
-sidebar_position: 2
-title: Github Codespaces
----
-
-import UnderConstruction from '@site/src/components/PageTools/UnderConstruction';
-
-webforJ's [Hello World Repository](https://github.com/webforj/webforj-hello-world) has been configured to run in Github Codespaces. Codespaces is a cloud-based development environment, and allows you to develop and run webforJ applications directly within your browser. To start developing with this tool, follow the steps below:
-
-## 1. Navigate to the HelloWorldJava repository
-
-To start, you'll need to go to the HelloWorldJava repository, which can be found [at this link](https://github.com/webforj/webforj-hello-world). Once there, click on the green **"Use this template"** button, and then the **"Open in a codespace"** option.
-
-![Codespace buttons](./_images/github/1.png#rounded-border)
-
-## 2. Running your program
-
-After waiting for the codespace to load, you should see a browser version of VS Studio Code open with the "HelloWorldJava" sample program loaded. From here, you can run the sample program, or start developing!
-
-To compile a program, open the terminal in VS Code and run the `mvn install` command.
-
-![Maven Install](./_images/github/2.png#rounded-border)
-
-If everything completes successfully, you should see the `BUILD SUCCESS` message.
-
-:::warning WARNING 
-Make sure to use the `mvn install` command instead of VS Code's built-in Maven interface for installing your program.
-:::
-
-Once this has been done, you'll need to navigate to a specific web address to see your program. To do this, first click on the **"Ports"** tab at the bottom of VS Code. Here, you will see two ports, 8888 and one other, listed.
-
-![Forwarded Ports](./_images/github/3.png#rounded-border)
-
-Click on the small **"Open in Browser"** button, resembling a globe, in the **"Local Address"** section of the **Ports** tab, which will open a new tab in your browser.
-
-![Browser Button](./_images/github/4.png#rounded-border)
-
-When the browser tab is open, you'll want to add to the end of the URL to ensure that your application is run. First, add a `/webapp` to the end of the web address, which will end in `github.dev`. After that, add the correct app and class name (if applicable) to show the desired application. To see how to properly configure the URL, [follow this guide](../getting-started/configuration).
-
-:::success Tip
-If you want to run the default "Hello World" program, simple add `/hworld` after the `/webapp` in the URL:
-<br />
-
-![Modified URL](./_images/github/5.png#rounded-border)
-:::
-
-
-Once this is done, you should see your application running in the browser, and can modify it in the VS Code instance running within codespaces!
+---
+sidebar_position: 2
+title: Github Codespaces
+---
+
+import UnderConstruction from '@site/src/components/PageTools/UnderConstruction';
+
+[`webforj-hello-world`](https://github.com/webforj/webforj-hello-world) has been configured to run in Github Codespaces. Codespaces is a cloud-based development environment, and allows you to develop and run webforJ applications directly within your browser. To start developing with this tool, follow the steps below:
+
+## 1. Navigate to the HelloWorldJava repository
+
+To start, you'll need to go to the HelloWorldJava repository, which can be found [at this link](https://github.com/webforj/webforj-hello-world). Once there, click the green **"Use this template"** button, and then the **"Open in a codespace"** option.
+
+![Codespace buttons](./_images/github/1.png#rounded-border)
+
+## 2. Running your program
+
+After waiting for the codespace to load, you should see a browser version of VS Studio Code open with the "HelloWorldJava" sample program loaded. From here, you can run the sample program, or start developing.
+
+To compile a program, open the terminal in VS Code and run the `mvn install` command.
+
+![Maven Install](./_images/github/2.png#rounded-border)
+
+If everything completes successfully, you should see the `BUILD SUCCESS` message.
+
+:::warning WARNING 
+Make sure to use the `mvn install` command instead of VS Code's built-in Maven interface for installing your program.
+:::
+
+Once this has been done, you'll need to navigate to a specific web address to see your program. To do this, first click the **"Ports"** tab at the bottom of VS Code. Here, you will see two ports, 8888, and one other, listed.
+
+![Forwarded Ports](./_images/github/3.png#rounded-border)
+
+Click on the small **"Open in Browser"** button, resembling a globe, in the **"Local Address"** section of the **Ports** tab, which will open a new tab in your browser.
+
+![Browser Button](./_images/github/4.png#rounded-border)
+
+When the browser tab is open, you'll want to add to the end of the URL to ensure that your app is run. First, add a `/webapp` to the end of the web address, which will end in `github.dev`. After that, add the correct app and class name (if applicable) to show the desired app. To see how to properly configure the URL, [follow this guide](./configuration).
+
+:::success Tip
+If you want to run the default "Hello World" program, simple add `/hworld` after the `/webapp` in the URL:
+<br />
+
+![Modified URL](./_images/github/5.png#rounded-border)
+:::
+
+
+Once this is done, you should see your app running in the browser, and can modify it in the VS Code instance running within codespaces.