A fully featured application server built for boilerplate-less Vert.x web applications
To obtain a pre-compiled release of Twine, check the releases tab. To compile, download the source from the releases tab or clone the repository for the latest development version, then follow the Building guide.
Before building, be sure you have at least JDK 8 and Gradle installed.
To build on Unix/Unix-like systems (Darwin, Linux, BSD) run
./gradlew build and on Windows run
The compiled executable will be in
To start Twine, execute the jar with the
-s option. This will generate all necessary configuration files and start the server. Once you start the server for the first time, terminate it and then observe the directory you executed in. Now you may proceed to the Configuration guide.
A Note About Starting Twine
When starting Twine with
-s, Twine will automatically create a new process with the proper JVM options to load dependencies from the
dependencies/ directory, and load module classes from the
modules/ directory. To avoid creating a new process, start the server using either
start.bat (found in this repository, or in the releases tab).
All configuration for Twine is done through a file named
The file itself is documented, and as such there isn't very much to go over here.
Opening the file will explain it in depth.
If you need to programmatically configure Twine, you can modify
twine.yml options through command line options and environment variables.
To configure with command line options, you can specify values with the
--config=NODE:VALUE option. So to set the port to 8080, you could specify
--config options can be used to configure as many values as you want.
To configure with environment variables, you must create variables beginning with
TW_CONF_, followed by the config node. So to set the port to 8080 using environment variables, you can have a variable with the following value:
TW_CONF_server_port=8080. These variables are case-sensitive, so keep that in mind when configuring with them.
_ is equivalent to
. in nodes specified with environment variables, making
server_port equivalent to
The priority for
twine.yml configurations is as follows: command line options > environment variables >
To enable HTTPS on your server, you'll need a JKS formatted keystore and a few adjustments to your
twine.yml file. To generate a JKS keystore, you will need a valid certificate from an organization like LetsEncrypt. Once you have a certificate file, you'll need to package it into a
.jks keystore with either Java's Keytool, or Keytool-Explorer (a GUI for keytool).
Once you've got a JKS format keystore, you'll need to set
server.https.keystore to the path of your JKS keystore, and set
server.https.keystorePassword to the keystore's password.
If you would like to redirect insecure HTTP traffic to the HTTPS version of your server, you can set that up by setting
server.https.redirect.enable to true, and
server.https.redirect.port to the port you would like the redirection server to run on. By default it is set to
To deploy a module jar, simply add it to the
modules/ directory, and start the server.
Module dependencies may be placed in the
This can be useful for sharing dependency jars between multiple modules, but is not necessary if module jars self-contain all of their dependencies.
It is recommended for modules to use dependency shading to avoid conflicts.
Sometimes you'll want to cluster several Twine instances, be it between servers, or on the same machine for various purposes such as data sharing and EventBus communication.
To cluster instances, you'll need an Apache Zookeeper server.
Enabling clustering is done by setting
From there, you need to configure the rest of the settings in
vertx.cluster to match settings for your Zookeeper server.
Running Twine Behind A Reverse Proxy
If you are running Twine behind a reverse proxy such as Nginx, you should make sure
server.respectXFF is set to
twine.yml, and that
Host headers are being sent by the reverse proxy.