The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Edit this Page

Despliegue en Heroku

En esta guía aprenderás a desplegar una aplicación web basada en Quarkus como web-dyno en Heroku.

Esta guía abarca:

  • Actualizar el puerto HTTP de Quarkus

  • Instalar la CLI de Heroku

  • Despliegue de la aplicación en Heroku

  • Deploy the application as container image to Heroku

  • Using Docker

  • Using Podman

  • Deploy the native application as container image to Heroku

Requisitos previos

To complete this guide, you need:

Introducción

Heroku is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. It supports several languages like Java, Ruby, Node.js, Scala, Clojure, Python, PHP, and Go. In addition, it offers a container registry that can be used to deploy prebuilt container images.

Heroku se puede utilizar de diferentes maneras para ejecutar una aplicación Quarkus:

  • Como un programa Java simple que se ejecuta en un contenedor definido por el entorno de Heroku

  • Como un programa Java en contenedor que se ejecuta en un contenedor definido por el proceso de construcción de Quarkus

  • Como un programa nativo en contenedor que se ejecuta en un contenedor definido por el proceso de construcción de Quarkus

All three approaches need to be aware of the port that Heroku assigns to it to handle traffic. Luckily, there’s a dynamic configuration property for it.

Configuración del proyecto común

Esta guía tomará como entrada una aplicación desarrollada en la guía de inicio.

Asegúrate de tener a mano la aplicación de inicio, o clona el repositorio Git: git clone https://github.com/quarkusio/quarkus-quickstarts.git o descargue un archivo. La solución se encuentra en el directorio getting-started.

Heroku can react on changes in your repository, run CI and redeploy your application when your code changes. Therefore, we start with a valid repository already.

Además, asegúrate de que tu CLI de Heroku está funcionando:

heroku --version
heroku login

Preparar el puerto HTTP de Quarkus

Heroku picks a random port and assigns it to the container that is eventually running your Quarkus application. That port is available as an environment variable under $PORT. The easiest way to make Quarkus in all deployment scenarios aware of it is using the following configuration:

quarkus.http.port=${PORT:8080}

This reads as: "Listen on $PORT if this is a defined variable, otherwise listen on 8080 as usual." Run the following to add this to your application.properties:

echo "quarkus.http.port=\${PORT:8080}" >> src/main/resources/application.properties
git commit -am "Configure the HTTP Port."

Desplegar el repositorio y construir en Heroku

The first variant uses the Quarkus Maven build to create the quarkus-app application structure containing the runnable "fast-jar" as well as all libraries needed inside Heroku’s build infrastructure and then deploying that result, the other one uses a local build process to create an optimized container.

For the first variant, two additional files are needed in your application’s root directory:

  • system.properties para configurar la versión de Java

  • Procfile para configurar cómo Heroku inicia su aplicación

Quarkus needs JDK 17, so we specify that first:

echo "java.runtime.version=17" >> system.properties
git add system.properties
git commit -am "Configure the Java version for Heroku."

Vamos a desplegar una aplicación web por lo que necesitamos configurar el tipo web en el Heroku Procfile así:

echo "web: java \$JAVA_OPTS -jar target/quarkus-app/quarkus-run.jar" >> Procfile
git add Procfile
git commit -am "Add a Procfile."

Su aplicación ya debería poder ejecutarse a través de heroku local web.

Vamos a crear una aplicación en tu cuenta y a desplegar ese repositorio en ella:

heroku create
git push heroku master
heroku open

La aplicación tendrá un nombre generado y el terminal debería mostrarlo. heroku open abre su navegador por defecto para acceder a su nueva aplicación.

Para acceder al endpoint REST mediante curl, ejecute:

APP_NAME=`heroku info | grep  "=== .*" |sed "s/=== //"`
curl $APP_NAME.herokuapp.com/hello

Por supuesto, también puedes utilizar la CLI de Heroku para conectar este repositorio a tu cuenta de GitHub, pero esto está fuera del alcance de esta guía.

Desplegar como contenedor

La ventaja de subir un contenedor completo es que tenemos un control total sobre su contenido y podemos incluso elegir desplegar un contenedor con un ejecutable nativo que se ejecute en GraalVM.

En primer lugar, inicie sesión en el registro de contenedores de Heroku:

heroku container:login

Necesitamos añadir una extensión a nuestro proyecto para construir imágenes de contenedores a través del plugin de Quarkus Maven:

mvn quarkus:add-extension -Dextensions="container-image-docker"
git add pom.xml
git commit -am "Add container-image-docker extension."

The image we are going to build needs to be named accordingly to work with Heroku’s registry and deployment. We get the generated name via heroku info and pass it on to the (local) build:

APP_NAME=`heroku info | grep  "=== .*" |sed "s/=== //"`
mvn clean package\
  -Dquarkus.container-image.build=true\
  -Dquarkus.container-image.group=registry.heroku.com/$APP_NAME\
  -Dquarkus.container-image.name=web\
  -Dquarkus.container-image.tag=latest

Push and release the image

You can now push the image and release it.

The initial push is rather big, as all layers of the image need to be transferred. The following pushes will be smaller.

Pushing through Docker

With Docker installed, these steps are simple:

docker push registry.heroku.com/$APP_NAME/web
heroku container:release web --app $APP_NAME

Pushing through Podman

When you want to use Podman as a drop-in-replacement for Docker, you will have some problems because the Heroku CLI depends on Docker and doesn’t support the OCI format. But there are possible solutions for these problems.

Cannot find docker, please ensure docker is installed.

The problem is obviously that the heroku-cli can’t find docker. This is quite easy to resolve, because the podman cli is docker-compatible. We just need to create a symlink from podman to docker:

sudo ln -s $(which podman) /usr/local/bin/docker
Error writing manifest: Error uploading manifest latest to registry.heroku.com/$APP_NAME/web: unsupported

Instead of doing a normal podman push (OCI format) we must use a workaround in order to push and release our app through Podman and the Heroku CLI in the desired format (v2s2 - Docker Image Manifest Version 2, Schema 2). Also skopeo is needed.

CONTAINER_DIR="target/container-dir"
mkdir $CONTAINER_DIR
podman push --format=v2s2 "registry.heroku.com/$APP_NAME/web" dir:$CONTAINER_DIR
skopeo --debug copy dir:$CONTAINER_DIR "docker://registry.heroku.com/$APP_NAME/web:latest"
heroku container:release web --app "$APP_NAME"
rm -rf $CONTAINER_DIR

Check the logs

Puede y debe comprobar los registros para ver si su aplicación se está ejecutando desde el contenedor:

heroku logs --app $APP_NAME --tail

Deploy as native application inside a container

The biggest advantage we take when deploying our app as a container is to deploy a container with the natively compiled application. Why? Because Heroku will stop or sleep the application when there’s no incoming traffic. A native application will wake up much faster from its sleep.

The process is pretty much the same. We opt in to compiling a native image inside a local container, so that we don’t have to deal with installing GraalVM locally:

APP_NAME=`heroku info | grep  "=== .*" |sed "s/=== //"`
mvn clean package\
  -Dquarkus.container-image.build=true\
  -Dquarkus.container-image.group=registry.heroku.com/$APP_NAME\
  -Dquarkus.container-image.name=web\
  -Dquarkus.container-image.tag=latest\
  -Dnative\
  -Dquarkus.native.container-build=true

After that, push and release again using Docker or Podman (see above) and check the logs.

Related content