How to set the Web Context Path in WildFly

This article shows you every way to change the Web Context Path for applications running on WildFly or JBoss EAP: by editing jboss-web.xml in a WAR, by editing application.xml in an EAR, by changing the deployment's runtime-name from the CLI without touching the archive, or by overlaying a new descriptor onto an application that's already deployed.

Context Path defaults

Firstly, by default, a Web application inherits the Web Context Path from its name. Therefore, a Web application whose name is helloworld.war, will be available under the http://localhost:8080/helloworld Context Path

If you are using Maven to build your project, the final application name is determined by the artifactid. However, you can override it through the finalName element of the build section:

<build>
      <finalName>${project.artifactId}</finalName>
      <!-- -->
</build>

Changing finalName works, but it means renaming the artifact itself. If you just want to control the context path without renaming your build output, use one of the methods below instead.

Quick comparison: which method should you use?

Method 1: jboss-web.xml (WAR deployments)

The recommended option to set a non-default Context name for a Web application is to add the jboss-web.xml in the WEB-INF folder of your Web application:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="
      http://www.jboss.com/xml/ns/javaee
      http://www.jboss.org/j2ee/schema/jboss-web_14_0.xsd"
   version="14.0">
   <context-root>/myapp</context-root>
</jboss-web>

There, you can choose the Web application context through the context-root element as you can see from the above example. The jboss-web_14_0.xsd schema shown here matches recent WildFly releases; if you want to pin the exact version your server ships with, check the docs/schema folder of your WildFly distribution — the version attribute on the root element is what actually matters, the schema location is only used for validation in your IDE.

Method 2: application.xml (EAR deployments)

If you are packaging your Web application in an EAR file, another option is to use the context-root element from the application.xml file. Note that EAR-based packaging is legacy at this point — most new WildFly/Jakarta EE projects deploy plain WARs, so reach for this only if you're maintaining an existing EAR-based application:

<application xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                         https://jakarta.ee/xml/ns/jakartaee/application_10.xsd"
    version="10">
    <display-name>JBossDukesBank</display-name>

    <module>
        <ejb>example.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>webapp.war</web-uri>
            <context-root>myapp</context-root>
        </web>
    </module>

</application>

This replaces the old http://java.sun.com/xml/ns/j2ee / application_1_4.xsd descriptor with the current Jakarta EE namespace and the application_10.xsd schema, which is what a modern WildFly (Jakarta EE 10/11) expects.

Method 3: Changing runtime-name via the CLI (no rebuild)

If you deploy through the management CLI or through scripts, you don't need a descriptor at all: the context root of a WAR is derived from its runtime-name, not from the --name you give the deployment. So you can deploy the same archive under a different context without ever touching jboss-web.xml:

deploy /path/to/helloworld.war --name=helloworld --runtime-name=myapp.war

This deploys helloworld.war so that it's reachable at http://localhost:8080/myapp, while the management name shown in the console/CLI stays helloworld. It's the fastest way to test a different context path without a rebuild, and it composes well with CI/CD pipelines where you don't want to bake environment-specific paths into the artifact.

Method 4: Changing the Web Context of an already-deployed application

Finally, it's possible to change the Web context of a Web application that's already deployed by using a CLI hack based on Deployment Overlays. Follow these steps:

1. Create a file jboss-web.xml with the Web Context. In our example, we will place it in the /tmp folder
2. Connect to the CLI (jboss-cli.sh)

Once connected, apply the new Web Context using the Deployments Overlay feature:

deployment-overlay add --name=myOverlay --content=/WEB-INF/jboss-web.xml=/tmp/jboss-web.xml --deployments=helloworld.war --redeploy-affected

In this example, the affected deployment is helloworld.war. You can apply the change to multiple applications, even using a regular expression such as “*”. See this example:

deployment-overlay add --name=myOverlay --content=/WEB-INF/jboss-web.xml=/tmp/jboss-web.xml --deployments=helloworld.war,*-admin.war --redeploy-affected

To learn more about deployments overlay, check this article: How to add a web fragment to all applications deployed on WildFly

Finally, if you want to set as Web Context the Root Web Context (“/”) check this tutorial: How to deploy a Web application on the Root Context on WildFly?

FAQ

My context-root change isn't taking effect. Why?
The most common cause is a stale deployment: WildFly caches deployment metadata, so a plain re-copy of the WAR into deployments/ without a real redeploy (or without --force from the CLI) can leave the old context active. Also double check you didn't set context-root in both jboss-web.xml and application.xml — when both are present, the EAR's application.xml wins.

Does context-root work the same way in JBoss EAP as in WildFly?
Yes — EAP is built on the same codebase, only the jboss-web_*.xsd schema version you reference should match what your EAP release ships with, which you'll find under its own docs/schema directory.

Can I set the context root without any descriptor at all?
Yes, if you control how the app is deployed: either rename the artifact via Maven's finalName (Method 0 above), or set --runtime-name at deploy time via the CLI (Method 3) — both avoid adding an XML descriptor.