AWS Tutorials

How to Deploy a Spring Boot App on an AWS EC2 Instance

Deploy a Spring Boot jar to AWS EC2: build it, install Java, run it as a systemd service behind Nginx, and keep database settings out of your code.

On this page
  1. What this guide covers
  2. Before you start
  3. Step 1: Build an executable jar
  4. Step 2: Launch an EC2 instance
  5. Step 3: Install Java on the instance
  6. Step 4: Copy the jar to the server
  7. Step 5: Run the jar and check it
  8. Step 6: Run the app as a systemd service
  9. Step 7: Put Nginx in front
  10. Step 8: Keep settings out of your code
  11. Step 9: Use a managed database for real data
  12. Other ways to host a Java web application on AWS
  13. Troubleshooting
  14. Clean up
  15. Next steps

What this guide covers

You will build a Spring Boot 3 app into an executable jar, copy it to an EC2 instance, run it as a systemd service and put Nginx in front of it on port 80. The last section compares other ways to host a Java web application on AWS.

Before you start

  • An AWS account and an IAM user with permission to use EC2. Avoid using the root user for daily work.
  • Java 17 or newer on your computer. Java 21 LTS is a common choice. You also need Maven or Gradle.
  • A Spring Boot 3 project that starts locally with java -jar.
  • Costs: while the instance runs, you pay for EC2, its EBS storage and its public IPv4 address.

Step 1: Build an executable jar

From your project folder, build the jar with the Maven wrapper:

./mvnw clean package

With Gradle, run ./gradlew bootJar instead. Maven writes the jar to target/, and Gradle writes it to build/libs/.

Test the jar on your computer before you move it:

java -jar target/your-app-0.0.1-SNAPSHOT.jar

Spring Boot listens on port 8080 by default. Open http://localhost:8080 and confirm the app responds.

Step 2: Launch an EC2 instance

In the EC2 console, choose Launch instance and set:

  • AMI: Amazon Linux 2023. Its default user is ec2-user.
  • Instance type: t3.small (2 GiB of memory) is a safer choice for a first deployment than t3.micro (1 GiB), which is tight for a JVM. Check your free-tier eligibility before you choose.
  • Key pair: create a key pair and download the .pem file.
  • Security group: allow SSH (port 22) from My IP only. If the site is public, allow HTTP (80) and HTTPS (443) from anywhere. You do not need to open port 8080 to the internet once Nginx is in front.

Launch the instance and wait until its state is Running.

Step 3: Install Java on the instance

Connect over SSH, then install Amazon Corretto 21:

ssh -i my-key.pem ec2-user@<public-dns-name>
sudo dnf install -y java-21-amazon-corretto-headless
java -version

Java 17 also works with Spring Boot 3. Install java-17-amazon-corretto-headless instead if your project targets 17.

Step 4: Copy the jar to the server

From your computer:

scp -i my-key.pem target/your-app-0.0.1-SNAPSHOT.jar ec2-user@<public-dns-name>:~/

On the instance, move the jar to a fixed location:

sudo mkdir -p /opt/app
sudo mv ~/your-app-0.0.1-SNAPSHOT.jar /opt/app/app.jar

Step 5: Run the jar and check it

java -Xmx512m -jar /opt/app/app.jar

The -Xmx flag sets the maximum Java heap. Choose a value that leaves memory for the operating system, Nginx and the JVM’s own overhead. On a 2 GiB t3.small, 512 MB is a reasonable starting point. On a 1 GiB t3.micro, use a smaller value, such as -Xmx384m, and watch memory with free -m.

In a second SSH session, run curl http://localhost:8080/ to confirm the app responds. The app stops when you close the SSH session, so the next step runs it as a service.

Step 6: Run the app as a systemd service

Create /etc/systemd/system/app.service:

[Unit]
Description=Spring Boot app
After=network.target

[Service]
User=ec2-user
ExecStart=/usr/bin/java -Xmx512m -jar /opt/app/app.jar
Restart=always

[Install]
WantedBy=multi-user.target

Then load the unit and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now app
sudo systemctl status app

Restart=always restarts the app after a crash, and enable starts it after a reboot. For production, create a dedicated system user for the service rather than reusing ec2-user. Change -Xmx512m in the unit if your instance has less memory.

Step 7: Put Nginx in front

Nginx accepts public traffic on port 80 and forwards it to the app on 8080:

sudo dnf install -y nginx

Create /etc/nginx/conf.d/app.conf:

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Check the configuration, then start Nginx:

sudo nginx -t
sudo systemctl enable --now nginx

Open http://<public-dns-name>/ in your browser. For HTTPS, you need a domain name. Certbot with Let’s Encrypt works with Nginx, and an Application Load Balancer with an ACM certificate is the other common option.

Step 8: Keep settings out of your code

  • Read configuration from environment variables. Spring Boot can read them directly, for example spring.datasource.password=${DB_PASSWORD} in application.properties.
  • Set variables in the systemd unit with Environment= lines, or load them from a file with EnvironmentFile=. For stronger protection, store the values in AWS Systems Manager Parameter Store or AWS Secrets Manager.
  • Set the active profile the same way, for example Environment=SPRING_PROFILES_ACTIVE=prod.
  • Do not commit database passwords to Git, even in application.properties.

Step 9: Use a managed database for real data

You can run a database on the same instance, but backups, upgrades and instance failures become your job. For anything beyond a test, use Amazon RDS. Point the Spring datasource URL at the RDS endpoint, and keep the database’s security group closed to everything except the app’s security group.

Other ways to host a Java web application on AWS

The second target keyword asks about hosting in general. These are the main options:

  • EC2 (this guide): the most control, and the most work to patch, monitor and scale.
  • Elastic Beanstalk: upload a jar or WAR and let the platform provision and manage the servers. The Java SE platform routes traffic to port 5000 by default, so set your app’s port to match, or configure the platform to route to the port your app uses.
  • Amazon ECS or AWS App Runner: run the app in a container. The ECS deployment guide shows the container path.
  • AWS Lambda: a good fit for event-driven or lower-traffic APIs. Spring Boot works on Lambda, but cold starts are the trade-off. See the Spring Boot on Lambda tutorial.

An executable jar includes an embedded Tomcat server, so you run it with java -jar. A WAR file needs a separate servlet container, such as Tomcat, installed on the server.

Troubleshooting

  • The site does not load. Check the security group for port 80, the Nginx status (sudo systemctl status nginx) and the app status (sudo systemctl status app). Read the app’s logs with sudo journalctl -u app -n 100.
  • You see the Nginx welcome page. The default server block in /etc/nginx/nginx.conf is answering requests. Comment out that server block, then run sudo systemctl reload nginx.
  • The app crashes with OutOfMemoryError. Lower the heap with -Xmx, close other programs on the instance, or move to a larger instance type. Check memory with free -m.
  • The app fails to start with “Port 8080 was already in use”. Another process is using the port. Find it with sudo ss -ltnp | grep 8080.

Clean up

Stopping the instance pauses compute charges, but EBS volumes and Elastic IPs keep billing. If you are finished, terminate the instance. Then check the EC2 console for leftover volumes, snapshots and Elastic IPs, and delete the ones you no longer need. The guide to avoiding unexpected AWS charges has a full checklist.

Next steps

The complete guide to aws tutorials

AWS Fundamentals: The Core Cloud Computing Services
Read the guide

Keep exploring

Guides from other topics

All topics →