How to Deploy a WAR File to Tomcat – 如何将WAR文件部署到Tomcat上

最后修改: 2016年 9月 1日


1. Overview


Apache Tomcat is one of the most popular web servers in the Java community. It ships as a servlet container capable of serving Web Archives with the WAR extension.

Apache Tomcat是Java社区中最受欢迎的Web服务器之一。它作为一个servlet容器,能够为带有WAR扩展的Web档案服务。

It provides a management dashboard from which we can deploy a new web application, or undeploy an existing one without having to restart the container. This is especially useful in production environments.


In this tutorial, we’ll do a quick overview of Tomcat, and then cover various approaches to deploying a WAR file.


2. Tomcat Structure


Before we begin, we should familiarize ourselves with some terminology and environment variables.


2.1. Environment Variables


If we’ve worked with Tomcat before, these will be familiar to us.


This variable points to the directory where our server is installed:




This variable points to the directory of a particular instance of Tomcat (we may have multiple instances installed):




If this variable isn’t set explicitly, then it’ll be assigned the same value as $CATALINA_HOME.


Web applications are deployed under the $CATALINA_HOME\webapps directory.


2.2. Terminology


Document root – Refers to the top-level directory of a web application where all the application resources are located, like JSP files, HTML pages, Java classes, and images.


Context path – Refers to the location that’s relative to the server’s address and represents the name of the web application.

上下文路径 – 指的是与服务器地址相对的位置,代表网络应用程序的名称。

For example, if our web application is put under the $CATALINA_HOME\webapps\myapp directory, it’ll be accessed by the URL http://localhost/myapp, and its context path will be /myapp.

例如,如果我们的网络应用被放在$CATALINA_HOME\webapps\myapp目录下,它将被URL http://localhost/myapp访问,其上下文路径将是/myapp

WAR – Short for Web Archive. It’s the extension of a file that packages a web application directory hierarchy in ZIP format. Java web applications are usually packaged as WAR files for deployment. These files can be created on the command line or with an IDE, like Eclipse.

WAR –网络档案的简称。它是一个文件的扩展名,以ZIP格式打包网络应用程序目录层次结构。Java网络应用程序通常被打包成WAR文件进行部署。这些文件可以在命令行上创建,也可以用IDE创建,如Eclipse。

After deploying the WAR file, Tomcat unpacks it and stores all the project files from the webapps directory in a new directory named after the project.


3. Tomcat Setup


The Tomcat Apache web server is free software that can be downloaded from their website. It’s a requirement that the user’s machine has a JDK available, and that the JAVA_HOME environment variable is set correctly.

Tomcat Apache Web 服务器是免费软件,可以从其网站下载。这是一个要求,即用户的机器有JDK可用,并且JAVA_HOME环境变量被正确设置。

3.1. Start Tomcat


We can start the Tomcat server by simply running the startup script located at $CATALINA_HOME\bin\startup. There’s a .bat and .sh in every installation.


We’ll choose the appropriate option depending on whether we’re using a Windows or Unix based operating system.


3.2. Configure Roles


During the deployment phase, we’ll have some options, one of which is to use Tomcat’s management dashboard. To access this dashboard, we must have an admin user configured with the appropriate roles.


To have access to the dashboard, the admin user needs the manager-gui role. Later, we’ll need to deploy a WAR file using Maven, and for this we’ll also need the manager-script role too.


Let’s make these changes in $CATALINA_HOME\conf\tomcat-users:


<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<user username="admin" password="password" roles="manager-gui, manager-script"/>

More details about the different Tomcat roles can be found by following this official link.


3.3. Set Directory Permissions


Finally, we’ll ensure that there’s read/write permission on the Tomcat installation directory.


3.4. Test Installation


To test that Tomcat is set up properly, we’ll run the startup script (startup.bat/ If no errors are displayed on the console, we can double-check by visiting http://localhost:8080.


If we see the Tomcat landing page, then we have installed the server correctly.


3.5. Resolve Port Conflict


By default, Tomcat is set to listen to connections on port 8080. If there’s another application that’s already bound to this port, the startup console will let us know.


To change the port, we can edit the server configuration file, server.xml, located at $CATALINA_HOME\conf\server.xml. By default, the connector configuration is:


<Connector port="8080" protocol="HTTP/1.1" 
  connectionTimeout="20000" redirectPort="8443" />

For instance, if we want to change our port to 8081, then we’ll have to change the connector’s port attribute:


<Connector port="8081" protocol="HTTP/1.1" 
  connectionTimeout="20000" redirectPort="8443" />

Sometimes, the port we have chosen is not open by default. In that case, we would need to open the port with the appropriate commands in the Unix kernel, or create the appropriate firewall rules in Windows. We won’t go into further details here as it’s beyond the scope of this article.


4. Deploy From Maven


If we want to use Maven for deploying our web archives, we must configure Tomcat as a server in Maven’s settings.xml file.


There are two locations where the settings.xml file may be found:


  • The Maven install: ${maven.home}/conf/settings.xml
  • A user’s install: ${user.home}/.m2/settings.xml

Once we have found it, we’ll add Tomcat:



Now we’ll need to create a basic web application from Maven to test the deployment. Let’s navigate to where we would like to create the application.


We’ll run this command on the console to create a new Java web application:

我们将在控制台运行这个命令来创建一个新的Java Web应用程序。

mvn archetype:generate -DgroupId=com.baeldung -DartifactId=tomcat-war-deployment 
  -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

This will create a complete web application in the directory tomcat-war-deployment, which will print hello world! if we deploy it now and access it via the browser.

这将在tomcat-war-deployment,目录下创建一个完整的Web应用程序,它将打印hello world!如果我们现在部署它并通过浏览器访问它。

But before we do that, we need to make one change to enable Maven deployment. Let’s head over to the pom.xml and add this plugin:

但在这之前,我们需要做一个改动,以启用Maven部署。让我们前往 pom.xml,添加这个插件。


Note that we’re using the Tomcat 7 plugin because it works for both versions 7 and 8 without any special changes.

请注意,我们使用的是Tomcat 7插件,因为它对7和8版本都适用,不需要做任何特别的改动。

The configuration url is the url to which we’re sending our deployment, and Tomcat will know what to do with it. The server element is the name of the server instance that Maven recognizes. Finally, the path element defines the context path of our deployment.

配置url是我们要发送部署的URL,Tomcat会知道如何处理它。server元素是Maven识别的服务器实例的名称。最后,path元素定义了部署的context path

This means that if our deployment succeeds, we’ll access the web application by hitting http://localhost:8080/myapp.


Now we can run the following commands from Maven.


To deploy the web app:


mvn tomcat7:deploy

Then to undeploy it:


mvn tomcat7:undeploy

Finally, to redeploy it after making changes:


mvn tomcat7:redeploy

5. Deploy With Cargo Plugin


Cargo is a versatile library that allows us to manipulate the various types of application containers in a standard way.


5.1. Cargo Deployment Setup


In this section, we’ll learn how to use Cargo’s Maven plugin to deploy a WAR to Tomcat. In this case, we’ll deploy it to a version 7 instance.


To get a firm understanding of the whole process, we’ll start from scratch by creating a new Java web application from the command line:

为了坚定地了解整个过程,我们将从头开始,从命令行中创建一个新的Java Web应用程序。

mvn archetype:generate -DgroupId=com.baeldung -DartifactId=cargo-deploy 
  -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false

This will create a complete Java web application in the cargo-deploy directory. If we build, deploy, and load this application as is, it’ll print Hello World! in the browser.

这将在cargo-deploy目录下创建一个完整的Java Web应用程序。如果我们构建、部署并按原样加载这个应用程序,它将在浏览器中打印Hello World!

Unlike the Tomcat7 Maven plugin, the Cargo Maven plugin requires that this file is present.

与Tomcat7 Maven插件不同,Cargo Maven插件要求存在该文件。

Since our web application doesn’t contain any servlets, our web.xml file will be very basic. We’ll navigate to the WEB-INF folder of our newly created project, and create a web.xml file with the following content:


<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="" 
        id="WebApp_ID" version="3.0">


To enable Maven to recognize Cargo’s commands without typing the fully qualified name, we need to add the Cargo Maven plugin to a plugin group in Maven’s settings.xml.

为了让Maven在不输入全称的情况下识别Cargo的命令,我们需要将Cargo Maven插件添加到Maven的settings.xml中的一个插件组。

As an immediate child of the root <settings></settings> element, we’ll add:



5.2. Local Deploy


In this subsection, we’ll edit our pom.xml to suit our new deployment requirements.


We’ll add this plugin:


                    <home>Insert absolute path to tomcat 7 installation</home>
                    <home>Insert absolute path to tomcat 7 installation</home>

The latest version, at the time of writing, is 1.5.0. However, the latest version can always be found here.


Notice that we explicitly define the packaging as a WAR; without this, our build will fail. In the plugins section, we’ll then add the cargo maven2 plugin. Additionally, we’ll add a configuration section where we tell Maven that we’re using a Tomcat container and also an existing installation.

请注意,我们明确地将包装定义为WAR;如果不这样做,我们的构建就会失败。在插件部分,我们将添加cargo maven2插件。此外,我们将添加一个配置部分,告诉Maven我们使用的是Tomcat容器和现有安装。

By setting the container type to installed, we tell Maven that we have an instance installed on the machine, and we provide the absolute URL to this installation.


By setting the configuration type to existing, we tell Tomcat that we have an existing setup that we’re using, and no further configuration is required.


The alternative would be to tell cargo to download and setup the version specified by providing a URL. However, our focus is on WAR deployment.


It’s worth noting that whether we’re using Maven 2.x or Maven 3.x, the cargo maven2 plugin works for both.

值得注意的是,无论我们使用的是Maven 2.x还是Maven 3.x,cargo maven2插件都适用于两者。

We can now install our application by executing:


mvn install

Then we’ll deploy it:


mvn cargo:deploy

If all goes well, we should be able to run our web application by loading http://localhost:8080/cargo-deploy.


5.3. Remote Deploy


To do a remote deploy, we only need to change the configuration section of our pom.xml. Remote deploy means that we don’t have a local installation of Tomcat, but have access to the manager dashboard on a remote server.


Let’s change the pom.xml so that the configuration section looks like this:



This time, we change the container type from installed to remote, and the configuration type from existing to runtime. Finally, we add authentication and remote URL properties to the configuration.


We’ll ensure that the roles and users are already present in $CATALINA_HOME/conf/tomcat-users.xml, just as before.


If we’re editing the same project for remote deployment, we’ll first un-deploy the existing WAR:


mvn cargo:undeploy

Then we’ll clean the project:


mvn clean

Next, we’ll install it:


mvn install

Finally, we’ll deploy it:


mvn cargo:deploy

That’s it.


6. Deploy From Eclipse


Eclipse allows us to embed servers in order to add web project deployment in the normal workflow without navigating away from the IDE.


6.1. Embed Tomcat in Eclipse


To embed an installation into eclipse, we select the window menu item from the taskbar, and then preferences from the drop down.


Then we’ll see a tree grid of preference items on the left panel of the window that appears. Next, we navigate to eclipse -> servers, or just type servers in the search bar.

然后我们会在出现的窗口左侧面板上看到一个树状的偏好项目网格。接下来,我们导航到eclipse -> servers,或者直接在搜索栏中输入servers

We can then select the installation directory, if not already open for us, and choose the Tomcat version we downloaded.


On the right hand side of the panel, a configuration page will appear. Here we select the Enable option to activate this server version and browse to the installation folder.



We’ll apply the changes, and then the next time we open the servers view from Eclipse’s windows -> show view sub-menu, the newly configured server will be present, and we can start, stop and deploy applications to it.

我们将应用这些更改,然后下次我们从Eclipse的windows -> show view子菜单中打开服务器视图时,新配置的服务器将出现,我们可以启动、停止并向其部署应用程序。

6.2. Deploy Web Application in Embedded Tomcat


To deploy a web application to Tomcat, it must exist in our workspace.


Let’s open the servers view from window -> show view and look for servers. When open, we can just right click on the server we configured and select add deployment from the context menu that appears.

让我们从window -> show view打开servers视图,寻找服务器。打开后,我们可以直接右击我们配置的服务器,并从出现的上下文菜单中选择添加部署



From the New Deployment dialog box that appears, we’ll open the project drop down, and select the web project.


There’s a Deploy Type section beneath the Project combo box. When we select Exploded Archive(development mode), our changes in the application will be synced live without having to redeploy. This is the best option during development as it’s very efficient.

项目组合框的下面有一个部署类型部分。当我们选择Exploded Archive(development mode)时,我们在应用程序中的变化将被实时同步,而无需重新部署。这是开发期间的最佳选择,因为它非常高效。



Selecting Packaged Archive(production mode) will require us to redeploy every time we make changes and see them in the browser. This is best only for production, but still, Eclipse makes it equally easy.

选择Packaged Archive(production mode)将要求我们在每次进行修改并在浏览器中看到它们时都要重新部署。这只对生产来说是最好的,但仍然,Eclipse使它同样简单。

6.3. Deploy Web Application in External Location


We usually choose to deploy a WAR through Eclipse to make debugging easier. However, there may come a time when we want it deployed to a location other than those used by Eclipse’s embedded servers. The most common instance is when our production server is online, and we want to update the web application.


We can bypass this procedure by deploying in production mode, noting the Deploy Location in the New Deployment dialog box, and then picking the WAR from there.


During deployment, instead of selecting an embedded server, we can select the <Externally Launched> option from the servers view alongside the list of embedded servers. Then we navigate to the webapps directory of an external Tomcat installation.

在部署期间,我们可以从嵌入式服务器列表旁边的servers视图中选择<Externally Launched>选项,而不是选择一个嵌入式服务器。然后我们导航到外部Tomcat安装的webapps目录。

7. Deploy From IntelliJ IDEA

7.从IntelliJ IDEA部署

To deploy a web application to Tomcat, it must exist and have already been downloaded and installed.


7.1. Local Configuration


Let’s open the Run menu, and click the Edit Configurations options.

让我们打开Run菜单,点击Edit Configurations选项。



In the panel on the left, we’ll search for Tomcat Server. If it’s not there, we’ll click the + sign in the menu, search for Tomcat, and select Local. In the name field, we’ll put Tomcat 7/8 (depending on our version).

在左边的面板中,我们将搜索Tomcat服务器。如果它不在那里,我们将点击菜单中的+号,搜索Tomcat,并选择Local。在名称字段中,我们将填写Tomcat 7/8(取决于我们的版本)。



Then we’ll click the Configure… button, and in the Tomcat Home field, we’ll navigate to the home location of our installation and select it.

然后我们将点击Configure…按钮,在Tomcat Home字段中,我们将导航到我们安装的主页位置并选择它。



Optionally, we can set the Startup page to be http://localhost:8080/ and HTTP port: 8080; we’ll change the port as appropriate.

另外,我们可以将启动页面设置为http://localhost:8080/ HTTP端口。8080;我们将根据情况改变端口。

Finally, we’ll go to the Deployment tab, click on the + symbol, select the artifact we want to add to the server, and click OK.





7.2. Remote Configuration


We’ll follow the same instructions as for local Tomcat configurations, but in the server tab, we must enter the remote location of the installation.


8. Deploy by Copying Archive


We’ve learned how to export a WAR from Eclipse. Another thing we can do is to deploy it by simply dropping it into the $CATALINA_HOME\webapps directory of any Tomcat instance. If the instance is running, the deployment will start instantly as Tomcat unpacks the archive and configures its context path.


If the instance isn’t running, then the server will deploy the project the next time it’s started.


9. Deploy From Tomcat Manager


Assuming we already have our WAR file to hand, and would like to deploy it using the management dashboard, we can access the manager dashboard by visiting: http://localhost:8080/manager.


The dashboard has five different sections: Manager, Applications, Deploy, Diagnostics, and Server Information.

仪表板有五个不同的部分。Manager, Applications, Deploy, Diagnostics, 和Server Information.

If we go to the Deploy section, we’ll find two subsections.


9.1. Deploy Directory or WAR File Located on Server


If the WAR file is located on the server where the Tomcat instance is running, then we can fill the required Context Path field preceded by a forward slash “/”.

如果WAR文件位于运行Tomcat实例的服务器上,那么我们可以填写所需的Context Path字段,前面加一个正斜杠”/”。

For example, if we’d like our web application to be accessed from the browser with the URL http://localhost:8080/myapp, then our context path field will have /myapp.


We can also skip the XML Configuration file URL field and head over to the WAR or Directory URL field. Here, we’ll enter the absolute URL to the Web Archive file as it appears on our server. For example, if our file’s location is C:/apps/myapp.war, then we enter this location. It’s important we don’t forget the WAR extension.


After that, we can click the deploy button. The page will reload, and we should see this message at the top of the page:


OK - Deployed application at context path /myapp

Our application should also appear in the Applications section of the page.


9.2. WAR File to Deploy


Here, we just click the choose file button, navigate to the location of the WAR file, select it, and then click the deploy button.


In both situations, if all goes well, the Tomcat console will inform us that the deployment has been successful with the following message:


INFO: Deployment of web application archive \path\to\deployed_war has finished in 4,833 ms

10. Conclusion


In this article, we focused on how to deploy a WAR into a Tomcat server.