Quickstart: Deploy your first app

This section provides a tutorial to deploy a first simple containerized app on Humanitec. It also explains how to configure modules and how to connect your CI pipelines to Humanitec.

Overview—What you will do

In this tutorial, you will learn how to create your first app with a development environment, add some container images from your Continuous Integration (CI) pipeline, configure them, and deploy them to a Kubernetes cluster managed by Humanitec.

Screenshot: A running app on Humanitec


To get started with Humanitec, your app must meet the following requirements:

  • The services you wish to deploy must be built into Docker images.
  • You must have a Continuous Integration (CI) pipeline. We have detailed instructions for:

If you don’t yet have any Docker images, you can use our sample-app and sample-service images that are available in your organization on Humanitec.

1. Create an app

  1. Log in to Humanitec. In the field labeled Create new app, enter a name for your first app, and click Create.
  2. The environment overview screen will load. By default, you will have an environment called Development.

2. Connect your CI pipeline

If you wish to use our sample frontend and backend images skip this step and proceed with Add modules to your app.

  1. In the box labeled Create new module, click Select container image, and select Manage images.

    Screenshot: Manage images
  2. The Image management screen will load. Click the button that corresponds with the CI pipeline you want to connect.

    Screenshot: Select CI pipeline on image management screen
  3. Follow the instructions in the modal that appears. In general, you will have to add the Humanitec API token as a variable in your pipeline, and you will need to add a step to the build process in your CI pipeline configuration file.
  4. Now you must trigger a build of your images (e.g., by pushing tags in Bitbucket). The images will be pushed to the Humanitec registry and will be available to add to your environments.
  5. Each image whose build you triggered should appear in the list. In the screenshot below, images product-be and product-fe were pushed to Humanitec through a Bitbucket pipeline.

    Screenshot: Image list on image management screen
  6. Click the Close button in the upper right corner to return to your app.

3. Add modules to your app

  1. In your app overview screen, on Create new module, click Select container image. Choose your image from a CI pipeline or select Humanitec sample images: first, sample-app, then sample-service.
  2. Change the name if needed and click the checkmark to create a module.
  3. You will immediately see your module configuration screen. A module will have one container created based on your selected image. You can add more container images if required.

    Screenshot: App before first deployment

4. 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. In the Public URL section, check the box labeled Expose with public URL.

    Screenshot: Expose public URL
  2. Enter the port where the module exposes its content in the Service port field.
  3. Click Close to return to the app overview screen

See Configure Modules if you wish to find out how to add containers, change image versions, configure variables, and add databases.

5. Deploy the app

  1. In your environment view click the Deploy to Development button to the right of the modules list.
  2. 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 left corner. A public URL will show on each module that you exposed:

Screenshot: Link to public URL

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

Click here to read more about deployments.

Free trial limitations

The following limitations apply to the free trial of Humanitec:

  • Each deployed module will have a lifespan of 1 day.
  • All publicly exposed apps will be exposed under a *.newapp.io domain.