Get started

Overview—What you will do

In this tutorial, you will deploy a containerized app on the Humanitec platform.

An app is a collection of code repositories that have been connected from your version control system. In the context of the platform, these are called modules. You can deploy your apps to one or more environments in your Kubernetes infrastructure. For each environment, you can define a set of configurations, environment variables, and secrets.

Screenshot: A running app on the Humanitec platform

Before you start

GitHub organization account

You need a GitHub account that is part of a GitHub organization that has been linked to the Humanitec platform.

If your organization has already been linked to the platform, then go to the registration form and register with your GitHub account. You will then have access to your organization’s apps on the platform.

Module requirements

If you want to deploy your own modules in your first app, then you must make sure that they meet the following requirements.


Each repository must include a Dockerfile that builds an image of the code. Please note the port that it exposes.

Git tag

Your repository must have a tagged commit that includes the Dockerfile.

In GitHub, you can create this by going to your repository, clicking on Releases, and then clicking on Draft new release.

Use our sample modules

We have a sample frontend and backend that can be deployed with the platform:

Go to the repositories, fork them to your organization’s account, and then push a tag in each.

1. Build the app

  1. Log in to the Humanitec platform.
  2. Enter a name for your new app and click Create.
  3. Now you will see a list of modules that have been connected to the platform from your organization.
    Click the Sync repositories button. When the list has been refreshed, click the Add button next to each module you want to include in the app.
    Screenshot: List of modules while creating an app
    Can’t see your repositories? See the Troubleshooting page for more information.
  4. When you’re ready, click Review.

Now, the platform will create your app and build the images of your modules.

The next screen that loads will display the development environment of your app. Each environment contains a set of configurations for the modules in the app, including module versions and configuration/environment variables.

Click here to read more about modules and how to add them to your app.

2. Expose frontend with public URL

If you intend for your modules to be accessed from outside the cluster (e.g., with a web UI or an API), then you must expose those modules with a public IP address. To do so:

  1. Click on the module you want to expose.
  2. The module configuration screen will load. In the Custom port mapping section, check the box labeled Expose with public URL.
    Screenshot: Expose public URL
  3. Enter the port where your module exposes its content in the container port field.
  4. Click Close to return to the app overview screen.

3. Create environment variables

If your modules rely on environment variables, then you can define them in the Variables section of the module configuration screen.

You can create variable substitutions that resolve to properties of other modules or databases. See the Modules page for more information.

If you’re using the product-fe and product-be repositories, then you must define a number of environment variables. Click on the respective module, scroll down to the Variables section, and create the following:

Variables for product-fe:


Variables for product-be:

  • DATABASE_USER: ${dbs.postgres.username}
  • DATABASE_PASSWORD: ${dbs.postgres.password}
  • DATABASE_PORT: ${dbs.postgres.port}

4. Deploy the app

Click the Deploy to Development button to the right of the modules list.

A modal will appear with a list of the changes that will be deployed. Click the Deploy button to trigger the process.

When your app finishes deploying, the Development environment will be tagged as “Running” in the upper right corner. A public URL will show on each module that you exposed:

Screenshot: Module with public URL

That’s it! Click the URL to access your module.

Click here to read more about the deployment process.

Further development

This tutorial showed you how to get a simple app up and running in a Kubernetes cluster managed by the platform. We recommend reading our documentation on:

Free trial limitations

The following limitations apply to the free trial of the Humanitec platform:

  • Both user access management and source code management are handled through GitHub.
  • You may create no more than 20 apps, with no more than 3 environments each.
    • If you deploy your app to a cluster managed by Humanitec, then each deployed module will have a lifespan of 1 day.
  • You may only create development environments with the free trial.
  • The free trial does not include the role-based access control model. Each member of an organization has full access to all applications for that organization and can delete and edit environments and applications.
  • For ingress, all deployed modules must use the * certificate.