Skip to content

Toro Cloud Dev Center


HTTP and HTTPS ports

Martini ships with Tomcat1, which is used to process HTTP and HTTPS requests. With the help of instance properties, you can configure certain parts of Tomcat in Martini.

This section will discuss how to configure Tomcat's underlying HTTP and HTTPS connectors. Out-of-the-box, Martini uses an HTTP connector only. But if you find your APIs handling sensitive data and you can't configure a secure proxy server in front of your instance (which is recommended), you can opt to use the HTTPS connector using the guide below.

Configuring the HTTP port

By default, Martini creates and uses a plain, non-secure HTTP connector at port 8080. You can easily change the port number by setting the value of the server.http.port instance property to any other number between 80 and 65535. To disable the HTTP connector, set this property's value to -1.

Configuring the HTTPS port

Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL), are cryptographic protocols that provide communications security over a computer network. They are the technologies that allow web browsers and web servers to communicate over a secure connection. This process means that the web browser and the web server encrypt all traffic before sending it.

In Tomcat, there are two different implementations of SSL/TLS; they are the Java Secure Socket Extension (JSSE) implementation and the Apache Portable Runtime (APR) implementation. Both implementations are available in Martini.

It's important to note that enabling the HTTPS port is only necessary if you're going to run Martini as a stand-alone web server. If you have another web server in front of your Martini instance, it's better to let that web server do all the SSL processing.

JSSE implementation

Martini uses the JSSE implementation by default. JSSE uses a Java KeyStore to store the private key and the certificate itself. You have to generate a Java KeyStore from your keys and certificate and configure Martini so it knows where the keystore is located.

To enable HTTPS with JSSE, you must set the following properties:

  • server.https.port

    The HTTPS port number to be used. Must be any number between 80 and 65535.

  • server.tomcat.https.keystoreFile

    The location of your Java KeyStore (JKS) file. If you've set this property value to a relative path, it will try to find the JKS file within the tmp directory, located within Martini's home folder.

    1
    2
    3
    4
    5
    <home>
    ├── ...
    ├── solr
    ├── tmp
    ├── web
    
  • server.tomcat.https.keystorePass

    The password of the JKS file.

With HTTPS enabled, your .properties file should contain something like this:

1
2
3
server.https.port=8443
server.tomcat.https.keystoreFile=martini.keystore
server.tomcat.https.keystorePass=AN3HeVoLybR6S89Eg7

APR Implementation

If you have decided to use the APR protocol instead, you only need to configure the location of your SSL certificate and SSL key.

The following properties should be configured to enable HTTPS using the APR protocol:

  • server.https.port

    The HTTPS port number to be used. Must be any number between 80 and 65535.

  • server.tomcat.https.protocol

    Set the value of this property to org.apache.coyote.http11.Http11AprProtocol to tell Martini to use the APR library.

  • server.tomcat.https.SSLCertificateFile

    The value of this property should be the path of the SSL certificate.

  • server.tomcat.https.SSLCertificateKeyFile

    Set the value of this property to the path of the SSL key.

With HTTPS enabled, your .properties file should contain something like this:

1
2
3
4
server.tomcat.https.protocol=org.apache.coyote.http11.Http11AprProtocol
server.https.port=8443
server.tomcat.https.SSLCertificateFile=/usr/local/ssl/server.crt
server.tomcat.https.SSLCertificateKeyFile=/usr/local/ssl/server.pem

Storing SSL certificates

It is not recommended to store your SSL certificates in <martini-home>. Store your SSL certificates in another location so that they won't be accidentally deleted when upgrading Martini to the latest version.

Configuring HSTS

In addition to enabling HTTPS, Martini can also be configured to use HTTP Strict Transport Security (HSTS) for protection against downgrade attacks.

Enabling HSTS will inject a header field named Strict-Transport-Security to your server's responses. Once your user agent receives a response with that header, all succeeding requests will automatically be converted from HTTP to HTTPS. This feature will prevent man-in-the-middle attacks.

To enable this feature, simply configure the following instance properties:

  • hsts.enabled

    Set to true to let Martini inject the Strict-Transport-Security header.

  • hsts.include-subdomains

    Set to true if all present and future sub-domains will be using HTTPS.

  • hsts.preload

    Set to true if the site owner would like their domain to be included in the HSTS preload list maintained by Chrome (and used by Firefox and Safari).

  • hsts.max-age

    The maximum time, in seconds, that a site is only to be accessed using HTTPS.

Here's an example configuration:

1
2
3
4
hsts.enabled=true
hsts.include-subdomains=false
hsts.preload=false
hsts.max-age=31536000

Startup log messages

Once your instance has launched, Martini will print log messages2 telling you which protocols and ports were configured. Below are some examples:

With only the HTTP connector enabled:

1
**** Martini awaiting requests, console available on port 8080 ****

With only the HTTPS connector enabled:

1
**** Martini awaiting requests, console available on https port 8443 ****

Both HTTP and HTTPS connectors enabled:

1
**** Martini awaiting requests, console available on port 80 and https port 443 ****

  1. Tomcat's version depends on the Martini version you're running; it gets updated on a regular basis between releases. 

  2. Provided you have not turned off the logger io.toro.martini.core.launch.Main