Server Settings - WebSocket

Configure WebSocket server settings

Overview

The WebSocket Settings page configures ColdFusion's WebSocket server for real-time, bidirectional communication between the server and browser clients. WebSockets enable push notifications, live chat applications, real-time dashboards, collaborative editing, and other interactive features that require instant data updates without polling.

ColdFusion's WebSocket implementation provides a high-performance, scalable solution for real-time communication with built-in support for channels, message broadcasting, authentication, and SSL/TLS encryption.

WebSocket Configuration Settings

Configure server mode, ports, timeouts, and SSL settings for WebSocket communication.

Server Status

Enable WebSocket Server

PurposeEnable/disable WebSocket functionality
DefaultEnabled in the default profile; disabled when the Secure Profile is applied (Source)
RecommendationEnable if your application requires real-time communication
Note: Restart ColdFusion after changing WebSocket settings (Source). Verify firewall allows connections on the configured port.

Use WebSocket Proxy Port / Built-in WebSocket Server

PurposeChoose how WebSocket traffic reaches ColdFusion
ProxyA proxy module running inside IIS or Apache intercepts ColdFusion WebSocket requests and redirects them to ColdFusion. Set it up with the wsproxyconfig tool in cfusion/bin. Adobe says you must use the proxy when a firewall sits between the browser and ColdFusion.
Built-in ServerClients connect directly to ColdFusion's built-in WebSocket server on the configured port and SSL port

Port

PurposePort that the WebSocket server listens to
Default8585 in the ColdFusion 2025 Update 14 Docker image; check your own Administrator, since installs can differ
RecommendationKeep the value shown in your Administrator unless it conflicts with another service
Important: Ensure firewall and load balancer allow WebSocket traffic on this port.

Enable SSL

PurposeEnables SSL for running WebSocket over SSL (WSS)
DefaultDisabled
RecommendationAlways enable for production
Port and Enable SSL defaults verified in the ColdFusion 2025 Update 14 configuration (neo-websocket.xml, keys port and sslEnabled) shipped in Adobe's official Docker image.
Security: Always use WSS (secure WebSockets) in production to encrypt data transmission and prevent eavesdropping.

SSL Port

PurposePort for secure WebSocket connections
Default8543 per Adobe's documentation; the ColdFusion 2025 Update 14 Docker image ships 8555 (neo-websocket.xml sslport). Check your own Administrator.
RecommendationUse default unless conflict exists

Connection Settings

Socket Timeout

PurposeHow long the WebSocket server keeps a socket open
Best Practice: Implement heartbeat/ping-pong messages to keep active connections alive. Close inactive connections to free resources.

Max Data Size

PurposeData size of packets sent/received
RecommendationKeep messages small for best performance
Performance: Large messages increase memory usage and latency. For large data, consider pagination or chunking.

Start Flash Policy Server

PurposeStarts the Flash cross-domain policy server on port 1243, needed only for Flash fallback when the browser has no native WebSocket support
RecommendationLeave off; current browsers support WebSocket natively

SSL/TLS Settings

KeyStore File Location

PurposePath to SSL certificate keystore
RequirementRequired for SSL
ExampleC:\OpenSSL\bin\keystore.jks (Adobe's example)
Setup: Use Java keytool to create keystore. Ensure ColdFusion has read permissions on the keystore file.

Keystore Password

PurposePassword for keystore access
RequirementRequired for SSL
Security: Use a strong password and store securely. Do not commit passwords to version control.

Using WebSockets in CFML

Server-Side WebSocket Channel

Declare channels in Application.cfc with this.wschannels. Server-side logic goes in an optional channel listener CFC that extends CFIDE.websocket.ChannelListener and overrides methods such as allowSubscribe, allowPublish, beforePublish, canSendMessage, beforeSendMessage, and afterUnsubscribe. There are no onOpen, onMessage, or onClose server-side handlers.

WebSocket Channel and Listener
// Application.cfc
component {
  this.name = "wsDemo";
  this.wschannels = [{name: "myChannel", cfclistener: "MyChannelListener"}];
}

// MyChannelListener.cfc
component extends="CFIDE.websocket.ChannelListener" {

  // Decide whether a client may subscribe to the channel
  public boolean function allowSubscribe(struct subscriberInfo) {
    return true; // add your authorization check here
  }

  // Inspect or modify a message before it is published
  public any function beforePublish(any message, struct publisherInfo) {
    return arguments.message;
  }

}
<!--- MyChannelListener.cfc (declare the channel in Application.cfc with this.wschannels) --->
<cfcomponent extends="CFIDE.websocket.ChannelListener">

  <cffunction name="allowSubscribe" returntype="boolean">
    <cfargument name="subscriberInfo" type="struct">
    <cfreturn true>
  </cffunction>

  <cffunction name="beforePublish" returntype="any">
    <cfargument name="message" type="any">
    <cfargument name="publisherInfo" type="struct">
    <cfreturn arguments.message>
  </cffunction>

</cfcomponent>

Client-Side JavaScript

Clients connect through the cfwebsocket tag, which generates a JavaScript object with methods such as subscribe, publish, and invoke. A raw browser WebSocket pointed at a channel URL does not speak ColdFusion's channel protocol.

WebSocket Client Connection
<!--- Creates a JavaScript object named ws and subscribes to myChannel --->
<cfwebsocket name="ws" onMessage="handleMessage" subscribeTo="myChannel">

<script>
  // Called for every message the server sends to this client
  function handleMessage(msg) {
    console.log("Received:", msg);
  }

  // Publish a message to the channel from the browser
  function sendHello() {
    ws.publish("myChannel", "Hello Server!");
  }
</script>

Publishing Messages

Send messages to connected clients:

Publishing to WebSocket Channels
// Publish to all subscribers of a channel
wsPublish("myChannel", {
  type: "notification",
  message: "Server update",
  timestamp: now()
});

// To target specific clients, use subscriber selectors or
// canSendMessage() in the channel listener
<!--- Publish to all subscribers of a channel --->
<cfset wsPublish("myChannel", {
  type: "notification",
  message: "Server update",
  timestamp: now()
})>

<!--- To target specific clients, use subscriber selectors or
      canSendMessage() in the channel listener --->

Managing Connections

Get information about active connections:

Managing WebSocket Connections
// Get all subscribers to a channel
subscribers = wsGetSubscribers("myChannel");

// Get all active channels
channels = wsGetAllChannels();
<!--- Get all subscribers to a channel --->
<cfset subscribers = wsGetSubscribers("myChannel")>

<!--- Get all active channels --->
<cfset channels = wsGetAllChannels()>

WebSocket Use Cases

Real-Time Notifications

  • Push notifications to users instantly
  • Alert users of system events or updates
  • Notify users of new messages or activities
  • Display real-time status updates

Live Chat Applications

  • Instant messaging between users
  • Customer support chat systems
  • Group chat rooms and channels
  • Typing indicators and presence detection

Real-Time Dashboards

  • Live data visualization and charts
  • System monitoring dashboards
  • Stock tickers and financial data
  • Social media feeds and analytics

Collaborative Applications

  • Collaborative document editing
  • Shared whiteboards and drawing tools
  • Multi-user project management
  • Real-time form collaboration

Gaming and Interactive Apps

  • Multiplayer game synchronization
  • Real-time scoring and leaderboards
  • Live polling and voting
  • Interactive quizzes and competitions

Best Practices

Production Configuration

  • Enable SSL/TLS for WebSocket connections in production
  • Use secure (WSS) protocol for sensitive data transmission
  • Set reasonable timeout values to free up idle connections
  • Monitor WebSocket server resource usage
  • Implement connection authentication and authorization

Security

  • Always use WSS (secure WebSockets) in production
  • Implement authentication before allowing channel subscriptions
  • Validate and sanitize all incoming messages
  • Use channel-level access control
  • Rate limit message sending to prevent abuse
  • Log suspicious connection patterns
  • Implement CSRF protection for WebSocket handshake

Performance

  • Keep messages small and efficient
  • Use JSON for structured data transmission
  • Implement message batching for high-frequency updates
  • Close unused connections promptly
  • Monitor memory usage per connection
  • Consider horizontal scaling for high traffic

Error Handling

  • Implement automatic reconnection logic in clients
  • Handle connection failures gracefully
  • Provide fallback mechanisms (long polling, SSE)
  • Log connection errors for debugging
  • Display user-friendly connection status indicators
  • Queue messages during temporary disconnections

Troubleshooting

WebSocket Server Won't Start

If the WebSocket server fails to start:

  • Verify WebSocket is enabled in administrator
  • Check configured port is not already in use
  • Ensure firewall allows connections on WebSocket port
  • Verify SSL keystore configuration if SSL is enabled
  • Review coldfusion-out.log for startup errors
  • Check file permissions on keystore file

Clients Cannot Connect

If clients fail to establish WebSocket connections:

  • Verify WebSocket URL format (ws:// or wss://)
  • Check correct hostname and port are specified
  • Ensure firewall/load balancer allows WebSocket traffic
  • Verify proxy servers support WebSocket protocol
  • Check browser console for connection errors
  • Test with simple WebSocket client tool

Connections Dropping Frequently

If WebSocket connections disconnect often:

  • Increase connection timeout setting
  • Implement heartbeat/ping-pong messages
  • Check network stability and latency
  • Verify proxy/load balancer timeout settings
  • Review server resource usage (CPU, memory)
  • Check for application errors closing connections

Messages Not Being Received

If messages aren't reaching clients:

  • Verify channel names match the names declared in this.wschannels
  • Check client is subscribed to correct channel
  • Confirm connection is still active
  • Review message size against configured limits
  • Check for JavaScript errors in client code
  • Test with simpler message formats

High Memory Usage

If WebSocket server uses excessive memory:

  • Reduce the maximum data size if clients send large messages
  • Implement connection cleanup for idle clients
  • Review application for memory leaks
  • Monitor number of active channels and subscribers
  • Close unused connections programmatically

SSL/TLS Connection Failures

If secure WebSocket connections fail:

  • Verify SSL certificate is valid and not expired
  • Check keystore path and password are correct
  • Ensure certificate matches server hostname
  • Verify client and JVM TLS version compatibility
  • Check for certificate chain issues
  • Test with self-signed certificate first

Advanced Configuration

Load Balancing WebSockets

Scaling WebSocket connections across multiple servers:

  • Configure sticky sessions on load balancer
  • Use ColdFusion Enterprise WebSocket clustering for cross-server messaging
  • Consider proxy mode (Use Proxy) so WebSocket traffic flows through the web server connector
  • Implement session affinity based on connection ID
  • Monitor connection distribution across servers
  • Plan for graceful server shutdowns

Monitoring and Metrics

  • Track active connection count
  • Monitor message throughput (sent/received per second)
  • Measure average connection duration
  • Log connection failures and errors
  • Alert on connection limit thresholds
  • Track memory and CPU usage per connection

Authentication and Authorization

  • Implement token-based authentication
  • Validate user credentials before channel subscription
  • Use session management for connection tracking
  • Implement channel-level permissions
  • Support OAuth or JWT for authentication
  • Log authentication attempts and failures

Performance Tuning

Message Optimization

  • Use compact JSON format for messages
  • Implement message compression for large payloads
  • Batch multiple updates into single messages
  • Use binary format for non-text data
  • Implement delta updates instead of full objects

Related Resources

Server Settings - WebSocket | ColdFusion Administrator | CFGuide