Running Web Applications

The seed-web-core and its companion modules provide support for Web technologies, such as Servlets, WebSockets, embedded Web servers, serving static resources, etc…

A SeedStack Web application requires the following dependency in your project:

<dependency>
    <groupId>org.seedstack.seed</groupId>
    <artifactId>seed-web-core</artifactId>
</dependency>
Show version
dependencies {
    compile("org.seedstack.seed:seed-web-core:3.14.0")
}

External servlet container

You can choose to run your Web application in an external Servlet 3+ container like Apache Tomcat.

To run in an external container, the seed-web-undertow dependency must be NOT be present in the classpath and the application must be packaged as a WAR.

Undertow embedded server

SeedStack Web applications run well with the embedded Undertow Web server. To add support for Undertow in your application, add the following dependency:

<dependency>
    <groupId>org.seedstack.seed</groupId>
    <artifactId>seed-web-undertow</artifactId>
</dependency>
Show version
dependencies {
    compile("org.seedstack.seed:seed-web-undertow:3.14.0")
}

This dependency provides a SeedLauncher implementation that handles the creation, configuration, startup and shutdown of the server.

An application configured with the Undertow Web server can be packaged as a capsule that can be run directly as an executable JAR.

Configuration

The embedded server can be configured with the following options:

web:
  server:
    # The host on which the server will be listening (0.0.0.0 by default)
    host: (String)
    
    # The port on which the server will be listening (8080 by default)
    port: (int)
    
    # The base context path of the application (/ by default)
    contextPath: (String)
    
    # If true, HTTP/2 will be enabled (true by default)
    http2: (boolean)
    
    # If true, HTTPS will be enabled (false by default)
    https: (boolean)
    
    # The welcome files served by default by the server (index.html by default)
    welcomeFiles: (List<String>)
    
    # The part below is specific to the Undertow implementation
    undertow:
      # The size of Undertow buffers
      bufferSize: (Integer)
      
      # The number of Undertow I/O threads
      ioThreads: (Integer)
      
      # The number of Undertow worker threads
      workerThreads: (Integer)
      
      # If true, direct buffers are used
      directBuffers: (Boolean)

To dump the web.server configuration options:

mvn -q -Dargs="web.server" seedstack:config

Undertow handlers support

A undertow-handlers.conf file can be specified, allowing to declare a sequence of any Undertow built-in handler. Its default location is at the root of the classpath (for instance in src/main/resources), but can be configured with the web.server.undertow.handlersFile option.

The file is a collection declarations following the textual representation of predicated handlers.

HTTPS

To configure Undertow for HTTPS, you need to have a Java keystore containing your server certificate. By default an SSL context will be built using the ssl alias in the master keystore:

crypto:
  keystores:
    master:
      path: path/to/your/keystore.jks
      password: keystorePassword
      aliases:
        ssl: aliasPassword

If you want to have alternative keystore or alias names, you can change them in the global SSL configuration.

After successful keystore configuration, you only need to enable HTTPS in the Undertow configuration:

web:
  server:
    https: true

Mutual authentication

If you want to enable mutual authentication (where the HTTPS user-agent sends a client certificate), set crypto.ssl.clientAuthMode:

crypto:
  ssl:
    clientAuthMode: REQUIRED

With that configuration, the user-agent will be required to send a client certificate for authentication.

Runtime information

When running a Web application, servlet information is available in the runtime.web.servlet special configuration tree:

runtime:
  web:
    servlet:
      # The context path of the servlet container
      contextPath: (String)
        
      # The virtual server name of the servlet container if available
      virtualServerName: (String)

When running with Undertow, additional information is also available:

runtime:
  web:
    # The base url of the Web application (protocol + host + port + context path) without a trailing slash
    baseUrl: (String)

    # Same as baseUrl but with a trailing slash
    baseUrlSlash: (String)

    server:
      # The protocol used by the Web server
      protocol: (String)
    
      # The host used by the Web server
      host: (String)
    
      # The port used by the Web server
      port: (int)

These values are not meant to be specified by the developer but are provided by SeedStack at runtime. If you specify a value for those in a configuration file, it will be overridden by runtime information.

   

On this page


Edit