Tomcat WAR Deployment & Zero-Downtime

1. WAR Deployment Patterns

Root Application (/)

Deploy your artifact as webapps/ROOT.war to serve traffic on the domain root without subpath prefix.

sudo cp target/app.war /opt/tomcat/webapps/ROOT.war

Custom Context Path (/api)

Deploy your artifact as webapps/api.war or configure external context descriptor in conf/Catalina/localhost/api.xml.

<Context docBase="/var/deployments/api.war" reloadable="false" />

2. Zero-Downtime Parallel Versioned Deployments (myapp##version.war)

Tomcat natively supports parallel deployment without interrupting in-flight sessions: simply append ##<version> to the WAR filename.

# Version 1 running: existing users stay on v1
sudo cp target/app-v1.war /opt/tomcat/webapps/myapp##001.war

# Deploy Version 2: new sessions automatically route to v2; v1 drains gracefully!
sudo cp target/app-v2.war /opt/tomcat/webapps/myapp##002.war

3. GitHub Actions Automated Deployment Pipeline

name: Deploy to Production Tomcat

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      - name: Build with Maven
        run: mvn clean package -DskipTests
      - name: Deploy WAR to Tomcat via SSH
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.HOST }}
          username: tomcat
          key: ${{ secrets.SSH_KEY }}
          source: "target/ROOT.war"
          target: "/opt/tomcat/webapps/"