Getting started with Weld

Weld comes with a number of examples. We recommend you start with examples/jsf/numberguess and examples/jsf/translator. Numberguess is a web (war) example containing only non-transactional managed beans. This example can be run on a wide range of servers, including WildFly, GlassFish, Apache Tomcat, Jetty, and any compliant Jakarta EE 10 container. Translator is an enterprise (ear) example that contains session beans. This example must be run on WildFly 27 or better, GlassFish 7 or better, or any compliant Jakarta EE 10 container.

Both examples use JSF 4.0.0 as the web framework and, as such, can be found in the examples/jsf directory of the Weld distribution.


To run the examples with the provided build scripts, you’ll need the following:

  • the latest release of Weld, which contains the examples

  • Maven 3, to build and deploy the examples

  • optionally, a supported runtime environment (minimum versions shown)

    • WildFly 27,

    • GlassFish 7 or better,

    • Apache Tomcat 10.1 or better (war example only), or

    • Jetty 11 or better (war example only)

In the next few sections, you’ll be using the Maven command (mvn) to invoke the Maven project file in each example to compile, assemble and deploy the example to WildFly and, for the war example, Apache Tomcat. You can also deploy the generated artifact (war or ear) to any other container that supports Jakarta EE 10, such as GlassFish 7.

The sections below cover the steps for deploying with Maven in detail.

First try

If you simply want to run the numberguess example without the requirement of a specific runtime you can start with the following commands:

$> cd examples/jsf/numberguess
$> mvn wildfly:run

The Maven WildFly plugin will run WildFly and deploy the example and the server will be automatically downloaded in the target directory. The numberguess application is available at http://localhost:8080/weld-numberguess.

Deploying to WildFly

To deploy the examples to a WildFly instance, you’ll need to download WildFly first. The good news is that there are no additional modifications you have to make to the server. It’s ready to go!

After you have downloaded WildFly, extract it. You can move the extracted folder anywhere you like. Wherever it lays to rest, that’s what we’ll call the WildFly installation directory, or JBOSS_HOME.

$> unzip
$> mv wildfly-27.*/ wildfly-27

In order for the build scripts to know where to deploy the example, you have to tell them where to find your WildFly installation. Set the JBOSS_HOME environment variable to point to the WildFly installation, e.g.:

$> export JBOSS_HOME=/path/to/wildfly-27

You’re now ready to run your first example!

Switch to the examples/jsf/numberguess directory and execute the Maven deploy target:

$> cd examples/jsf/numberguess
$> mvn wildfly:deploy
If you are using Eclipse, you should seriously consider installing the JBoss Tools add-ons, which include a wide variety of tooling for CDI and Jakarta EE development, as well as an enhanced WildFly server view.

Wait a few seconds for the application to deploy (or the application server to start) and see if you can determine the most efficient approach to pinpoint the random number at the local URL http://localhost:8080/weld-numberguess.


The Maven WildFly plugin includes additional goals for WildFly to deploy and undeploy the archive.

  • mvn wildfly:deploy - deploy the example to a running WildFly instance

  • mvn wildfly:undeploy - undeploy the example from a running WildFly instance

  • mvn wildfly:redeploy - redeploys the example

For more information on the WildFly Maven plugin see the plugin documentation.

You can also run functional tests to verify that the example works as expected. Run:

$> mvn verify -Darquillian=wildfly-managed

You should see the following output:

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

The second starter example, weld-translator, will translate your text into Latin. (Well, not really, but the stub is there for you to implement, at least. Good luck!) To try it out, switch to the translator example directory and execute the deploy target:

$> cd examples/jsf/translator/ear
$> mvn wildfly:run
The translator uses session beans, which are packaged in an EJB module within an ear. Java EE 8 allows session beans to be deployed in war modules, but that’s a topic for a later chapter.

Again, wait a few seconds for the application to deploy (if you’re really bored, read the log messages), and visit http://localhost:8080/weld-translator to begin pseudo-translating.

Again, functional tests can be running by executing:

$> cd examples/jsf/translator/ftest
$> mvn verify -Darquillian=wildfly-managed

Deploying to GlassFish

Deploying to GlassFish should be easy and familiar, right? After all, it’s the Jakarta EE compatible implementation and Weld is the CDI compatible implementation, meaning Weld gets bundled with GlassFish. So yes, it’s all quite easy and familiar.

To deploy the examples to GlassFish, you’ll need a GlassFish 7 release. Extract the zip to a directory of your choice and set the GLASSFISH_HOME environment variable. Switch to the GLASSFISH_HOME directory and start the server:

$> ./bin/asadmin start-domain

Now you can deploy the example.

$> ./bin/asadmin deploy /path/examples/jsf/numberguess/target/weld-numberguess.war

Once the command completes the application is available at http://localhost:8080/weld-numberguess

The reason the same artifact can be deployed to both WildFly and GlassFish, without any modifications, is because all of the features being used are part of the standard platform. And what a capable platform it has become!

Deploying to Apache Tomcat

Servlet containers are not required to support Jakarta EE services like CDI. However, you can use CDI in a servlet container like Tomcat by embedding a standalone CDI implementation such as Weld.

Weld comes with servlet integration extension which bootstraps the CDI environment and provides injection into servlets components. Basically, it emulates some of the work done by the Jakarta EE container, but you don’t get the enterprise features such as session beans and container-managed transactions.

Note that due to limitations of servlet containers (e.g. read-only JNDI) your application might require some additional configuration as well (see Tomcat and Jetty for more info).

Let’s give the Weld servlet extension a spin on Apache Tomcat. First, you’ll need to download Tomcat 10.1 or later from and extract it.

$> unzip

The Maven plugin communicates with Tomcat over HTTP, so it doesn’t care where you have installed Tomcat. However, the plugin configuration assumes you are running Tomcat in its default configuration, with a hostname of localhost and port 8080. The readme.txt file in the example directory has information about how to modify the Maven settings to accommodate a different setup.

You can either start Tomcat from a Linux shell:

$> cd /path/to/apache-tomcat-10.1
$> ./bin/

a Windows command window:

$> cd c:\path\to\apache-tomcat-9\bin
$> start

or you can start the server using an IDE, like Eclipse.

Change to the examples/jsf/numberguess directory again and run the following Maven command:

$> cd examples/jsf/numberguess
$> mvn clean package -Ptomcat

Now you’re ready to deploy the numberguess example to Tomcat!

$> cp examples/jsf/numberguess/target/weld-numberguess.war apache-tomcat/webapps/