--- title: Documentation layout: default toc: true --- #{page.table_of_contents} ## What is Escalante? Escalante is an application server for [Scala](http://scalan-lang.org), based on the popular [JBoss Application Server 7](http://www.jboss.org/as7). ### Open Source Escalante is a project of the JBoss Community, and is completely open-source software. Escalante is licensed under the [EPL](http://www.eclipse.org/legal/epl-v10.html). You may download the binaries or the source-code, modify it if you desire, and use it, even for profit, without any licensing costs. ## Escalante Installation This section explains how to install Escalante application server step by step: ### Ensure you have Java 6 Escalante requires Java JDK 6. To determine which version, if any, is installed on your system, at a command-line, attempt to run the java command with the -version argument. $ java -version java version "1.6.0_31" Java(TM) SE Runtime Environment (build 1.6.0_31-b04-415-11M3646) Java HotSpot(TM) 64-Bit Server VM (build 20.6-b01-415, mixed mode) If the version is at least 1.6, your version of Java is sufficient. If you have no Java installed, or a version less than 1.6, you'll need to install a Java Development Kit. For many systems, it is easy to install the open-source OpenJDK. For installation on Ubuntu, Fedora, OpenSuse, or Debian, please refer to the installation instructions provided by the OpenJDK project. If you find a java on your system, ensure that it is not actually gcj, as it is insufficient for running the Esclante server. For Apple OSX systems, Apple provides a JDK version 6. ### Download binary distribution You can obtain the latest version of Escalante from the [downloads section](/download). ### Unzip it somewhere handy We'll install Escalante under your user's $HOME directory. $ unzip -q escalante... ### How to run Escalante Running Escalante essentially amounts to running JBoss: $ $ESCALANTE_HOME/bin/standalone.sh ## Escalante for Lift Web Applications If you've never head of Lift, or have never used it, you might wanna check the [FAQ section](/faq) where you can find answers to questions such as: > Q. [What is Lift ?](/faq/#what_is_lift) > Q. [Why develop web applications using Lift ?](/faq/#why_develop_web_applications_using_lift) > Q. [Why deploy Lift applications on Escalante ?](/faq/#why_deploy_lift_applications_on_escalante) Now that you're familiar with Lift, let's see what Escalante provides for Lift developers. Escalante offers the possibility of deploying Lift applications in two different ways. Let's look at the differences between these two deployment modes: ### Optimising Lift applications for Escalante Deploying Lift applications in other servlet engines, or application servers, normally require the application to ship both the Lift and Scala libraries within them, bloating the deployment archive. Lift applications targeted for deployment in Escalante can be configured in such way that they do not require any Lift dependencies to be shipped within the application, and that includes the Scala language libraries too. This vastly reduces the size of your application deployment archive. To give you an idea, the most basic of the Lift examples, the war file for the 'Hello World' example, takes in the region of 30 MB. Without all the jar dependencies, the war file takes a mere 8 KB. So, the question is, how does Escalante know, at deploy time, which dependencies your Lift application needs? Escalante figures out which dependencies your applications needs reading a `META-INF/escalante.yml` file within your deployment archive. This file should be formatted following the [YAML](http://www.yaml.org/) markup language which offers a human-readable way of defining metadata for your application. Here's an example of `META-INF/escalante.yml` configuring all available properties: scala: version: 2.10.1 lift: version: 2.5-RC4 modules: - mapper - jpa This example descriptor is indicating to Escalante that the Lift version that this application needs in 2.5-RC4, and that the Scala version required is 2.10.1. Both `version` attributes are optional in which case, default values are assumed. The default values currently used by Escalante are shown in the example. Once the dependency versions are known, Escalante uses a Maven dependency resolver library to download, if not already present locally, and build the necessary building blocks for your application to access these dependencies. If multiple Lift applications are deployed into Escalante using the method explained above, some of the dependencies can actually be shared between different Lift applications, which results in a further reduction on memory usage. Lift's `modules` attribute defines a list of extra modules that the Lift application requires. These modules essentially translate to Maven Lift artifacts with these coordinates: net.liftweb lift-$_$ $ By default, if no `modules` is given, Escalante brings in the `webkit` module which is the base of any Lift application. There's no limitation to the Scala or Lift versions supported. The only requirement is that they can be resolved using Maven. Lift artifacts are resolved using the coordinates mentioned above. For Scala dependencies, these are resolved from these coordinates: org.scala-lang scala-library $ As a Lift application developer, you will be familiar with the requirement that Lift applications require a `WEB-INF/web.xml` to be included within them in order to define a Lift filter. With Escalante, this is not needed any more. In the absence of a `WEB-INF/web.xml`, Escalante adds one to the deployment archive. If the user application does contain a `WEB-INF/web.xml`, it uses the one already shipped, so this means that the if the user provides a web descriptor, it must contain the Lift filter definition. ### Maven support Lift applications can be created and deployed into Escalante using Maven. By far the best way to find out how to configuration applications to deploy to Escalante using Maven is to inspect the [Escalante Quickstarts](/quickstarts) and use them as starting point. ### SBT support Lift applications can now be created and deployed into Escalante using SBT. Thanks to the [Escalante SBT plugin](http://github.com/escalante/sbt-escalante), `META-INF/escalante.yml` can be generated (if not already present in the source tree) using the build's metadata information, and Lift applications can be deployed to an embedded Escalante instance which does not require a separate process. By far the best way to find out how to configuration applications to deploy to Escalante using SBT is to inspect the [Escalante Quickstarts](/quickstarts) and use them as starting point. ### Standard Lift application support Escalante can also deploy standard Lift applications that have not been optimised. So, if you are already have packaged Lift applications, you can deploy them without problems into Escalante. Bear in mind though that when deploying such applications into Escalante, they must ship all the dependencies required. ### Integration with application server services Lift applications, whether optimised or not, can integrate with services provided by the application server. For example, integration with the default persistence datasource: #### Connecting to datasources Lift applications can connect very easily to the default persistence datasource. To do so, Lift's bootable class, normally located in `bootstrap.liftweb.Boot` needs to be modified to define the default database connection identifier to point to the JNDI name of the example datasource: DefaultConnectionIdentifier.jndiName = "java:jboss/datasources/ExampleDS" ## Escalante for Play Framework 2 Applications [Play Framework](http://www.playframework.com/) is a popular, lightweight, stateless Scala web framework that's build on Akka and enables highly-scalable applications. Check [FAQ section](/faq) for more in depth details about Play Framework. Starting in Escalante `0.3.0`, Play Framework 2.1 Scala web applications can be deployed on top of Escalante natively. The integration is currently limited to deployment of the applications and resolution of Play library dependencies, but in future versions further integrations with the services provided by Escalante will be developed. ### Getting started By far the best way to get started deploying Play 2.x applications on top of Escalante is to have a look at the [Escalante Play Quickstarts](/quickstarts) and use them as starting point. The primary way to deploy Play 2.x applications on top of Escalante is to use [SBT](http://www.scala-sbt.org/), along with the Play and Escalante SBT plugins, in order to build, deploy and run these type of applications. With this in mind, the following system properties should be passed to the `sbt` command in order to configure runtime configuration options: * `-Dhttp.address`: configure HTTP address or host name for the application. Default value is `0.0.0.0`. * `-Dhttp.port`: configure HTTP port for the application. Default value is `9000`. * `-Dhttps.port`: optional SSL port configuration. ### Logging from SBT Logging, when running Escalante on top of SBT, works slightly differently to standalone Play 2.x applications. Instead of defining logging information in either `application.conf`, or providing `application-logger.xml`, in order to fine tune logging settings, you need to pass a `-Djava.util.logging.config.file=` property which points to a logging settings file. A typical JDK logging configuration file would contain: handlers=java.util.logging.FileHandler,java.util.logging.ConsoleHandler .level=INFO io.escalante.level=FINEST org.level=INFO com.level=INFO play.level=FINEST java.util.logging.FileHandler.pattern = %t/escalante-%u.log java.util.logging.FileHandler.count = 1 java.util.logging.FileHandler.level = FINEST java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter java.util.logging.ConsoleHandler.level = FINEST java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter ### Reloadable Application Support Currently Escalante does not support automatic Play application reload based on source file changes. When application source code changes, it's currently necessary to start Escalante once again (i.e. running `escalante-run` from SBT console). Future versions of Escalante will provide this functionality.