Deploy a Java web environment (Tomcat) - Elastic Compute Service

Deployment options

Automated deployment (Terraform): Click Run Now to use Terraform to automatically create a complete environment, including an ECS instance, a public IP address, and the necessary security group rules.
Manual deployment: If you have an existing ECS instance or prefer to control the deployment process, follow these steps.

Prerequisites

Enable public network access: Assign a fixed public IP address or an Elastic IP (EIP) to the instance.
Add security group rules:
- For Linux: Allow inbound traffic over TCP on ports 22 (SSH) and 8080 (Tomcat).
- For Windows: Allow inbound traffic over TCP on ports 3389 (RDP) and 8080 (Tomcat).
Manually deploy OpenJDK: Install a Java Development Kit (JDK) on the server.

Procedure

Linux

Step 1: Download and install Tomcat

Log on to an ECS instance.
1. Go to ECS console - Instances. In the top-left corner, select the region and resource group for the target instance.
2. Navigate to the details page of the target instance. Click Connect and select Workbench. Follow the on-screen prompts to access the terminal.

Download and extract the Tomcat installation package.

This example uses Tomcat v9.0.91. To install a different version, get the download URL from the official Tomcat website and replace the URL in the command.

# Download the Tomcat installation package
sudo wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.91/bin/apache-tomcat-9.0.91.tar.gz  --no-check-certificate 
# Extract the package to the /usr/local/ directory
sudo tar -zxvf apache-tomcat-9.0.91.tar.gz -C /usr/local/

Create a symbolic link.
This approach allows you to upgrade Tomcat by only updating the symbolic link, without modifying the service configuration file.
```
sudo ln -s /usr/local/apache-tomcat-9.0.91 /usr/local/tomcat
```

Step 2: Configure Tomcat service

Configure Tomcat as a systemd service to enable automatic startup.

Get the JDK path.
```
sudo readlink -f $(which java)
```
- For JDK 8: The correct JDK path is the parent directory of the jre directory.
- For JDK 11 or later: The returned path is the correct JDK path.

Create the tomcat.service service file.

Replace JDK_PATH with the JDK path that you obtained in the previous step.

sudo tee /etc/systemd/system/tomcat.service > /dev/null <<'EOF'
[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment="JAVA_HOME=JDK_PATH"
Environment="CATALINA_PID=/usr/local/tomcat/temp/tomcat.pid"
Environment="CATALINA_HOME=/usr/local/tomcat"
Environment="CATALINA_BASE=/usr/local/tomcat"

ExecStart=/usr/local/tomcat/bin/startup.sh
ExecStop=/usr/local/tomcat/bin/shutdown.sh

Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

Start the Tomcat service and enable it to start on boot.

# Reload the systemd configuration for the new service file to take effect
sudo systemctl daemon-reload
# Start the Tomcat service
sudo systemctl start tomcat
# Enable the Tomcat service to start on boot
sudo systemctl enable tomcat

Step 3: Verify the deployment

Check the service status.
```
sudo systemctl status tomcat
```
If active (running) is returned, Tomcat started successfully.
Verify access.
In the address bar of your local browser, enter http://<ECS instance public IP address>:8080. If the Tomcat welcome page is displayed, the Java web environment is deployed successfully.

Windows

This example shows how to deploy Tomcat 9.0.121 on a 64-bit Windows Server 2022 instance.

Step 1: Install and configure Tomcat

Log on to an ECS instance.
1. Go to ECS console - Instances. In the top-left corner, select the region and resource group for the target instance.
2. Navigate to the details page of the target instance. Click Connect and select Workbench. Set the connection method to Terminal Connection, enter your username and password, and log on to the graphical terminal.
Download Tomcat 9.0.121 and extract the package.
You can launch PowerShell and execute the following command to retrieve Tomcat 9.0.121 from the Alibaba Cloud Open Source Mirror repository.
```
# 1. Modify the paths below as needed
$Url = "https://mirrors.aliyun.com/apache/tomcat/tomcat-9/v9.0.121/bin/apache-tomcat-9.0.121-windows-x64.zip"
$Zip = "C:\Downloads\tomcat.zip"       # Download Path
$Dest = "C:\Applications\tomcat"       # Extract Directory

# 2. Download and extract the package
Invoke-WebRequest $Url -OutFile $Zip
Expand-Archive $Zip -DestinationPath $Dest -Force
```
We recommend that you extract the compressed package to a path that does not contain Chinese characters, for example, C:\Java\apache-tomcat-9.0.97, to avoid potential path recognition issues.
If you need a different version, visit the official Tomcat website, select the version you need, and then download and extract the installation package.
Configure environment variables.
1. Right-click This PC and select Type > Advanced system settings > Environment Variable.
2. In the System variables area, click New Resources, create the CATALINA_HOME system variable, set the variable value to the Tomcat installation path, and then click OK.
3. In System Variables, find the Path variable, select it, and click Modify.
4. In Edit environment variable, click New Resources, add %CATALINA_HOME%\bin, and click OK to save the configuration.

Step 2: Install and start Tomcat service

Installing Tomcat as a Windows service, instead of using startup.bat to run it temporarily, allows Tomcat to run stably in the background and enables automatic startup.

Install the service.
Open Command Prompt as an administrator, switch to the Tomcat bin directory, and run the installation command.
```
service.bat install Tomcat9
```
If the message The service 'Tomcat9' has been installed. is returned, the installation is successful.
Tomcat9 is a custom service name that will be used when managing the service.
Start the service and set it to start automatically.
1. Right-click , then click Run, enter services.msc, and press Enter to open the Services Manager.
2. Locate the Apache Tomcat 9.0 Tomcat9 service, right-click the service, select Type, set the Startup Type to Automatic, and then click Start.
If you see garbled Chinese characters in the logs, see Tomcat logs display garbled Chinese characters.

Step 3: Verify the deployment

In the address bar of your browser, enter http://<ECS instance public IP address>:8080. If the Tomcat welcome page is displayed, the Java web environment is successfully deployed.

Next steps

Upload a web project

Follow the instructions in Use Workbench to upload or download files to upload a web application (.war file) to the Tomcat website root directory (which is webapps by default). Tomcat will automatically detect and deploy the WAR file.

After deployment, you can access the application at http://<public IP address>:8080/<project name>.

Configure Tomcat

Modify the configuration file

Go to the conf folder in the Tomcat installation directory, and open the server.xml file.

Modify the Tomcat configuration.

Tomcat uses port 8080 by default, and you can change it by modifying the value of the port attribute.

After you change the port, you must add a security group rule to allow inbound traffic on the new port.

&lt;!-- A &quot;Connector&quot; represents an endpoint by which request
     and responses are returned. Documentation at :
     Java HTTP Connector: /docs/config/http.html
     Java AJP  Connector: /docs/config/ajp.html
     APR (HTTP/AJP) Connector: /docs/apr.html
     Define a non-SSL/TLS HTTP/1.1 Connector on port 8080
--&gt;
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           maxParameterCount="1000"
           />

The default website root directory for Tomcat is webapps. To change the website root directory, you can modify the value of the appBase attribute.

In the following <Host> configuration from server.xml, the appBase="webapps" attribute specifies the application deployment directory:

</Realm>
<Host name="localhost" appBase="webapps"
      unpackWARs="true" autoDeploy="true">
  &lt;!-- SingleSignOn valve, share authentication between web applications
       Documentation at: /docs/config/valve.html --&gt;
  &lt;!--
  &lt;Valve className=&quot;org.apache.catalina.authenticator.SingleSignOn&quot; /&gt;
  -->

Set JVM memory parameters for Tomcat

Linux

Create a setenv.sh file. You can use the setenv.sh file to centrally manage JVM parameters.

Adjust the initial and maximum JVM heap sizes based on your ECS instance specifications and application load.

sudo tee /usr/local/tomcat/bin/setenv.sh > /dev/null <<'EOF'
#!/bin/bash
# Example: For an ECS instance with 2 GB of memory, allocate 512 MB
JAVA_OPTS="-server -Xms512m -Xmx512m"
export JAVA_OPTS
EOF

Add execute permissions to the file.

sudo chmod +x /usr/local/tomcat/bin/setenv.sh

Restart Tomcat for the configuration to take effect.

Windows

Go to the bin folder in the Tomcat installation directory, and open the catalina.bat file.
Add or modify the JVM parameters.
Near the beginning of the file (usually after setlocal and before call "%CATALINA_HOME%\bin\setenv.bat"), add or modify JAVA_OPTS . Adjust the initial and maximum JVM heap memory based on the ECS instance specifications and application load.
```
# Example: For an ECS instance with 2 GB of memory, allocate 512 MB
set "JAVA_OPTS=%JAVA_OPTS% -Xms512m -Xmx512m"
```
If JAVA_OPTS already exists, append the parameters to it (note that a space is required between parameters).
Restart Tomcat for the configuration to take effect.

Production environment recommendations

For production environments, take the following steps after deployment to reduce security risks.

Delete default applications
To reduce the potential attack surface, we recommend that you delete all default example applications under the webapps directory, such as docs, examples, manager, and host-manager.
- Linux: sudo rm -rf /usr/local/tomcat/webapps/*
- Windows: Use File Explorer to manually delete all subdirectories in the CATALINA_HOME\webapps directory.
Configure HTTPS
Use HTTPS in production. Install an SSL certificate on the Tomcat server (Linux), and use Nginx or Server Load Balancer (SLB) as a reverse proxy to handle HTTPS requests.

FAQ

Browser times out or cannot be reached

Check the security group: Check if the inbound rules of the ECS instance's security group allow port 8080.
Check the OS firewall: Check whether the OS firewall (such as firewalld or Windows Defender Firewall) is disabled or has been configured to allow traffic on port 8080.
Check the port listener: Confirm that Tomcat is listening on port 8080.
- Linux: ss -lntp | grep 8080
- Windows: netstat -ano | findstr ":8080"

Tomcat fails to start

Check logs: The main Tomcat logs are located in the logs folder of its installation directory. Check the catalina.out (Linux) or catalina.<date>.log (Windows) and localhost.<date>.log files. If the logs contain the Address already in use error, it means that the port is occupied by another program. For more information, see Troubleshoot port inaccessibility when an ECS instance can be pinged.
JDK path error: Check whether the JAVA_HOME environment variable is configured correctly.

Tomcat logs display garbled Chinese characters

This issue usually occurs due to a mismatch between the default encoding of the Windows Command Prompt (CMD), which is GBK, and the encoding of Tomcat's log output, which is typically UTF-8.

Open the conf folder in the Tomcat installation directory and find and edit the logging.properties file.
Change all default UTF-8 encodings in the file to GBK.
Save the file and restart Tomcat. Verify that Chinese characters in the logs display correctly.