path: root/documentation/getting-started/getting-started-environment.asciidoc

---
title: Setting up the Development Environment
order: 2
layout: page
---

[[getting-started.environment]]
= Setting up the Development Environment

This section guides you step-by-step in setting up a reference development
environment. Vaadin supports a wide variety of tools, so you can use any IDE for
writing the code, almost any Java web server for deploying the application, most
web browsers for using it, and any operating system platform supported by Java.

In this example, we use the following toolchain:

* Windows, Linux, or Mac OS X
* link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle Java SE 8] (Java 6 or newer is required)
* link:http://www.eclipse.org/downloads/[Eclipse IDE for Java EE Developers]
* link:http://tomcat.apache.org/[Apache Tomcat 8.0 (Core)]
* link:http://www.getfirefox.com/[Mozilla Firefox] browser
* link:http://www.getfirebug.com/[Firebug] debug tool (optional)
* link:http://vaadin.com/download/[Vaadin Framework]

The above reference toolchain is a good choice of tools, but you can use almost
any tools you are comfortable with.

We recommend using Java 8 for Vaadin development, but you need to make sure that
your entire toolchain supports it. A server supporting Servlet 3.0 is
recommended. It is required for using Vaadin CDI, for which also a CDI container
is required, a standard feature in Java EE 6 or newer servers. It is also
required by the Vaadin Spring add-on. Server push can benefit from using
communication modes, such as WebSocket, enabled by features in some latest
servers. For Java EE containers, at least Wildfly, Glassfish, and Apache TomEE
Web Profile are recommended.

[[figure.toolchain]]
.Development Toolchain and Process
image::img/toolchain-hi.png[]

<<figure.toolchain>> illustrates the development toolchain. You develop your
application as an Eclipse project. The project must include, in addition to your
source code, the Vaadin libraries. It can also include project-specific themes.

You need to compile and deploy a project to a web container before you can use
it. You can deploy a project through the Web Tools Platform (WTP) for Eclipse
(included in the Eclipse EE package), which allows automatic deployment of web
applications from Eclipse. You can also deploy a project manually, by creating a
web application archive (WAR) and deploying it to the web container.

[[getting-started.environment.java]]
== Installing Java SDK

Java SDK is required by Vaadin and also by the Eclipse IDE. Vaadin is compatible
with Java 1.6 and later editions. Java EE 7 is required for proper server push
support with WebSockets.

[[getting-started.environment.java.windows]]
=== Windows

. Download Oracle Java SE 8.0 from
link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/index.html]

. Install the Java SDK by running the installer. The default options are fine.

[[getting-started.environment.linux]]
=== Linux / UNIX

Most Linux systems either have JDK preinstalled or allow installing it through a
package management system. Notice however that they have OpenJDK as the default
Java implementation. While it is known to have worked with Vaadin and possibly
also with the development toolchain, we do not especially support it.

Regarding OS X, notice that JDK 1.6 or newer is included in OS X 10.6 and newer.

Otherwise:

. Download Oracle Java SE 8.0 from
link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[http://www.oracle.com/technetwork/java/javase/downloads/]

. Decompress it under a suitable base directory, such as [filename]#/opt#. For
example, for Java SDK, enter (either as root or with [command]#sudo# in Linux):

+
[subs="normal"]
----
[prompt]#+++#+++# [command]#cd# [replaceable]#/opt#
[prompt]#+++#+++# [command]#sh# [replaceable]##<path>##/jdk-[replaceable]##<version>##.bin
----
+
and follow the instructions in the installer.

. Set up the [literal]#++JAVA_HOME++# environment variable to point to the Java
installation directory. Also, include the [literal]#++$JAVA_HOME/bin++# in the
[literal]#++PATH++#. How you do that varies by the UNIX variant. For example, in
Linux and using the Bash shell, you would add lines such as the following to the
[filename]#.bashrc# or [filename]#.profile# script in your home directory:

+
----
export JAVA_HOME=/opt/jdk1.8.0_31
export PATH=$PATH:$HOME/bin:$JAVA_HOME/bin
----
+
You could also make the setting system-wide in a file such as
[filename]#/etc/bash.bashrc#, [filename]#/etc/profile#, or an equivalent file.
If you install Apache Ant or Maven, you may also want to set up those in the
path.

+
Settings done in a [filename]#bashrc# file require that you open a new shell
window. Settings done in a [filename]#profile# file require that you log in into
the system. You can, of course, also give the commands in the current shell.


[[getting-started.environment.eclipse]]
== Installing Eclipse IDE

=== Windows

. Download the Eclipse IDE for Java EE Developers from
link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/]

. Decompress the Eclipse IDE package to a suitable directory. You are free to
select any directory and to use any ZIP decompressor, but in this example we
decompress the ZIP file by just double-clicking it and selecting "Extract all
files" task from Windows compressed folder task. In our installation example, we
use [filename]#C:\dev# as the target directory.

Eclipse is now installed in [filename]#C:\dev\eclipse#.
You can start it from there by double clicking [filename]#eclipse.exe#.

=== Linux / OS X / UNIX

We recommend that you install Eclipse manually in Linux and other UNIX variants.
They may have it available from a package repository, but using such an installation may cause problems with installing plug-ins.

You can install Eclipse as follows:

. Download Eclipse IDE for Java EE Developers from
link:http://www.eclipse.org/downloads/[http://www.eclipse.org/downloads/]

. Decompress the Eclipse package into a suitable base directory. It is important
to make sure that there is no old Eclipse installation in the target directory.
Installing a new version on top of an old one probably renders Eclipse unusable.

. Eclipse should normally be installed as a regular user, which makes installation of plug-ins easier.
Eclipse also stores some user settings in the installation directory.
+
To install the package, enter:
+
[subs="normal"]
----
[prompt]#$# [command]#tar# zxf [replaceable]##<path>##/eclipse-jee-[replaceable]##<version>##.tar.gz
----
+
This will extract the package to a subdirectory with the name
[filename]#eclipse#.

. If you wish to enable starting Eclipse from command-line, you need to add the
Eclipse installation directory to your system or user PATH, or make a symbolic
link or script to point to the executable.


An alternative to the above procedure would be to use an Eclipse version
available through the package management system of your operating system. It is,
however, __not recommended__, because you will need write access to the Eclipse
installation directory to install Eclipse plugins, and you may face
incompatibility issues with Eclipse plugins installed by the package management
of the operating system.



[[getting-started.environment.tomcat]]
== Installing Apache Tomcat

Apache Tomcat is a lightweight Java web server suitable for both development and
production. There are many ways to install it, but here we simply decompress the
installation package.

__Apache Tomcat should be installed with user permissions.__ During development,
you will be running Eclipse or some other IDE with user permissions, but
deploying web applications to a Tomcat server that is installed system-wide
requires administrator or root permissions.

. Download the installation package:

+
Apache Tomcat 8.0 (Core Binary Distribution) from http://tomcat.apache.org/

. Decompress Apache Tomcat package to a suitable target directory, such as
[filename]#C:\dev# (Windows) or [filename]#/opt# (Linux or Mac OS X). The Apache
Tomcat home directory will be [filename]#C:\dev\apache-tomcat-8.0.x# or
[filename]#/opt/apache-tomcat-8.0.x#, respectively.



[[getting-started.environment.firefox]]
== Firefox and Firebug

Vaadin supports many web browsers and you can use any of them for development.
If you plan to create a custom theme, customized layouts, or create new
components, we recommend that you use either Firefox together with Firebug or
Google Chrome, which has built-in developer tools similar to Firebug.

[[getting-started.environment.firefox.firebug]]
=== Using Firebug with Vaadin

After installing Firefox, use it to open
link:http://www.getfirebug.com/[http://www.getfirebug.com/]. Follow the
instructions on the site to install the latest stable version of Firebug
available for the browser. You may need to allow Firefox to install the plugin
by clicking the yellow warning bar at the top of the browser window.

After Firebug is installed, it can be enabled at any time from the Firefox
toolbar. <<figure.firebug.calc>> shows Firebug in action.

[[figure.firebug.calc]]
.Firebug Debugger for Firefox
image::img/firebug.png[]

The most important feature in Firebug is inspecting HTML elements. Right-click
on an element and select [guilabel]#Inspect Element with Firebug# to inspect it.
In addition to HTML tree, it also shows the CSS rules matching the element,
which you can use for building themes. You can even edit the CSS styles live, to
experiment with styling.