Introduction

Spring Boot WebSocket support can run on WildFly, but the deployment model is different from the usual embedded-server setup. When deploying to WildFly, you typically package the application as a WAR, let WildFly provide the servlet container, and make sure your WebSocket configuration fits that external-container model.

Use a WAR Instead of the Usual Executable JAR

For WildFly deployment, the application is commonly packaged as a WAR.

Your main application class should extend SpringBootServletInitializer.

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3import org.springframework.boot.builder.SpringApplicationBuilder;
4import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
5
6@SpringBootApplication
7public class Application extends SpringBootServletInitializer {
8
9    @Override
10    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
11        return application.sources(Application.class);
12    }
13
14    public static void main(String[] args) {
15        SpringApplication.run(Application.class, args);
16    }
17}

This lets the app run as a WAR in WildFly while still being launchable in development if needed.

Dependency Setup Matters

When deploying to WildFly, the embedded Tomcat starter should not be packaged as a normal runtime dependency.

In Maven, that usually means marking it as provided.

1<packaging>war</packaging>
2
3<dependencies>
4    <dependency>
5        <groupId>org.springframework.boot</groupId>
6        <artifactId>spring-boot-starter-websocket</artifactId>
7    </dependency>
8    <dependency>
9        <groupId>org.springframework.boot</groupId>
10        <artifactId>spring-boot-starter-tomcat</artifactId>
11        <scope>provided</scope>
12    </dependency>
13</dependencies>

That prevents conflicts between the embedded container and WildFly's container services.

A Simple WebSocket Configuration

For Spring's STOMP-based messaging support, a standard configuration looks like this:

1import org.springframework.context.annotation.Configuration;
2import org.springframework.messaging.simp.config.MessageBrokerRegistry;
3import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
4import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
5import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;
6
7@Configuration
8@EnableWebSocketMessageBroker
9public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
10
11    @Override
12    public void configureMessageBroker(MessageBrokerRegistry registry) {
13        registry.enableSimpleBroker("/topic");
14        registry.setApplicationDestinationPrefixes("/app");
15    }
16
17    @Override
18    public void registerStompEndpoints(StompEndpointRegistry registry) {
19        registry.addEndpoint("/ws").setAllowedOriginPatterns("*");
20    }
21}

This works the same conceptually whether the app runs with embedded Boot or inside WildFly.

Deploying to WildFly

Package the application and copy the WAR to WildFly's deployment directory.

mvn clean package
cp target/app.war $WILDFLY_HOME/standalone/deployments/

Then verify startup logs and confirm the WebSocket endpoint is exposed under the deployed application context path.

Watch for Container Conflicts

WildFly already provides Java EE or Jakarta EE infrastructure. Spring Boot can live inside that environment, but conflicts can appear if you accidentally package embedded-container pieces or rely on incompatible servlet APIs.

The safest approach is:

• package as WAR
• use container-provided servlet runtime
• keep dependency versions aligned with the target platform

Testing the Endpoint

A minimal JavaScript client can verify connectivity.

const socket = new WebSocket("ws://localhost:8080/app/ws");
socket.onopen = () => console.log("connected");
socket.onerror = (e) => console.error(e);

Adjust the path to match your actual deployment context and endpoint mapping.

Security and Proxy Considerations

If WildFly sits behind a reverse proxy or load balancer, make sure WebSocket upgrade headers are forwarded correctly. A perfectly valid Spring configuration can still fail if the proxy strips or mishandles the upgrade request.

That means deployment debugging sometimes belongs at the HTTP or infrastructure layer, not only inside Spring Boot or WildFly itself.

Common Pitfalls

A common mistake is deploying a default Boot executable JAR to WildFly expectations. For WildFly, WAR packaging is usually the right model.

Another mistake is leaving the embedded Tomcat dependency as a normal runtime dependency, which can create classpath or container conflicts.

Developers also often forget that the WebSocket URL includes the deployed application context path, not just the endpoint path from the Spring config.

Summary

• Spring Boot WebSockets can run in WildFly, but the app is usually packaged as a WAR.
• Extend SpringBootServletInitializer for external-container deployment.
• Mark embedded Tomcat as provided when deploying to WildFly.
• Configure WebSocket endpoints normally through Spring.
• Check deployment context paths and container classpath conflicts when debugging.