Application

Before you begin, this documentation assumes the following:

You have created an Environment.

An application is part of a Project within an Environment and is a container unit. Multiple applications can be part of the same Environment, be connected to a set of dependencies (databases and other services), and can communicate with other applications within the same Environment.

Qovery allows you to create and deploy applications from two different sources: Git Repository or Container Registry

Deploying from a Git Repository

In this configuration, Qovery will pull the code from the chosen repository, build the application and deploy it on your kubernetes cluster.

The list of Git repositories available during the setup is strictly tied to the permissions of your git account (by default Qovery can access all your repositories). If you want to restrict the Qovery access only to a few repositories, user the GitHub Qovery Application (only for Github).

Deploying from a Container Registry

In this configuration, Qovery will pull the chosen container registry an image you have pre-built and deploy it on your kubernetes cluster.

To improve the security and avoid deploying images from non-authorized registries, we have decided to restrict the list of Container Registry you can use during the setup process. Only an administrator with the right permissions can manage it from the Container Registry Management page

Create an Application

1. Go into the chosen environment and press the "New Service" button and then the "Create application" button

   

2. Select the following fields:

   • Application Name: give a name to your applicaiton
   • Application Source: Chose between Git Repository or Container Registry, depending on the source location of your application

   If you want to deploy an application from a Git Repository you will have to select:

   • Git Repository: Select the git provider hosting your code (it can be hosted on GitHub, GitLab or Bitbucket).
   • Branch: Select branch that Qovery should use to deploy your application
   • Root Application Path: base folder in which the application resides in your repository
   • Build Mode: chose between Docker or Buildpack. For more information, go to this section

   If you want to deploy an application from a Container Registry you will have to select:

   • Registry: select the container registry storing the image of your application. Note: only pre-configured registry are available in this list, check the Container Registry Management page for more information.
   • Image name: the name of the image to be deployed with this application (example: postgres)
   • Image tag: the tag of the image to be deployed with this application (example: 12)
   • Image Entrypoint: the entrypoint to be used to launch your applicaiton (not mandatory)
   • CMD Arguments: the arguments to be passed to launch your applicaiton (not mandatory). We expect the format to be an array. Example ["rails", "-h", "0.0.0.0", "-p", "8080", "string"]

   The tag 'latest' is not supported, please use a specific tag.

3. Within this section, you will need to define the resources to be assigned to your applicaiton at run time.

   • vCPU: the vCPU assigned to each instance of your application. The default is 500m (0.5 vCPU).
   • RAM: the amount of RAM assigned to each instance of your application. The default is 512MB.
   • Number of instances (Application Auto-scaling): select the minimum and the maximum number of instances of your application that can run within your cluster. The number of instances running at an insant t is automatically managed by Kubernetes (Application auto-scaling) and it is based on real-time CPU consumption. When your app goes above 60% of CPU consumption for 5 minutes, your app will be auto-scaled and more instances will be added. It is transparent. Qovery runs your application on Kubernetes and relies on metrics-server service to auto-scale your app.

   Please note that in this section you configure the CPU/RAM allocated by the cluster for your application and that cannot consume more than this value. Even if the application is underused and consume less resources, the cluster will still reserve the selected amount of CPU/RAM.

   

4. You can now define one or more ports for your Application. Most of the application needs to be accessed by other services inside or outside your environment over different L7/L4 protocols. Today Qovery supports the following protocols:

   • HTTPS (Select this protocol if you need to run Websockets)
   • gRPC
   • TCP
   • UDP

   By default ports are accessible only from inside your environment. You can also expose them publicly, making them accessible over the public network via a dedicated public domain that will be assigned to your application by Qovery during the deployment. Note that HTTPS/gRPC ports are alwasy exposed over the port 443.

   

   Important Informations

   • Most of the Kubernetes Health Checks]docs.using-qovery.configuration.service-health-checks are based on the port declared in this section. Make sure you declare the right port and that you configure the health checks properly.
   • Connections on public ports are automatically closed after 60 seconds. If you want to implement long living connection (like for websockets) please make sure to use the rigth ingress timeouts in the advanced settings section
   • Exposing publicly TCP/UDP ports requires to create a dedicated load balancer and it takes a few minutes before having it ready (~15 minutes). Note also that this has a direct impact on your cloud provider bill.
   • You can configure your application to use the PORT environment variable by adding the PORT on your application env variables page.
   • A Note on Listening IPs: It's best for your application to listen on 0.0.0.0:$PORT. While most things work with 127.0.0.1 and localhost, some do not (NodeJS for example)

5. (Optional) If a port has been defined for your application, you can define the health check probes to run in order to verify the state of your application

   To know more about how to configure your Liveness and Readiness probes, have a look at the health-checks section

6. You will find a recap of your application setup and you can now decide to: 1. Go back to one of the previous steps and change your applicaiton settings 2. Create your application without deploying it 3. Create and deploy your application

   

How was it? Did this tutorial work?  Yes  No

Deployment Management

Have a look at the Deployment Management section for more information.

Configuration

Once created, you can access the configuration of an application at any time via the Settings tab available on the application section

You can find below the description of each of the tabs available in this section

General

General settings section allows you to set up your application name and the source code location (git repository or image registry) .

Git Repository

If your application is built and deployed from a git repository, within this section you can:

• Modify the git provider where your code is stored (it can be hosted on GitHub, GitLab or Bitbucket).
• Modify the branch that Qovery should use for deploying your application
• Modify Root Application Path - base folder in which the application resides in your repository

Qovery supports mono repositories. See our advanced guide for more details.

If your repository contains private submodules using SSH protocol, you will need to add a secret beginning with GITSSH_KEY, containing a private SSH key with access rights to your sumbodules repositories.

Secret names examples:

• GIT_SSH_KEY_GITHUB
• GIT_SSH_KEY_GITLAB
• GIT_SSH_KEY_MYAPP

Container Registry

If your application is deployed from an image registry, within this section you can modify:

• Registry: select the container registry storing the image of your application. Note: only pre-configured registry are available in this list, check the Container Registry Management page for more information.
• Image name: the name of the image to be deployed with this application (example: postgres)
• Image tag: the tag of the image to be deployed with this application (example: 12)
• Image Entrypoint: the entrypoint to be used to launch your applicaiton (not mandatory)
• CMD Arguments: the arguments to be passed to launch your applicaiton (not mandatory). We expect the format to be an array. Example ["rails", "-h", "0.0.0.0", "-p", "8080", "string"]

The tag 'latest' is not supported, please use a specific tag.

Build Mode

This option is available only if you have selected "Git Repository" as source

Option 1: Buildpacks

To simplify the application build for the developer, Qovery supports Buildpacks out of the box. Buildpacks determine the build process for an app and which assets and runtimes should be made available to your code at runtime. If your complex apps are running multiple languages, you can also use multiple buildpacks within a single app. Meaning, as a developer, you don't need to write a Dockerfile to build and run your app. Qovery Buildpacks takes care of everything for you.

Supported languages

language	version
Node.JS	any
Clojure	any
Python	any
Java	any
Gradle	any
JVM	any
Grails	any
Scala	any
Play	any
PHP	any
Go	any

You don't find a cool language? Suggest us to support it

Option 2: Dockerfile

Qovery runs your application within the Container technology. To build and run your application, you need to provide a valid Dockerfile.

Valid NodeJS Dockerfile

FROM node:13-alpine
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app
COPY . .
RUN npm install
EXPOSE 3000
CMD node ./bin/www

After creating a Dockerfile, specify the location of your Dockerfile in Dockefile path field.

Configuration from above will make Qovery look for the Dockerfile in /timescale/Dockerfile path of your repository (Root Application Path + Dockerfile Path).

Resources

CPU

To configure the number of CPUs that your app needs, adjust the setting in the Resources section of the application configuration.

Default is 500m (0.5 vCPU).

Please note that in this section you configure the CPU allocated by the cluster for your application and that cannot consume more than this value. Even if the application is underused and consume less resources, the cluster will still reserve the selected amount of CPU.

RAM

To configure the amount of RAM that your app needs, adjust the setting in Resources section of the application configuration.

Default is 512MB.

Please note that in this section you configure the CPU allocated by the cluster for your application and that cannot consume more than this value. Even if the application is underused and consume less resources, the cluster will still reserve the selected amount of CPU. If your application requires more RAM than requested, it will be killed by the kubernetes scheduler.

Auto-scaling

Application auto-scaling is based on real-time CPU consumption. When your app goes above 60% of CPU consumption for 5 minutes, your app will be auto-scaled and more instances will be added. It is transparent. You can adjust the minimum and maximum of instances you need in your application settings. Qovery runs your application on Kubernetes and relies on metrics-server service to auto-scale your app.

Storage

Block Storage

The default filesystem for applications running on Qovery is ephemeral. Application data isn’t persisted across deploys and restarts, which works just fine for most apps because they use managed databases to persist data.

However, many applications need persistent disk storage that isn’t ephemeral. These include:

• Blogging platforms and CMSs like WordPress, Ghost, and Strapi.
• Collaboration apps like Mattermost, GitLab, and Discourse.

This is where Qovery block Storage comes in. Qovery applications can use storage to store data that persists across deploys and restarts, making it easy to deploy stateful applications.

For most use cases, it is better to use Object Storage instead of Block Storage.

Use cases

✅ Good use cases

• For I/O intensive applications (E.g. database)
• To store temporary files

❌ Bad use cases

• To store file > 1 TB
• To expose files from an application (E.g. images)

Types of Block Storage

Qovery Storage supports:

Type	Max IOPS	Max Throughput	Min Size	Max Size	Use cases
fast_ssd	64000	1GB/s	5GB	10GB Community / 1TB paid plans	Critical business applications that require sustained IOPS like databases

Configuration

You can set up your Block Storage in Storage section of your application configuration.

Storage can be added only if the application has never been deployed before AND if it runs only with one instance (check the Resources section)

Ports

Within this section you can define the port exposed by your application to the other services or even over the internet. You can edit the existing ports or declare new ones by specifying:

• Application port: this is the port exposed internally by your application for the other services.
• Protocol: you can select the protocol used by your application : HTTP (for both standard HTTP or websocket communications), gRPC, TCP, UDP.
• Publicly exposed: it allows you to expose over the public network your service. A public domain will be assigned to your application during the deployment (see Domain section)
• If Publicly Exposed is selected:
  • External port: it is the port that can be used to access this service over the internet (when exposed publicly). Note that for HTTP and gRPC the port is set by default to 443.
  • Port Name: it is the name assigned to the port. When multiple ports are exposed publicly, its value is used to route the traffic to the right port based on the called subdomain (which will contain the port name value). Since each port is exposed on the port 443, having a different subdomain is the only way to have multiple ports exposed over the internet. If not set, the default value is p<portNumber> (see Domain section for more information)

Important Informations

• Most of the Kubernetes Health Checks]docs.using-qovery.configuration.service-health-checks are based on the port declared in this section. Make sure you declare the right port and that you configure the health checks properly.
• Connections on public ports are automatically closed after 60 seconds. If you want to implement long living connection (like for websockets) please make sure to use the rigth ingress timeouts in the advanced settings section
• Exposing publicly TCP/UDP ports requires to create a dedicated load balancer and it takes a few minutes before having it ready (~15 minutes). Note also that this has a direct impact on your cloud provider bill.
• You can configure your application to use the PORT environment variable by adding the PORT on your application env variables page.
• A Note on Listening IPs: It's best for your application to listen on 0.0.0.0:$PORT. While most things work with 127.0.0.1 and localhost, some do not (NodeJS for example)

Health Checks

To know more about how to configure your Liveness and Readiness probes, have a look at the health-checks section

Domains

The Domain section allows you to define a custom domain for your application.

For each port publicly exposed, a domain is automatically assigned by Qovery to your application. Qovery will manage for you the networking and the TLS configuration for these domains.

domain example: p80-zdf72de72-z709e1a88-gtw.za8ad0657.bool.sh

Special Case - Preview Environment For each port exposed publicly, an additional domain will be created with the following pattern portName-prId-srvName-envSourceName.cluster_domain:

• portName: is the port name, as explained above
• prID: is the id of the PR that has generated the preview environment
• srvName: is the name of the service
• envSourceName: is the name of the blueprint environment that has created the current preview environment

domain example: p80-123-frontend-blueprint.za8ad0657.bool.sh

Note:

• each service deployed on the same cluster will have the same root domain assigned (example: za8ad0657.bool.sh)
• the first characters of the domain assigned to the application is based on the portName given to the port (See the port section
• a default domain (without the portName) is assigned to the default port(See the port section). Example zdf72de72-z709e1a88-gtw.za8ad0657.bool.sh

If you want to customize the domain assigned to your application press the Add Domain button.

In this section, you can assign your custom domain via CNAME or just change the sub-domain assigned to your service.

This configuration will be automatically removed on every cloned environment or preview environment in order to avoid domain collision.

Configuring a domain via CNAME

You can configure your DNS by adding a CNAME record so that your app will be accessible through your custom domain. Qovery will handle for you the network configuration and the TLS certificate.

We prepared a guide and video tutorial that explains how to set up your custom domain.

Change the assigned sub-domain

You can specify a different sub-domain for your application as long as it belongs to the assigned cluster domain (see above). Example:

• your current domain is zdf72de71-z709e1a85-gtw.za8ad0659.bool.sh (so your assigned cluster domain is za8ad0659.bool.sh)
• you can enter a new custom domain myfrontend.za8ad0659.bool.sh (since it is a subdomain of the cluster domain)

The application will now be accessible from both the default and the new custom domain.

Qovery does not check collision in the domain declaration. Make sure you assign a unique subdomain within your cluster.

Connecting to a database

To know how to access your database from your application, have a look at the database section.

Connecting to another application

To know how to access your database from your application, have a look at the database section.

Environment Variable

To learn how to set up environment variables in your projects and applications, navigate to configuring Environment Variables section.

Secrets

To learn how to set up secrets in your projects and applications, navigate to configuring Secrets section.

Logs

To learn how to display your application logs, navigate to logs section

SSH

To connect to your application via SSH, please use the via the Qovery SSH command available on our CLI.

Clone

You can create a clone of the service via the clone feature. A new service with the same configuration (see below for exceptions) will be created into the target environment.

The target environment can be the same as the current environment or even another one in a completely different project.

Important information

Not every configuration parameter will be copied within the new service for consistency reasons. The configuration is fully or partially copied depending on the target environment:

• same environment:
  • custom domain: this setup is not copied into the new service (to avoid collision)
• another environment:
  • custom domain: this setup is not copied into the new service (to avoid collision)
  • environment variable: aliases defined on environment variables are not copied (since the aliased env var might not exist)
  • deployment pipeline: stage setup is not copied (since the target stage might not exist)
  • number of instances: if the target environment runs on a Qovery EC2 cluster, the max number of instances is set to 1 (Qovery EC2 constraint)

Please check the configuration of the new service before deploying it.

Delete an Application

1. Choose your application

2. In the application overview, click on the 3 dots button and remove the application.

   

How was it? Did this tutorial work?  Yes  No