Quick Start
Spring Boot

Deploy a Spring Boot App

This quickstart guide explains how to deploy a Spring Boot (opens in a new tab) application written in Java to Koyeb using:

  1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
  2. Pre-built containers you can deploy from any public or private registry.

Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can "just run".

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You will need:

You can deploy and preview the Spring Boot application from this guide by clicking the Deploy to Koyeb button:

Deploy to Koyeb (opens in a new tab)

Consult the repository on GitHub (opens in a new tab) to view this example application.

Create the Spring Boot app

Get started by creating a basic Spring Boot application.

Download and extract a project template

Visit this spring initializer page (opens in a new tab).

This URL populates the following configuration for initialization:

  • Project: Maven
  • Language: Java
  • Group: com.koyeb
  • Artifact: example-spring-boot
  • Packaging: Jar
  • Dependencies: Spring Web

Click GENERATE and then save the provided .zip file to your local computer.

Unzip the .zip file to access the project files, remove the .zip archive, and enter the new project directory. The link above generates a file called example-spring-boot.zip, so we will run:

unzip example-spring-boot.zip
rm example-spring-boot.zip
cd example-spring-boot

The most important project files and directories are:

  • ./mvnw: A wrapper for the Maven command for Linux and macOS. This calls a vendored version of Maven stored in .mvn/wrapper/maven-wrapper.jar instead of the system version.
  • ./mvnw.cmd: This is an equivalent wrapper script for Windows.
  • ./pom.xml: The project management file for defining dependencies and metadata.
  • ./src/main/java/com/koyeb/examplespringboot/ExampleSpringBootApplication.java: The main application file for the project.
  • ./src/main/resources/application.properties: Describes environment-specific configuration details for the project.

Modify the application code

Here, you will replace the application code generated by the project template with a basic "hello world" application.

In your editor, open the ExampleSpringBootApplication.java file in the ./src/main/java/com/koyeb/examplespringboot directory in your editor. Replace the current contents with the following code:

./src/main/java/com/koyeb/examplespringboot/ExampleSpringBootApplication.java
package com.koyeb.example_spring_boot;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
@SpringBootApplication
@RestController
public class ExampleSpringBootApplication {
    public static void main(String[] args) {
      SpringApplication.run(ExampleSpringBootApplication.class, args);
    }
 
    @GetMapping("/")
    public String hello() {
      return String.format("Hello world!");
    }
}

This code imports the necessary classes and interfaces to make a web application from the Spring Boot and Spring Web packages. It defines one class with annotations to mark it as a Spring Boot application and REST controller. This class has main method to bootstrap the Spring Boot capabilities as well as a hello method that is mapped to respond to requests to the / endpoint with "Hello world!".

You can run the new application by typing the following from the root project directory:

./mvnw spring-boot:run

Maven builds the application and runs it according to the project configuration. Once the application is running, visit http://127.0.0.1:8080 in your browser or with curl. You will get a "Hello world!" message as the response.

Press CTRL-C when you are finished to stop the application.

Modify the configuration to make the port configurable

This "hello world" Spring Boot app currently runs on port 8080, but you can configure it to run on the port specified by the PORT environment variable. The following code uses port 8080 as the default fallback value if the PORT variable is unset.

Open the application.properties file in the ./src/main/resources directory. Add the following under the current code to set the project's port configuration:

./src/main/resources/application.properties
server.port=${PORT:8080}

This configures Tomcat (opens in a new tab), the application server, to check the PORT environment variable for the port to run on.

Confirm that port 8080 is used when the PORT environment variable is unset:

./mvnw spring-boot:run

Your application will be served on http://127.0.0.1:8080.

Press CTRL-C to stop the application, and then test modifying the port value by passing the PORT variable:

PORT=5555 ./mvnw spring-boot:run

The application is now available on port 5555 instead of 8080, which confirms that you can dynamically configure the application port.

Create a Dockerfile for the project (Optional)

You can build and run our Spring Boot project on Koyeb using the native Java buildpack. Optionally, you can build from a Dockerfile for more control. To make it possible to build a container image for the application, you need to create the Dockerfile. You will also define a .dockerignore file to tell the builder what files to skip when creating the image.

Define a .dockerignore file in your main project directory. Inside, paste the following contents:

.dockerignore
.git
.gitignore
Dockerfile
.dockerignore
target

This file tells Docker to not include Git files, the Docker files themselves, and any build artifacts placed in the target directory. This helps ensure that the image we build is not bloated and that the build completes faster.

Create a new file called Dockerfile within the main project directory. Inside, paste the following contents:

Dockerfile
# Build stage
FROM eclipse-temurin:19-jdk-alpine AS builder
 
WORKDIR /app
COPY . .
RUN ./mvnw package
 
# Run stage
FROM eclipse-temurin:19-jdk-alpine AS runner
 
WORKDIR /app
COPY --from=builder /app/target/*.jar app.jar
 
CMD ["java", "-jar", "app.jar"]

This Dockerfile uses a multistage build (opens in a new tab) to separate the build steps from the final image environment. This creates a more streamlined image and allows us to tightly control what files are included in the final image.

Both stages are based on the Alpine version of the eclipse-temurin image (opens in a new tab). The build stage copies all of the files over to the image and builds the package. The compiled artifact is then copied to the runtime image where it is executed directly with the java executable.

If you have Docker installed locally, you can build and test the image on your computer and optionally upload it to a registry. You can deploy container images from any container registry to Koyeb.

You can also build the Dockerfile (directly from the repository when deploying)[#deploy-to-koyeb-using-git-driven-deployment], which is useful as a way of automatically deploying when changes occur.

Push the project to GitHub

In the project directory, initialize a new Git repository by running the following command:

git init

Download a basic .gitignore file designed for Maven projects from GitHub:

curl -L https://raw.githubusercontent.com/github/gitignore/main/Maven.gitignore -o .gitignore

Specify the Java runtime version to use so that the Koyeb Java buildpack executes the project with the correct version:

echo "java.runtime.version=19" > system.properties

Next, add the project files to the staging area and commit them. If you don't have an existing GitHub repository to push the code to, you can create a new one and run the following commands to commit and push changes to your GitHub repository replacing <YOUR_GITHUB_USERNAME> and <YOUR_REPOSITORY_NAME> with the values from your GitHub repository:

git add :/
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Deploy to Koyeb using git-driven deployment

Once the repository is pushed to GitHub, you can deploy the Spring Boot application to Koyeb. Any changes in the deployed branch of your codebase will automatically trigger a redeploy on Koyeb, ensuring that your application is always up-to-date.

To deploy the Spring Boot app on Koyeb using the control panel (opens in a new tab), follow the steps:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public Spring Boot example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page: https://github.com/koyeb/example-spring-boot.
  4. Choose the Builder for your project. You can use either a Dockerfile or buildpack for this repository.
  5. Name the App and Service. For example, example-spring-boot.
  6. Click the Deploy button.

This creates a Koyeb App and Service which builds and deploys your application on Koyeb. You can access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Deploy to Koyeb from a container registry

If you chose to build a container image for the Spring Boot application, you can optionally deploy the application from a container registry instead of from GitHub.

To deploy a pre-built Spring Boot container image on Koyeb using the control panel (opens in a new tab), follow these steps:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select Docker as the deployment option.
  3. Choose the container image and tag from your registry and click Next to continue.
  4. Name the App and Service. For example, example-spring-boot.
  5. Click the Deploy button.

This creates a Koyeb App and Service which builds and deploys your application on Koyeb. You can access your application running on Koyeb by clicking the URL ending with .koyeb.app.

What's next

For more examples of Spring Boot and Java applications deployed on Koyeb, check out these tutorials:

To learn more about the features available for your apps, check out the following documentation:

RustStreamlit