How to Deploy a WAR File in Tomcat
Copy the WAR into Tomcat's webapps directory: with autoDeploy on, app.war is served at /app and ROOT.war at /. Or upload through the Manager page at /manager/html. Confirm the startup line in logs/catalina.out, then open the context on port 8080.
For Java developers deploying servlet and Spring Boot WARs on a Linux VPS or dedicated Tomcat server.
knowledge
- Read time
- 7 min
- Sections
- 9
- Updated
- 14 Nov 2026
- Written by
- WebJi® team
Last editorial update: 15 November 2026.
What is a WAR file, and what does its name decide?
A WAR file is a zip archive of one Java web application — classes, JSPs and a WEB-INF directory — and Tomcat serves it as one context whose URL path comes from the file name. Tomcat calls each deployed application a context; app.war answers at /app, and ROOT.war, spelled in capitals, is the only name that occupies the bare host at /.
- One WAR is one web application; a setting inside the archive does not set its URL path, though a context descriptor in
conf/[engine]/[host]/can override the file name. - Double hash means version, not a longer path:
shop##2.0.warstill serves at/shop— Tomcat's parallel versioning keeps the path and tracks 2.0 as the version, so old sessions can finish on the previous WAR. - The servlet namespace must match the server: Tomcat 9 loads
javax.servlet(what Spring Boot 2.x and older servlet apps are built against); Tomcat 10.1 and Tomcat 11 loadjakarta.servlet. A javax WAR on Tomcat 10 fails before the first page renders.
Which Tomcat deployment method fits your workflow?
Three built-in routes land on the same context URL — copy the file into webapps, upload it through the Manager web page, or POST it to the Manager text API — so pick by how the WAR reaches the server. All three are documented in Tomcat's own deployment guide; a fourth, the Tomcat Client Deployer, wraps the text API in Ant for build pipelines.
| Method | Use it when | You need | It worked when |
|---|---|---|---|
| Copy into webapps | You have a shell on the server | autoDeploy on, or a restart | catalina.out names the archive and the context URL loads |
| Manager HTML page | Someone uploads a build in a browser | A user with the manager-gui role | The application list shows the path as running |
| Manager text API | A build server deploys | A user with the manager-script role | The call to /manager/text/deploy returns OK |
An IDE deploy talks to a Tomcat on your laptop. Use it to test locally; use one of the rows above when the WAR has to run on the server your visitors reach.
How do you deploy a WAR by copying it into webapps?
Copy the WAR into the Host's appBase — $CATALINA_BASE/webapps, which is /opt/tomcat/webapps on a tarball install and /var/lib/tomcat10/webapps on Ubuntu's tomcat10 package — and Tomcat publishes it while running when autoDeploy is on. If autoDeploy is off, deployOnStartup (on by default) publishes whatever sits in webapps at the next start.
- Build the WAR on a JDK that matches the target Tomcat line, then copy it with
scpas the tomcat user's ownership, not root's. - Name it for the URL you want —
app.warfor/app,ROOT.warfor the host root — and remove any leftover exploded folder of the same name. - Watch
logs/catalina.outfor a line naming that archive; withunpackWARsat its default, a directory appears beside the WAR. - Open
http://the-server:8080/app, orhttps://your-domain/apponce a proxy is in front. A Tomcat 404 means the context never started; your own application's error page means it did. - Replace the WAR to ship a new build — Tomcat redeploys when the new WAR is newer than the exploded directory. Delete both the WAR and the exploded directory, or undeploy in Manager, when the context should go away.
Do not drop the file into a PHP or static-files docroot; Tomcat only auto-deploys from its own appBase. Connect to the server over SSH first — the PuTTY connection guide covers that step.
How do you deploy through the Tomcat Manager?
Open http://the-server:8080/manager/html as a user whose role is manager-gui, choose the WAR from your computer, and deploy it without restarting Tomcat. The user is defined in conf/tomcat-users.xml; the text interface that build servers use lives at /manager/text under the manager-script role, and both answer to the same running server.
The check is the new row in the Manager's application list: state running, path matching the file name. Undeploy on that row removes the context cleanly. Two Manager facts trip people up:
- 403 with a correct password is usually not the password. The stock Manager app allows only localhost until you edit its
RemoteAddrValve. Add your address, or tunnel port 8080 over SSH — do not open Manager to the whole internet. - manager-gui is the browser role, manager-script the API role. A CI job failing with 401 while the browser works means the user has the wrong one.
How do you deploy a Spring Boot WAR to external Tomcat?
Three build settings turn a Spring Boot app into a deployable WAR: set packaging to war, mark spring-boot-starter-tomcat as provided, and extend SpringBootServletInitializer from your application class. The WAR lands in the build output (usually target/) and deploys by either method above like any other WAR.
Do not also run java -jar for the same app on the same host — the embedded server and the external Tomcat will fight over port 8080. Match the generations: Spring Boot 2.x builds against javax.servlet and stays on Tomcat 9; Spring Boot 3.x needs Java 17 and a jakarta server, so use Tomcat 10.1 or 11. An executable jar with its own embedded server is a different deployment model, not a WAR deploy.
How do you run Tomcat properly on a Linux VPS?
Run Tomcat as a dedicated system user behind a reverse proxy on 443, with the heap set in bin/setenv.sh — that is the layout a Java app needs on a VPS. Shared hosting has no system JDK and no service you can restart, so a WAR deploy starts at the VPS tier; if you would rather not build the stack yourself, Java and Tomcat hosting is this same layout with root SSH, quoted by email before you pay, and moving an existing app is free after terms and approval.
- Install a JDK matching the Tomcat line — OpenJDK 17 runs Tomcat 10.1 and 11; Tomcat 9 also runs on Java 8 or 11. The Ubuntu Java install guide covers the JDK step.
- Create a service user (
adduser --system --group tomcat), download the core tarball from tomcat.apache.org into/opt/tomcat, and hand the tree to that user. Never run the service as root. - Add a systemd unit whose start command is
/opt/tomcat/bin/catalina.sh runwithUser=tomcat, thensystemctl enable --now tomcat. The welcome page on port 8080 means the container is up. - Put Nginx or Apache on 80/443 and proxy to
127.0.0.1:8080, then close 8080 on the public firewall. Binding Tomcat itself to port 80 would force running as root — skip that. - Set the heap in
/opt/tomcat/bin/setenv.shviaCATALINA_OPTS: on a 2 GB VPS,-Xms1g -Xmx1guses about half the RAM and leaves room for the OS and metaspace. A systemd unit ignores flags exported in.bashrc, so put them in the unit or setenv.sh and confirm withps.
Ports for reference: 8080 is the default HTTP connector in conf/server.xml, 8005 the shutdown port, 8443 only the redirect port. A hostname timeout while :8080 still loads is a closed 443 or a proxy aimed at the wrong port — not a bad WAR.
Why did the WAR deploy fail?
Read logs/catalina.out first — the line you want names your archive and says the context started; anything else maps to one of these five fixes. Change one thing, wait for autoDeploy or a restart, then read the log again.
- 404 at the right host: the path is the file name.
app.waris/app, not/; onlyROOT.wartakes the bare host. - javax.servlet error on Tomcat 10 or 11: wrong namespace for that server — move the WAR to Tomcat 9 or rebuild it for jakarta.
- Address already in use: another process holds 8080, often an embedded jar you forgot to stop. Stop it, or change the connector and the proxy together.
- WAR sits in webapps and nothing happens: autoDeploy is off, the tomcat user cannot read the file, or the copy landed outside appBase.
- Manager returns 403: the user lacks the right manager role, or the RemoteAddrValve still allows only 127.0.0.1.
- The old app is still what you see: the exploded directory is newer than the WAR, or a second copy is deployed under another name.
If the VPS is a WebJi® server and the unit will not stay up, email support@webji.services — staffed round the clock in Hindi and English. The office phone is a business-hours line, not a support channel.
Frequently asked questions
How do I deploy a WAR file in Tomcat?
Copy the WAR into the webapps directory. With autoDeploy on, Tomcat serves app.war at /app and ROOT.war at /. Check logs/catalina.out for the deploy line, then open that path on port 8080.
Where do WAR files go in Tomcat?
Into the Host appBase: $CATALINA_BASE/webapps — /opt/tomcat/webapps on a tarball install, /var/lib/tomcat10/webapps on Ubuntu's tomcat10 package. Tomcat does not auto-deploy from any other directory.
How do I access Tomcat Manager remotely?
Open http://the-server:8080/manager/html as a user with the manager-gui role in conf/tomcat-users.xml. A 403 with correct credentials usually means the Manager's RemoteAddrValve still allows only localhost — add your address or tunnel over SSH.
What is the difference between shop.war and shop##2.0.war?
Both serve at /shop. The double hash marks a parallel-deployment version: new requests get 2.0 while sessions pinned to the older WAR finish on it. A single # in the name is not a version marker and does not add a path segment.
How do I increase Tomcat memory on a VPS?
Put -Xms and -Xmx in CATALINA_OPTS inside bin/setenv.sh, which catalina.sh reads at start. On a 2 GB VPS, 1g for both is about half the RAM. Restart and confirm -Xmx on the java process line with ps.
Why is my WAR not deploying?
Check catalina.out. Typical causes: a javax WAR on Tomcat 10 or 11, a file the tomcat user cannot read, autoDeploy turned off, or port 8080 already in use by another process.
Last editorial update: 15 November 2026.
Ready to get started with WebJi®?
Join 12,000+ businesses across India and overseas. INR pricing, 18% GST shown before payment and 24/7 email support in Hindi and English — average first reply under 60 minutes.