Create Sample App
We'll show you how to spin up and configure your first application in 5 minutes.
IIn this tutorial, you will learn how to create your first application in Humanitec with a development environment, add workloads, configure them, and deploy them to a Kubernetes cluster. To keep things simple, we will use infrastructure (e.g. a Kubernetes Cluster, a database, DNS, container images) that is pre-connected by Humanitec to allow for a quick first test. If you want to learn how to connect your own infrastructure, follow this tutorial.
If you do not have a Humanitec account yet, head over to our website to request a free trial. We will send you instructions on how to start your free trial right away.

The Sample App

We provide two sample images to help you get started with Humanitec. Those are the sample-app as frontend, which serves a React app, and sample-service as backend, which stores data in a PostgreSQL database.
Architecture of sample app provided by Humanitec
You can find the code of the two images in the Humanitec Tutorials Github organization.

Prepare the App

In general, you will need to prepare a number of things before being able to create a new App in Humanitec. Typically, you will need the following elements:
  • Container Images - made available within Humanitec directly from your CI Pipelines
  • Kubernetes Cluster - a Kubernetes cluster to run your workloads in
  • Database Server - to host the databases for your various environments
  • DNS - to allow for web access to your apps
However, in this tutorial, we don't need to prepare any of this because we will use pre-connected infrastructure to keep things simple for the beginning.

Create new App in Humanitec

The first step is to create a new App in Humanitec. This can be done as follows:
  • Navigate to the App Overview Screen. In the tile labeled Create new app, enter a name for your first app, and click Create.
  • The App Details Screen screen will be loaded. By default, you will have an environment called Development without any Workloads.

Add Workloads

Each app, in Humanitec, consists of a number of workloads. In this tutorial, we will use the two images sample-app and sample-service, that are available within Humanitec by default. Your own images would be available the same way once you have connected your build pipelines to Humanitec.
Let's first create the sample-app Workload:
  1. 1.
    In the App Details Screen, select default-module from the Create new workload drop-down and enter the name sample-app when prompted. You cannot change that name later on. Click the ✔ button to accept the name.
  2. 2.
    Click on the newly created sample-app card to enter the Workload Details Screen.
  3. 3.
    Click the + Create new container button and select the sample-app container from the list. Click Create to confirm your selection.
  4. 4.
    Click the < Back to app details button to return to the App Details Screen.
Repeat these steps to create the sample-service Workload.
  1. 1.
    In the App Details Screen, select default-module from the Create new workload drop-down and enter the name sample-service when prompted. You cannot change that name later on. Click the ✔ button to accept the name.
  2. 2.
    Click on the newly created sample-service card to enter the Workload Details Screen.
  3. 3.
    Click the + Create new container button and select the sample-service container from the list. Click Create to confirm your selection.
  4. 4.
    Click the < Back to app details button to return to the App Details Screen.
Sample App with two Workloads in the App Details Screen

Add Resource Dependencies

‌The next important step is adding the required resource dependencies. The sample-service requires a PostgreSQL database. Let's add this resource dependency:
  • Switch to the Untitled draft of your application.
  • Click Edit workload (i.e. in the banner) on the sample-service tile.
  • Select Add resource in the Resource Dependencies section.
  • Select Postgres from the list and give your database the name my-db.
The new resource dependency is now listed in the Workload Details Screen.

Add Environment Variables

Now that we created the required database, we need to connect it to the sample-service. We do this by adding an environment variable:
  • Switch to the Untitled draft of your application
  • Click Edit workload (i.e., in the banner) on the sample-service tile.
  • In the Variables section add a new environment variable with the key CONNECTION_STRING and the value postgresql://${externals.my-db.username}:${externals.my-db.password}@${externals.my-db.host}:${externals.my-db.port}/${externals.my-db.name}. This environment variable will be resolved at deployment time and enables the connection between the sample-service and the database.
The newly created environment variable is now listed in the Variables section.

Expose Frontend with Public DNS

The frontend of our sample application, the sample-app Workload, needs to be exposed with a URL to the public internet. First, we need to add a new DNS resource to the Workload:
  • Switch to the Untitled draft of your application.
  • Click Edit workload (i.e., in the banner) on the sample-app tile.
  • Select Add resource in the Resource Dependencies section.
  • Select DNS from the list and give your DNS connection the name my-dns.
The new resource dependency is now listed in the Workload Details Screen. We now need to configure an Ingress:
  • Click Select DNS resource in the Ingress section.
  • Select my-dns from the drop-down.
  • Click Select path type and select Default from the drop-down.
  • Enter 8080 as port number in the Port field.
  • Click Done, once finished, and click on < Back to app details to return to the App Details Screen.
Ingress configuration for the sample-app

Connect Frontend and Backend

Now that we have both Workloads defined and configured, we need to point the frontend sample-app to the backend sample-service. Here is how you can do this:
  • Switch to the Untitled draft of your application
  • Click Edit workload (i.e. in the banner) on the sample-app tile.
  • In the Variables section add a new environment variable with the key PUBLIC_SERVER_URL and the value http://${modules.sample-service.service.name}:8080. This environment variable will be resolved at deployment time and enables the connection between the sample-app and the sample-service.

Deploy the Application

We are now ready to deploy our first app.‌
  • Switch to the Untitled draft of your application.
  • Click the Deploy button.
  • Enter a Comment in the respective input field and hit Deploy.
When your app finishes deploying, the Development environment will be marked as Running in the upper left corner.
Running Sample App
We can now visit the frontend of our newly created app in a browser. We can retrieve the DNS name for the service as follows:
  • Select the Active deployment in the left-hand column.
  • Click on the sample-app card to open the Workload Details Screen.
  • The generated DNS is available to copy in the Ingress section.
  • Enter the copied URL in a new browser tab and check out the running app.
That’s it! You created your first app in Humanitec.

Next Steps

Now that you created your first sample app in Humanitec, it might be interesting to learn how to connect your own infrastructure. You can follow this step-by-step tutorial to create a version of the sample app that is running on your own infrastructure.
Last modified 1mo ago