diff --git a/BuildMaster/platforms/java/#.md b/BuildMaster/platforms/java/#.md index 483ad3f9..0847a50c 100644 --- a/BuildMaster/platforms/java/#.md +++ b/BuildMaster/platforms/java/#.md @@ -1,65 +1,78 @@ --- title: Java -subtitle: Java Applications & Maven Goals +subtitle: Building Java Applications sequence: 200 +show-headings-in-nav: true --- -You can use BuildMaster to build applications and components written in any language. That includes Java-based projects that use Maven to manage the build automation. +[Java](https://www.java.com/) is one of the top five programming languages in the software ecosystem, running on billions of devices from global cloud systems to single-board computers like Raspberry Pi. -[Maven](http://maven.apache.org/) allows a project to build using its project object model (POM) and a set of plugins that are shared by all projects using Maven, providing a uniform build system. Maven is a project management tool that uses a build lifecycle framework for developers. It is a build automation tool used primarily for Java projects. +[Jakarta EE](https://jakarta.ee/) is the de-facto set of multi-tier specifications and extensions to Java SE that enables enterprise application services such as: -To build Java-based projects, you can the Maven operation within BuildMaster's [Java extension](https://inedo.com/den/inedox/java) to execute goals and phases. +{.docs} + - Servlets + - JavaServer Faces (JSF) *(component-based UI for web apps)* + - Web services + - Framework libraries & APIs: + - Dependency injection + - Persistence + - Transactions -## What are Maven Phases and Goals? +Formerly known as Java Enterprise Edition (Java EE) and Java 2 Platform, Enterprise Edition (J2EE), it is sponsored by the [Eclipse Foundation] and contributed to by Oracle. -A Maven _phase_ represents a stage in the Maven build lifecycle. Each Build Lifecycle is Made Up of Phases. +The most common Java application servers are: -There are three major _built-in_ Build Life Cycles: +{.docs} + - [Apache TomEE](java/tomcat) + - [Red Hat WildFly](java/wildfly) (formerly JBoss Application Server) + - [JBoss Enterprise Application Platform (EAP)](java/wildfly) (paid version of WildFly) + - [Oracle WebLogic](https://www.oracle.com/middleware/technologies/weblogic.html) + - [Eclipse Glassfish](https://projects.eclipse.org/proposals/eclipse-glassfish) (formerly Oracle) + - [IBM WebSphere](https://www.ibm.com/cloud/websphere-application-platform/) -1. default -2. clean -2. site +When deploying Java locally or to small web servers, the most common web servers are: -The default lifecycle comprises of the following Build Phases: +{.docs} + - [Eclipse Jetty](java/jetty) + - [Apache Tomcat](java/tomcat) -``` -- validate - validate the project is correct and all necessary information is available -- compile - compile the source code of the project -- test - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed -- package - take the compiled code and package it in its distributable format, such as a JAR. -- integration-test - process and deploy the package if necessary into an environment where integration tests can be run -- verify - run any checks to verify the package is valid and meets quality criteria -- install - install the package into the local repository, for use as a dependency in other projects locally -- deploy - done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects. -``` +## Building Java Applications {#building data-title="Build Process"} -When you run a phase – all goals bound to this phase are executed in order. So to go through the above phases, we just have to call one command: +Java programs are compiled into bytecode as `.class` files and packaged into one of many types of [JAR files](https://docs.oracle.com/javase/tutorial/deployment/jar/basicsindex.html). At run time, bytecode is interpreted and executed by the Java Virtual Machine ([JVM](https://docs.oracle.com/javase/specs/jvms/se13/html/jvms-1.html#jvms-1.2)). To develop Java, you'll always develop against the [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/javase-jdk13-doc-downloads.html). -`mvn { Ex: mvn install }` +Common tools used to build and test Java programs are: -The above command, will start from the `validate` phase and continue until all the phases are executed sequentially until the `install` phase. Maven can either execute a goal or a phase (or even multiple goals or multiple phases) as follows: +{.docs} + - [**javac**](https://docs.oracle.com/en/java/javase/13/docs/specs/man/javac.html) - primary Java compiler included with the JDK + - [**Maven**](java/maven) - most common XML-based build and deployment tool with all the support of Ant plus dependency management, packaging, publish support + - [**Ant**](java/ant) - basic build tool with customizable XML build tasks + - [**Gradle**](java/gradle) - similar to Maven but uses a [Groovy](http://groovy-lang.org/)-based configuration file + - [**JUnit**](java/junit) - most common unit test framework for Java applications -`mvn clean install plugin:goal` +## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"} -## How to Execute a Maven Goal in BuildMaster +At a high level, the process of building and deploying Java applications with BuildMaster is: -There are two ways to excute a maven goal in BuildMaster. Either with the `Execute-Maven` operation or the `InedoCore::Exec`. +{.docs} + - Get source code from the source control repository + - Compile project with Maven + - Capture artifact for deployment -`Excute-Maven` is included in our Java Extension. and Can be executed with this simple OtterScript. -``` -Execute-Maven - ( - GoalsAndPhases: ":" - ); -``` +## Deploying Java Applications {#deployment data-title="Deployment Process"} -Using the InedoCore::Exec command will require you to [install maven](http://maven.apache.org/) on the build machine. Maven is a Java based tool, therefore JDK (JDK 1.7 or above, preferably JDK 1.8) installation on your system is a pre-requisite. -``` - InedoCore::Exec - ( - FileName: ~\FullPathToMaven\mvn, - Arguments: : - ); -``` +Java applications in an enterprise are typically deployed to on-premise or to hosted application servers such as: -_To find out more information about running maven commands you can review [this documentation](http://maven.apache.org/run.html)_ +{.docs} + - IBM WebSphere + - Oracle WebLogic + - Red Hat JBoss/WildFly + - Tomcat + +Deployment to application servers involves running a host-specific "deploy" command on a remote server, typically with a WAR file as an input argument. + +Deploying to web servers is a little different. Deploying to Tomcat servers, for example, follows the common format: + +{.docs} + - Stop Tomcat services + - Deploy WAR file + - Start Tomcat services diff --git a/BuildMaster/platforms/java/ant.md b/BuildMaster/platforms/java/ant.md new file mode 100644 index 00000000..6a0321c4 --- /dev/null +++ b/BuildMaster/platforms/java/ant.md @@ -0,0 +1,153 @@ +--- +title: Ant +subtitle: Building Java Applications with Ant +sequence: 200 +show-headings-in-nav: true +--- + +[Ant](https://ant.apache.org) is a Java-based build tool for Java. + +Written in Java, the original author, James Duncan Davidson, said the name is an acronym for "Another Neat Tool." Ant was released on April 19th, 2000, as part of [Tomcat](java/tomcat) 3.1 and was used to build Tomcat and nothing else. Ant was then separated after it's donation to the Apache Software Foundation because it was determined it could fix many issues developers had with Makefiles, and the first official standalone release was Ant 1.1 on July 19th, 2000. It was the most popular build tool for Java until [Maven](java/maven). + +Some of Ant's best qualities: + - extremely flexible + - does not impose coding conventions + - does not impose directory layouts + +## Overview & Concepts {#overview data-title="Ant Overview"} + +Because Ant is built on Java, it can be run on any OS. Ant uses XML-based configuration files called build files that define a target tree. + +These configuration files are made up of: + +{.docs} +- Project: the master build definition containing all of the targets, tasks, and properties + - Each project defines one or more targets. +- Targets: a set of tasks you want to be executed + - Can depend on other targets + - When starting Ant, you select which target(s) you want executed +- Tasks: a piece of code that can be executed +- Properties: key/value pairs used to customize or provide shortcuts to values used within targets and tasks + - These can be set: + - externally and passed in when calling Ant + - internally within a target or task + +To extend Ant, users can develop their own "antlibs" containing Ant tasks and types. These are based in Java and have specific interfaces they must implement. For dependency management, use [Apache Ivy](https://ant.apache.org/ivy/). + +## Apache Ivy {#ivy data-title="Apachy Ivy"} + +[Apache Ivy](https://ant.apache.org/ivy/) is a tool for recording, tracking, resolving, and reporting project dependencies, and it's characterized by flexibility, configurability, and tight integration to Ant. IT is the best option for managing dependencies when using Ant. + +Ivy uses the Maven 2 repository to resolve the dependencies you declare in an Ivy file, and its syntax is very similar to Apache Ant. + +## Building with Ant {#building data-title="Building with Ant"} + +First, create a build file for Ant. + +A basic build file typically includes these targets: + +{.docs} +- `init`: Creates the build directory structure used by compile +- `compile`: Compiles the java files in the src folder into bytecode and outputs them into the build folder +- `dist`: Packages the build folder into a JAR, WAR, etc... and copies that into the dist folder +- `clean`: Deletes the build and dist directories + +Defining your project default target to be `dist` will simplify executing an Ant build. Additional targets can be included. + +### Example Build File +``` + + + simple example build file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Running Ant Via the Command Line + +##### Using the Default Target +``` +ant -buildfile "ProfitCalcJava.build" -Dversion:1.1 +``` + +##### Specifying Targets +``` +ant -buildfile "ProfitCalcJava.build" -Dversion:1.1 clean dist +``` + +## Executing Ant with BuildMaster {#buildmaster data-title="Ant in BuildMaster"} + +Ant must be installed on the build server prior to executing any of these commands. Setting ANT_HOME in the path is preferable, but you can use the AntPath variable function to override it. To do any of this, however, the Java extension must be installed in BuildMaster. + +Use the following OtterScript in a deployment plan: + +``` +Java::Build-AntProject +( + BuildPath: ProfitCalcJava.build + ProjectBuildTarget: dist, + ProjectBuildTarget: target, + BuildProperties: @(version=$ReleaseNumber.$BuildNumber) +) +``` + +- Running Ant directly: +``` +Exec "ant -buidfile ProfitCalcJava.build -Dversion:$ReleaseNumber.$BuildNumber dist"; +``` + +- Example plan that gets the latest source code from Git and captures a Maven artifact as a BuildMaster artifact: +``` +Git::Get-Source +( + RepositoryUrl: https://github.com/Inedo/ProfitCalcJava.git, + Branch: master +); + +Java::Build-AntProject +{ + BuildPath: ProfitCalcJava.build + BuildTarget: dist + ProjectBuildTarget: target, + BuildProperties: @(version=$ReleaseNumber.$BuildNumber) +}; + +Create-Artifact ProfitCalcJava +( + From: target, + Include: @(*.jar, *.war, *.ear) +); +``` diff --git a/BuildMaster/platforms/java/gradle.md b/BuildMaster/platforms/java/gradle.md new file mode 100644 index 00000000..12850a7e --- /dev/null +++ b/BuildMaster/platforms/java/gradle.md @@ -0,0 +1,137 @@ +--- +title: Gradle +subtitle: Building Java Applications with Gradle +sequence: 500 +show-headings-in-nav: true +--- + +[Gradle](https://gradle.org/) is a Java-based build automation tool focused on flexibility and performance. +Gradle is: + +{.docs} +- highly customizable and extensible at its core +- very fast, because it only processes the inputs that have changed instead of everything each time +- powerful, because it can build many popular languages. + +Gradle build scripts are written in [Groovy](https://groovy-lang.org/) or [Kotlin](https://kotlinlang.org/) instead of the typical XML files that Maven and Ant use. Gradle is also the official build tool for Android. + +Gradle is not just limited to building Java; it also comes with native support for: + +{.docs} + - C/C++ + - Kotlin + - Groovy + - Scala + - JavaScript + - and more. + + +## Overview & Concepts {#overview data-title="Gradle Overview"} + +When creating a build file for Gradle, you typically would create a file named `build.gradle`. Gradle has two different options for syntax within a build file: + +{.docs} +- Groovy (most common) +- Kotlin + +When using Kotlin, you will need to append `.kts` to the end you your Gradle files (i.e., `build.gradle.kts` and `settings.gradle.kts`). + +Since the build files are built using Groovy or Kotlin, build files: + +{.docs} +- Can execute custom code +- Are compiled which will give better syntax errors +- Can provide intellisense while creating build files + + +Gradle has migration paths for converting [Maven](https://docs.gradle.org/6.2.1/userguide/migrating_from_maven.html) and [Ant](https://docs.gradle.org/6.2.1/userguide/migrating_from_ant.html) builds to Gradle. + +Currently, Gradle only works with two package sources: + +{.docs} +- Apache Maven +- Apache Ivy + +Gradle supports single and multi-project builds. In addition to a build file, Gradle defines a settings file (named settings.gradle). The settings file allows you define your project hierarchy and/or handle multiple build projects in your build process. It also allows you to extend the build script by building plugins that you include as dependencies within `build.gradle`. + +You can use the `gradle init` command to create a Java project using the default Gradle folder structure. This, however, is only a starting point, as Gradle does not require any specific folder structure. + +### Gradle Build Lifecycle + +Gradle's build lifecycle includes: + +{.docs} +- Project: a collection of tasks +- Tasks: execution of a basic piece of work (i.e., compiling classes) +- Build phases: + - Initialization: determines which projects are going to be built and creates a project instance for each project + - Configuration: configures all project instances + - Execution: + - Determines the sub-set of tasks to execute based on which inputs have changed and which projects where configured in the Configuration phase + - Executes this determined sub-set + + +## Building with Gradle {#building data-title="Building with Gradle"} + +Before you can build with Gradle, you need to make sure that Gradle is setup in your system's PATH. Once it is in your system's PATH, you will need to create a `build.gradle` file for Gradle. Then, optionally create a `settings.gradle` to configure your build file. You can use other Gradle files to compile other projects (e.g., unit tests) that can be called from the main Gradle file. + +When using Gradle to build Java, you would need to include the `java-library` plugin. Including that plugin automatically enables the following features: + +{.docs} +- `compileJava` task that compiles all your Java source files under `src/main/java` +- `compileTestJava` task that compiles all your java test files under `src/test/java` +- `test` task that runs the tests from `src/test/java` +- `jar` task that packages the main compiled classes from `compileJava` and resources from `src/main/resources` into a single `JAR` named `-.jar` +- `javadoc` task that generates Javadoc for the main classes + +Remember, Gradle is highly customizable: You can modify the build file to work with your application. Although Gradle has a default folder structure, you can easily customize that by defining your folder locations in your build file. And you can also add functionality by including more plugins. + +### Example build.gradle File + +``` +plugins { + id 'java-library' +} + +java { + sourceCompatibility = JavaVersion.VERSION_1_8 + targetCompatibility = JavaVersion.VERSION_1_8 +} + +version = '1.2.1' +``` + +### Running Gradle via the Command Line + +Gradle highly encourages using the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html#gradle_wrapper). When using the Gradle Wrapper, you should replace Gradle with `gradlew.bat` (or `./gradlew` for Linux): + +``` +gradle build +``` + +## Executing Gradle with BuildMaster {#buildmaster data-title="Gradle in BuildMaster"} + +Gradle must be installed on the build server prior to executing any of these commands. Setting GRADLE_HOME in the path is preferable. To do any of this, however, the Java extension must be installed in BuildMaster. + +Use the following OtterScript in a deployment plan: + +``` +Exec "gradle build" +``` + +An example plan that gets the latest source code from Git and captures a Gradle artifact as a BuildMaster artifact: + +``` +Git::Get-Source +( + RepositoryUrl: https://github.com/Inedo/ProfitCalcJava.git, + Branch: master +); + +Exec "gradle build" + +Create-Artifact ProfitCalcJava +( + From: build/libs +); +``` diff --git a/BuildMaster/platforms/java/jetty.md b/BuildMaster/platforms/java/jetty.md new file mode 100644 index 00000000..4f060145 --- /dev/null +++ b/BuildMaster/platforms/java/jetty.md @@ -0,0 +1,44 @@ +--- +title: Jetty +subtitle: Deploying Java Applications to Jetty +sequence: 500 +show-headings-in-nav: true +--- + +[Eclipse Jetty](https://www.eclipse.org/jetty/) is a free web server and javax.servlet container used to run Java web applications that has been part of the Eclipse Foundation since 2009. Jetty is open-source and is free for commercial use and distribution as well as local development needs. It includes support for HTTP/2, WebSocket, OSGi, JMX, JNDI, JAAS and many other integrations and can be standalone or used to embed a webserver into devices, tools, frameworks, and more. While Jetty does *not* implement the entire Jakarta EE specification, most Java IDEs include templates (e.g., Maven archetypes) that create the necessary project structure to build and deploy a web applications in Jetty. + +## Overview & Concepts {#overview data-title="Jetty Overview"} + +Jetty is built on Java and requires the Java JRE to run. It does not include separate Windows and Linux scripts; instead, you start the server directly from Java: + +``` +java -jar start.jar +``` + +Jetty does not include a Graphical User Interface (GUI), so you can only make changes via the command line. For example, you would make configuration changes by passing parameters to the `java -jar start.jar` command, (i.e., `java -jar start.jar --add-to-start=https,http2`). + +It also does not come out of the box with the components to run as a Windows Service, but you can use third-party tools to configure it. You can view [Jetty's documentation](https://www.eclipse.org/jetty/documentation/9.4.26.v20200117/startup.html) for more information. Jetty *does* include scripts to run as a Linux/Unix service out of the box. You can learn more by viewing [Jetty's documentation](https://www.eclipse.org/jetty/documentation/9.4.26.v20200117/startup.html). + + +## Deploying Java Web Applications to Jetty {#deployment data-title="Deployment"} + +The standard way of deploying Jetty applications is copying a WAR file to `$JETTY_HOME\webapps` and letting Jetty's deployment scanner scan and automatically deploy the file. + +You can also customize application deployments in Jetty using the [Jetty Deployable Descriptor XML File](https://www.eclipse.org/jetty/documentation/9.4.26.v20200117/configuring-specific-webapp-deployment.html). + +If you are using a non-standard web application structure or static files, you will need to set up a custom Deployable Descriptor File. + +## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"} + +The process of deploying Jetty in BuildMaster follows the same pattern as the manual process. + +Example OtterScript plan: +``` +set $JETTY_HOME = $EnvironmentVariable(JETTY_HOME); + +# the ProfitCalcJava artifact contains org.inedo.profitcalc-1.2.3.war +Deploy-Artifact ProfitCalcJava +( + To: $JETTY_HOME\webapps +); +``` diff --git a/BuildMaster/platforms/java/junit-tests.md b/BuildMaster/platforms/java/junit-tests.md deleted file mode 100644 index 9beebc00..00000000 --- a/BuildMaster/platforms/java/junit-tests.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: JUnit -subtitle: JUnit Tests in BuildMaster -keywords: unit test, buildmaster, junit, junit test, java -sequence: 100 ---- - -BuildMaster is a fully-functional Continuous Integration tool for a variety of platforms allowing your organization to start using CI/CD today. If your are writing __Java applications__ and want to implement unit testing as part of your deployment pipeline Buildmaster can quite easilty accomodate that. - -#### What is JUnit? -JUnit is a unit testing framework for Java programming language. JUnit has been important in the development of test-driven development, and is one of a family of unit testing frameworks collectively known as xUnit, that originated with JUnit. - -#### Why should you use JUnit with BuildMaster? -You can use this automation framework for both unit testing and UI testing. You can set up buildmaster to require unit tests to pass before the deployment can go to the next stage. - -Execute the JUnit peraration -``` - Execute-JUnit - ( - Include: JUnitTest.class, - From: /usr/share/java/ - ); -``` - -#### Pass or Fail -If your tests all pass you will see the results in your execution logs. If __any__ of the tests happen to fail the error will be logged and the rest of your plan will be skipped. You may also want to wrap this operation in a try/catch to handle the error more cleanly or to do more with the test results like notify any interested parties. - -#### Pipeline Promotion -Add an _Automatic Gate Approval_ with the type of _Unit Tests_ to your integration stage in your pipeline to prevent promotion to a stage if a unit test fails. (The promotion can ultimately be manually forced if needed). This will ensure that if the application has automatically been promoted to a stage that requires gate approval, it has has passed all unit tests. - diff --git a/BuildMaster/platforms/java/junit.md b/BuildMaster/platforms/java/junit.md new file mode 100644 index 00000000..8b080b22 --- /dev/null +++ b/BuildMaster/platforms/java/junit.md @@ -0,0 +1,74 @@ +--- +title: JUnit +subtitle: Running JUnit Tests +keywords: buildmaster, unit-testing, junit +sequence: 500 +show-headings-in-nav: true +--- + +[JUnit](https://junit.org/) is the most popular unit testing framework for Java projects. Developers are able to run tests directly in most IDEs such as IntelliJ, Eclipse, and more. + +Within a CI build pipeline, tests can be run using common tasks/phases in build tools such as [Maven](https://maven.org/) and [Gradle](https://gradle.org/) or alternatively executed directly with [Java directly](https://junit.org/junit5/docs/current/user-guide/#running-tests-console-launcher-options): + +``` +java -jar junit-platform-console-standalone-1.6.0.jar +``` + +## JUnit Testing in BuildMaster {#buildmaster data-title="JUnit with BuildMaster"} + +BuildMaster's [built-in unit test reporting](/docs/buildmaster/ci-cd/testing-and-verification/unit-tests) is designed to work with the JUnit test framework. + +To enable integration with JUnit: + +{.docs} + 1. Ensure the Java extension is installed + 2. A configuration variable named `$JavaPath` exists and is configured to point to the `java` executable (`java.exe` on Windows) + +An example build plan that gets source, compiles the source using Maven, and runs JUnit tests is: + +``` +GitHub::Get-Source +( + Organization: Inedo, + Repository: ProfitCalcJava +); + +Java::Execute-Maven +( + GoalsAndPhases: "test-compile compile", + In: ProfictCalcJava +); + +Java::Execute-JUnit +( + Includes: **.class, + From: ProfictCalcJava\src\test +); +``` + +Note that this example may be slightly redundant because the default Maven lifecycle will execute tests in phase prior to "package." Running the `Execute-JUnit` operation separately enables BuildMaster to record the output in its own format for reporting purposes. + +## Test Result Behavior {#results data-title="Test Result Behavior"} + +Test results are logged in the build execution log and also to the *Unit Test* section of a build, with a more specific breakdown and/or test history. If a unit test fails, the default behavior is to halt the build. + +If the desired behavior is to continue regardless of failure, wrap the operation in an OtterScript try/catch statement. For example: + +``` +try +{ + Java::Execute-JUnit + ( + Includes: **.class, + From: ProfictCalcJava\src\test + ); +} +catch +{ + Log-Warning Ignoring test failures for now...; +} +``` + +## Preventing Deployment of Builds with Failed Unit Tests {#preventing-deployment data-title="Prevent Deploying Untested Builds"} + +To ensure that a build with failed unit tests is never deployed, add a "Unit Tests Passed" [automated check](/docs/buildmaster/verification/pipelines/approvals-and-gates/automated-checks) to the pipeline stage immediately following the build stage (typically Integration). This will prevent a build with failed unit tests (and optionally inconclusive tests) from being promoted regardless if errors were logged or ignored in the build plan. Of course, this build can still be forced to the next stage, but special administrative permissions are required in order to do so. diff --git a/BuildMaster/platforms/java/maven.md b/BuildMaster/platforms/java/maven.md new file mode 100644 index 00000000..7a1e22a9 --- /dev/null +++ b/BuildMaster/platforms/java/maven.md @@ -0,0 +1,88 @@ +--- +title: Maven +subtitle: Building Java Applications with Maven +sequence: 100 +show-headings-in-nav: true +--- +[Apache Maven](https://maven.apache.org/) (or just "Maven") is the most common build, packaging, and deployment tool for [Java](java). Maven began as an attempt to standardize the build processes in the [Jakarta Turbine project](https://turbine.apache.org/), which consisted of multiple projects, build scripts, and JAR output files -- but Maven made it easy to publish project information and share JAR files. + +The original objectives of Maven were: + +{.docs} +- Simplifying the build process +- Providing a uniform build system +- Providing quality project information +- Providing guidelines for best practices development +- Allowing transparent migration to new features +- All popular IDEs (Eclipse, Netbeans, IntelliJ) use Maven under the hood + +## Maven Overview {#overview data-title="Maven Overview"} + +Maven is a command line tool that works at a project level. In Maven, a project is conceptualized as an application or library and is defined by a POM.xml file. Maven packages projects into an artifact (JAR, WAR, EAR, etc.), and artifacts may be published to a local repository on a developer's machine or build server or to a enterprise repository such as [ProGet](/proget) to share them with other developers. + +### Archetypes + +A Maven archetype is a project template used to create Java projects for web applications, Jakarta EE projects, plugins for Maven, "sites" (i.e., a documentation site included in the maven artifact), or custom archetypes. Maven ships with a default set of archetypes, and additional archetypes can be downloaded from a Maven repository. + + +### Build Lifecycle + +A build lifecycle in Maven consists of a series of phases, and each phase is bound to zero or more goals. A "goal" in Maven is essentially an individual build task. Executing a phase will implicitly execute all phases before it in the lifecycle (e.g., `compile` must run before `test`). You can find more information on various lifecycles [here](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#Lifecycle_Reference). + +The most common way to associate goals with phases is to configure packaging element in your POM file under the `` element. Some of the valid packaging values are `jar` (the default), `war`, `ear`, and `pom`. + + +## Building with Maven {#building data-title="Building"} + +Once you have configured your Maven project, the general pattern for building any type of Maven application involves: + - Run `mvn clean package` + - The `clean` phase will remove all files generated by the previous build, and the `package` phase will execute all necessary phases to generate an artifact + - For sites, it would be `mvn clean site`, since the package phase does not exist for sites + +The build process can be customized by referencing a specific lifecycle in the POM file or by executing specific goals instead of phases directly. To execute goals directly, you would run: +``` +mvn clean:clean resources:resources compiler:compile jar:jar +``` + + +## Executing Maven with BuildMaster {#buildmaster data-title="Maven in BuildMaster"} + +To execute Maven builds in BuildMaster: + +{.docs} +- Maven must be installed on the build server *prior to* executing any of these commands +- the Java extension must be installed in BuildMaster +- *Do not* execute the `install` phase + - When deploying with BuildMaster, we recommend only *packaging* artifacts because the package output will be captured and deployed as a BuildMaster artifact + +Use the following OtterScript in a deployment plan to execute Maven in BuildMaster: +``` +Java::Execute-Maven +( + GoalsAndPhases: "clean package" +); +``` +- Running Maven directly: +``` +Exec "mvn clean package"; +``` + +Example plan that gets the latest source code from Git and captures a Maven artifact as a BuildMaster artifact: +``` +Git::Get-Source +( + RepositoryUrl: https://github.com/Inedo/ProfitCalcJava.git, + Branch: master +); + +Java::Execute-Maven +( + GoalsAndPhases: "clean package", + In: ProfitCalcJava +); + +Create-Artifact ProfitCalcJava +( + From: ProfitCalcJava\target +); +``` diff --git a/BuildMaster/platforms/java/scala.md b/BuildMaster/platforms/java/scala.md new file mode 100644 index 00000000..b9682d54 --- /dev/null +++ b/BuildMaster/platforms/java/scala.md @@ -0,0 +1,47 @@ +--- +title: Scala +subtitle: Building and Deploying Scala Applications +sequence: 800 +show-headings-in-nav: true +--- + +[Scala](https://www.scala-lang.org/) is a statically typed programming language featuring both object-oriented and functional principles. It is designed to run on the Java JVM or in a browser ([Scala JS](https://www.scala-js.org/)). It also addresses some of the criticisms of Java. + +## Building Scala Applications {#building data-title="Building Scala Applications"} + +Scala is built similarly to Java. Because Scala code compiles to Java bytecode, any compiled Scala application can run on the Java Runtime Environment (JRE), or in other words, any platform that runs an application built from traditional Java source code. + +`sbt`, short for "Scala Build Tool", is the typical build tool used to build Scala applications and is included with common IDEs. When a project is created following the recommended directory structure, executing the following interactive CLI commands will build a Scala application: +``` +$ sbt +> clean +> compile +``` + +## Deploying Scala Applications {#deployment data-title="Deploying Scala Applications"} + +Scala applications are packaged the same way as Java applications (e.g., JAR, WAR, or EAR files). This means they can be deployed in exactly the same way as any other Java application (refer to the [Deploying Java Applications](/docs/buildmaster/platforms/java#deployment) documentation to see a list of deployment methods). + +## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"} + +The automated process is the same as the manual process above, except that commands should be run in "batch mode" to prevent prompts for user input. Batch mode is executed by supplying arguments when invoking `sbt` (e.g., `sbt clean compile`). + +Example OtterScript plan: +``` +Git::Get-Source +( + RepositoryUrl: https://github.com/Inedo/ProfitCalcScala.git, + Branch: master +); + +Exec +( + FileName: sbt, + Arguments: clean compile +); + +Create-Artifact ProfitCalcScala +( + From: ProfitCalcScala\target +); +``` diff --git a/BuildMaster/platforms/java/tomcat.md b/BuildMaster/platforms/java/tomcat.md new file mode 100644 index 00000000..469525eb --- /dev/null +++ b/BuildMaster/platforms/java/tomcat.md @@ -0,0 +1,55 @@ +--- +title: Tomcat +subtitle: Deploying Java Applications to Tomcat +sequence: 300 +show-headings-in-nav: true +--- + +[Apache Tomcat](https://tomcat.apache.org/) is the most popular web server environment used to run Java web applications. + +The project includes open-source implementations of Jakarta EE functionality such as servlets, Java Server Pages (JSP), and more. When hosting your application using Tomcat, your Java web application's target output needs to generate a WAR file. Most Java IDEs include templates (e.g., Maven archetypes) that create the necessary project structure to build and deploy a web application. + +## Overview & Concepts {#overview data-title="Tomcat Overview"} + +Tomcat runs on both Windows and Linux, and it includes certain functionality for both. + +On Windows, Tomcat can run as a console application and is controllable by batch scripts (e.g., `%CATALINA_HOME%\bin\startup.bat`) or can be hosted as a Windows Service and controlled by the Windows Service Control Manager. + +On Linux, it can run as a console application and is controllable by shell scripts (e.g. `$CATALINA_HOME/bin/startup.sh`) or configured on a per-distro basis to run as a daemon where starting/stopping it depends on the `init` script from the package. + +Tomcat internally consists of three major application service components: + +{.docs} + - **Catalina** - Java servlet container + - **Coyote** - HTTP web server + - **Jasper** - JSP engine + +The `$CATALINA_HOME/conf/server.xml` is the configuration file for the initial startup port for the web server and individual `` elements that contain information about each hosted web application. + +## Deploying Java Web Applications to Tomcat {#deployment data-title="Deployment"} + +By default, applications are packaged as WAR files and deployed to the `$CATALINA_HOME\webapps` directory. The general process involves: + +{.docs} + - stopping the Tomcat server: `$CATALINA_HOME/bin/shutdown.sh` + - deploy WAR file to `$CATALINA_HOME\webapps` directory + - starting the Tomcat server: `$CATALINA_HOME/bin/startup.sh` + +## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"} + +The process for automating Tomcat with BuildMaster follows the same pattern as the manual process. + +Example OtterScript plan: +``` +set $CATALINA_HOME = $EnvironmentVariable(CATALINA_HOME); + +Exec $PathCombine($CATALINA_HOME, bin, shutdown.sh); # .bat on Windows + +# the ProfitCalcJava artifact contains org.inedo.profitcalc-1.2.3.war +Deploy-Artifact ProfitCalcJava +( + To: $PathCombine($CATALINA_HOME, webapps) +); + +Exec $PathCombine($CATALINA_HOME, bin, startup.sh); # .bat on Windows +``` diff --git a/BuildMaster/platforms/java/wildfly.md b/BuildMaster/platforms/java/wildfly.md new file mode 100644 index 00000000..c9d0efc9 --- /dev/null +++ b/BuildMaster/platforms/java/wildfly.md @@ -0,0 +1,57 @@ +--- +title: WildFly +subtitle: Deploying Java Applications to WildFly/JBoss EAP +sequence: 400 +show-headings-in-nav: true +--- + +[WildFly](https://wildfly.org), formerly JBoss Application Server, is a free application runtime used to run Java web applications. Built on WildFly, [JBoss Enterprise Application Platform (EAP)](https://www.redhat.com/en/technologies/jboss-middleware/application-platform) is a paid enterprise application runtime that includes open-source implementations of Jakarta EE functionality (e.g., servlets, Java Server Pages (JSP), and more). Both WildFly and JBoss EAP are commonly referred to as JBoss. + +As with other Java application servers, your Java web application's target output needs to generate a WAR file. Most Java IDEs include templates (e.g., Maven archetypes) that create the necessary project structure to build and deploy a web application. JBoss refers to these WAR files as "modules." + +## Overview & Concepts {#overview data-title="WildFly Overview"} + +WildFly can be run in `standalone` or `domain` mode. The features are the same for both; the only difference is server management. + +{.docs} +- On Windows, WildFly can run as a console application and is controllable by batch scripts (e.g. `%JBOSS_HOME%\bin\standalone.bat` or `%JBOSS_HOME%\bin\domain.bat`) or can be hosted as a Windows Service and controlled by the Windows Service Control Manager +- On Linux, it can run as a console application and is controllable by shell scripts (e.g. `$JBOSS_HOME/bin/standalone.sh` or `$JBOSS_HOME/bin/domain.sh`) or configured on a per-distro basis to run as a daemon where starting/stopping it depends on the `init` script from the package. + +You can customize what modules and configurations are used by the server by modifying the configuration files found in `%JBOSS_HOME%\standalone\configuration` or `%JBOSS_HOME%\domain\configuration`. You can also pass a configuration file as a parameter to the startup script: + +{.docs} +- Standalone: `--server-config` +- Domain: `--domain-config` + +WildFly includes a web-based management console out-of-the-box, but it can also be maintained via the [command line](https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-CommandLineInterface). + +## Deploying Java Web Applications to WildFly {#deployment data-title="Deployment"} + +To deploy applications to WildFly, you'll typically use the Web Admin Console or the Admin Console CLI. To deploy to using the CLI, you would first connect to the WildFly server, then run the deploy command: + +``` +%JBOSS_HOME%\bin\jboss-cli.bat --connect 192.168.0.100 --commands="deploy ProfitCalcJava.ear" +``` + +You also have the option to specify a server list with the `--server-groups` parameter. + +## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"} + +Automating WildFly with BuildMaster follows the same pattern as the manual process. + +Example OtterScript plan: +``` +set $JBOSS_HOME = $EnvironmentVariable(JBOSS_HOME); + +# the ProfitCalcJava artifact contains org.inedo.profitcalc-1.2.3.war +Deploy-Artifact ProfitCalcJava +( + To: $WorkingDirectory +); + +Exec +{ + Path: PathCombine($JBOSS_HOME, bin, jboss-cli.sh) + Arguments: --connect 192.168.0.100 --commands="deploy org.inedo.profitcalc-1.2.3.war" +}; # .bat on Windows +``` diff --git a/BuildMaster/redirects.xml b/BuildMaster/redirects.xml index 2d3b7346..c1bb1c86 100644 --- a/BuildMaster/redirects.xml +++ b/BuildMaster/redirects.xml @@ -156,6 +156,7 @@ - + +