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>
    <version>3.15.1</version>
</dependency>

dependencies {
    compile("org.seedstack.seed:seed-web-core:3.15.1")
}

External servlet container

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

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>
    <version>3.15.1</version>
</dependency>

dependencies {
    compile("org.seedstack.seed:seed-web-undertow:3.15.1")
}

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)

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.

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

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)