Skip to main content
A Quarkus application runs on Sevalla on the JVM, as an application built from your Git repository: Ingot, Sevalla’s builder, recognizes the Quarkus Maven plugin in pom.xml, builds Quarkus’s fast-jar with the project’s Maven wrapper, and the web process starts it with java -Dquarkus.http.port="$PORT" -jar /app/quarkus-run.jar, so Quarkus listens on the port that Sevalla sets in the PORT environment variable.

At a glance

Environment variables

The application needs no environment variables of its own. It reads PORT, which Sevalla sets to the web process port.

Before you begin

  • A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
  • A Java 25 JDK on your computer. The project’s Maven wrapper downloads Maven, so you don’t install it.

Create the project

Generate the project on code.quarkus.io: a Maven project for Java 25 with Quarkus REST and SmallRye Health.
code.quarkus.io uses the recommended Quarkus platform release, 3.40.1.1 when this guide was written, and adds the Maven wrapper (mvnw), which runs Maven 3.9.16. It also adds Quarkus’s Dockerfiles in src/main/docker, which package a build you’ve already run, and a .dockerignore for them that leaves out everything but target/. Ingot builds from source, so it doesn’t apply that .dockerignore. Add a resource for the home page:
src/main/java/com/example/storefront/HelloResource.java
The generated .gitignore already keeps the build output in target/ and a local .env out of the repository.

Prepare the project for Sevalla

Replace the empty src/main/resources/application.properties with:
src/main/resources/application.properties
The rest of the project already has what Ingot needs: From these files, Ingot:
  • Builds on the Java 25 JDK with ./mvnw --batch-mode --no-transfer-progress -DskipTests package. Tests don’t run in the image build; run them in CI.
  • Copies Quarkus’s fast-jar, the target/quarkus-app folder, into the image, dependencies first, so a code change leaves the dependency layer of the image as it is.
  • Runs it on the Java 25 runtime (JRE) as user 1000:1000, with JAVA_TOOL_OPTIONS set to -XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError. See Size the JVM memory.
Ingot runs Quarkus on the JVM only: it doesn’t build a native executable, and stops the build when quarkus.native.enabled is true. Run ./mvnw quarkus:dev and open http://localhost:8080 to check the application locally. Then commit everything and push it to your Git provider:

Deploy to Sevalla

These steps build with Ingot. To build from your own Dockerfile instead, see Deploy with a Dockerfile.
1

Create the application

In the sidebar, click Applications, then click Create > Application. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch. Under Location, choose a Data center. Keep the Size at H1 or choose a larger one, then click Create application. The application opens on its Overview tab with the status Not deployed yet: creating an application doesn’t deploy it.
2

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.
3

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

Verify the deployment

  1. On the Deployments tab, click the deployment. Its Build log shows Ingot’s build plan: Java 25 from maven.compiler.release in pom.xml, Maven from the wrapper, and the start command for Quarkus.
    Build log
    The warning is about the .dockerignore that code.quarkus.io generated: Ingot skips it and builds from the whole repository.
  2. Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
  3. Click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The page shows Hello from Quarkus on Sevalla.
The application header with its name, Running status, repository, branch and the domain that opens the applicationThe application header with its name, Running status, repository, branch and the domain that opens the application
/q/health/ready returns a JSON document with "status": "UP". The application’s runtime logs show Listening on: http://0.0.0.0:8080 and Profile prod activated. If the deployment fails, read its build log, then see Troubleshoot. To check the deployment from a terminal or an AI agent, read its status with Get deployment (getDeploymentV3) until it’s success, and its build log with Get application deployment logs (getApplicationDeploymentLogsV3), as in Deploy with the API. Then request the endpoints:
Get application runtime logs (getApplicationRuntimeLogsV3) with search finds the address Quarkus listens on:

Add a health check

SmallRye Health serves Quarkus’s readiness check at /q/health/ready. A readiness probe on it makes each new instance wait until Quarkus has started before it gets traffic, so a deployment switches over only to instances that serve requests.
1

Open the web process

On the application’s Processes tab, click ⋯ on the Web process, then click Update process.
2

Turn on the readiness probe

Under Health checks, turn on Readiness probe and set the Path to /q/health/ready. Keep the Port at the web process’s port, 8080 unless you changed it.
3

Save and deploy

Click Update process, then click Deploy in the undeployed changes bar at the bottom of the page.
The deployment’s status changes to Deployed once the new instance answers the probe. See Health checks for every probe setting. Deploy with the API sets the same probe. Get process (getProcessV3) returns it in readiness_probe:

Shut down gracefully

When Sevalla stops an instance, during a deployment, a restart or a scale-down, it waits 5 seconds, sends SIGTERM, and stops the instance if it’s still running 30 seconds after the shutdown began. See How processes run. Without quarkus.shutdown.timeout, Quarkus stops at once on SIGTERM and closes the connections of requests still in progress. With it, Quarkus waits for the requests in progress, up to 20 seconds, which ends within the 25 seconds between SIGTERM and the end of the shutdown. While it waits, the log shows Waiting for HTTP requests to complete, then All HTTP requests complete. The old instance’s runtime logs end with storefront stopped in, followed by the time it took, on every deployment. Set the timeout in application.properties: set only as an environment variable, it doesn’t turn graceful shutdown on.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write your own when you want full control of the image: the base image, the system packages and every layer. Add a Dockerfile to the root of the repository, and replace the .dockerignore that code.quarkus.io generated:
Dockerfile
.dockerignore
The .dockerignore keeps the Git history, a local build in target/, local environment files and logs out of the build. The generated one leaves out everything but target/, for Quarkus’s Dockerfiles in src/main/docker, so a Dockerfile that builds from source can’t find pom.xml with it. Commit and push both files. Ingot doesn’t use the Dockerfile, so you can keep it in a repository that builds with Ingot. Ingot adds the .dockerignore patterns to its own, and its build plan shows Ignored 4 patterns from .dockerignore; none of them matches a file the Ingot build needs. Then switch the application to the Dockerfile build strategy:
1

Choose the Dockerfile build strategy

On the application’s Settings tab, in the Build strategy section, click Update build strategy. Click Dockerfile, keep the Dockerfile path Dockerfile and the Docker context ., then click Update build strategy.
2

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.
The deployment’s build log shows 📦 Building and pushing docker image using Dockerfile... instead of Ingot’s build plan, and its Dockerfile tab shows your file. When the deployment’s status is Deployed, the domain shows Hello from Quarkus on Sevalla again. On the next deployment after a code change, the build log shows CACHED for the go-offline step. See Dockerfile. With the API, Update application (updateApplicationV3) switches the build strategy. Then deploy and wait as in Deploy with the API:
The CLI does the same with sevalla apps update $APP_ID --build-type dockerfile --dockerfile-path Dockerfile. The new deployment’s build log names the Dockerfile build:

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment; otherwise, click Deploy now for each change. Each deployment builds the image, then replaces the web process’s instances. See Deployments.

Use environment variables

Add configuration on the application’s Environment variables tab, and read it in application.properties with a placeholder, as quarkus.http.port=${PORT:8080} reads PORT. Variables apply at the next deployment. With Ingot, variables marked Available during buildtime also reach the Maven build; with a Dockerfile, they arrive as build arguments, which a stage reads only after an ARG line for each one. Keep quarkus.shutdown.timeout in application.properties: as an environment variable alone, it doesn’t turn graceful shutdown on. See Environment variables.

Add a custom domain

To serve the application from your own domain, such as shop.example.com, add the domain on the application’s Domains tab and create the DNS records that Sevalla shows. Custom domains need a web process larger than H1, so scale the web process first. See Custom domains.

Troubleshoot

For more causes, see Troubleshoot Ingot builds and Troubleshoot builds and deployments.

Deploy with the API

These calls make the same deployment as Deploy to Sevalla and Add a health check, in an order that a script or an AI agent runs as it is. Each step names the Sevalla API operation, then the CLI command and the MCP server tool that do the same. You need:
  • An API key with the Company developer role, or the APP:CREATE, APP:READ and APP:UPDATE permissions, in the SEVALLA_API_KEY environment variable. The CLI reads the key from SEVALLA_API_TOKEN.
  • The repository on a Git provider that’s connected to your Sevalla account. See Git providers. Creating the application checks it: when Sevalla can’t read the repository, the call returns 400 with Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access., followed by where to grant access.
  • curl and jq.
1

Choose the location

List clusters (listClustersV3) returns the locations your company can use, each with its id, the display_name that the dashboard shows and its region ID in location. Keep the ID of the one you want by its region ID, such as eu-frankfurt-1 for Frankfurt, Germany. Locations lists them all:
CLI: sevalla resources clusters. MCP: get_platform_options.
2

Create the application

Create application (createApplicationV3) creates the application with a web process. It builds with Ingot (build_type is ingot) and isn’t deployed yet:
CLI: sevalla apps create --name storefront --cluster $CLUSTER_ID --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main. MCP: create_application with deploy set to false.
3

Find the domain

List application domains (listApplicationDomainsV3) returns the domain that Sevalla gives the application. It appears a few seconds after the application is created, so ask until it’s there:
CLI: sevalla apps domains list --app-id $APP_ID. MCP: get_application.
4

Find the web process

List processes (listProcessesV3) returns the web process that the application was created with:
CLI: sevalla apps processes list --app-id $APP_ID. MCP: get_application.
5

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the sizes by name, in lowercase:
CLI: sevalla resources process-types. MCP: get_platform_options.
6

Set the size and the readiness probe

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets the size and adds the readiness probe from Add a health check, with the dashboard’s default timings. Send timeoutSeconds: a probe without it gets 120 seconds, where the dashboard sets 1.
CLI: sevalla apps processes update $WEB_ID --app-id $APP_ID --resource-type $H1_ID sets the size; the CLI can’t set probes. MCP: scale_process with size_id for the size, and sevalla_api_update with updateProcessV3 and the same body for the probe.
7

Turn on auto-deploy

Update application (updateApplicationV3) turns on automatic deployments for every push to the branch:
CLI: sevalla apps update $APP_ID --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3.
8

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit on the branch:
CLI: sevalla apps deployments trigger $APP_ID --branch main. MCP: trigger_deployment.
9

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting and inProgress while it runs, then success, failed, cancelled or skipped. Poll it until the status is final, for up to 30 minutes:
CLI: sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.
10

Read the build log

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, oldest line first: the build plan from Verify the deployment, the build and the rollout. When the status is failed, the last lines say why.
CLI: sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment_logs.
11

Check the application

Request the home page from the application’s domain:
Then run the other checks in Verify the deployment.