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 thant3.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
.pemfile. - 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}inapplication.properties. - Set variables in the systemd unit with
Environment=lines, or load them from a file withEnvironmentFile=. 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 withsudo journalctl -u app -n 100. - You see the Nginx welcome page. The default server block in
/etc/nginx/nginx.confis answering requests. Comment out thatserverblock, then runsudo 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 withfree -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
- Try a serverless version with the Spring Boot on AWS Lambda tutorial.
- Set up the database with the Amazon RDS guide.
- For an overview of the services used here, read the AWS fundamentals guide.