The Humanitec platform’s primary functions are to help you develop containerized apps and deploy them to your Kubernetes infrastructure. The apps derive their code from repositories linked from your GitHub organization. The platform imports these repositories as modules. Users in your organization can deploy these modules to your Kubernetes infrastructure in the context of apps.

This section describes how modules work and how to configure them.

What is a module?

A module is a code repository that has been linked to the platform from your GitHub organization.

When you create an app, you can choose one or more modules to add:

Screenshot: List of modules to add to your app

Your modules will be added to an environment. An environment includes your modules and environment-specific configurations for each module, such as ingress, databases, and environment variables.

When you deploy your app, the platform will deploy the modules as containers in the designated Kubernetes cluster.

How do I create a module?

All you have to do is create a public repository in your linked GitHub organization that meets the following requirements:

  • It must include a Dockerfile.
  • The repository must have a tagged commit that includes the Dockerfile.

How do I add a module to my app?

When you create an app, the first step is to choose which modules to add.

If you want to add modules to an existing app:

  1. Log in to to the Humanitec platform and click on your app.
  2. In the box labeled Add new module, click Browse internal modules.
  3. A list of modules, derived from your organization’s repositories, will load. If you don’t see your module, then click Refresh the list. If you do, then click the Add button.
  4. Click Finish selection.

The module will be added to your app. However, you must deploy the app again in order for the changes to take effect.

How do I configure a module?

You can define the environmental configuration settings for your module by clicking on the module.

Once you click on it, the module’s configuration screen will appear:

Screenshot: Module configuration screen


This section displays information about the module’s repository and displays a list of versions (i.e., GitHub release tags). Here, you can choose which version to deploy with the app.

When you choose a version, the platform will build its Docker image (or take the existing one from the registry) and then deploy it to your cluster when you click Deploy.

Build logs

This section shows the logs for all of the build steps defined for your module. You can use this section to troubleshoot issues with your module’s Dockerfile.

Custom port mapping

This section lets you expose your module with a public URL. Check the box and enter the port on which it serves its content.

Other modules can use the module’s DNS name (and in-cluster IP address) as environment variables In the Variables section, enter a variable substitution in the value field with the format: ${modules.{MODULE-NAME}.service.external-name}. See the variable substitutions section for more information.


The Humanitec platform offers you the option to create databases for each module in a Google Cloud Platform (GCP) cluster managed by the platform itself. You can choose from the following types:

  • PostgreSQL
  • MongoDB (coming soon)
  • MySQL (coming soon)

When you create a platform-managed database instance, the platform will create the following secrets:

  • DATABASE_HOST: Host address of the database.
  • DATABASE_PORT: Port where the database listens.
  • DATABASE_ENGINE: Engine used to run the database.
  • DATABASE_NAME: UUID for the database.
  • DATABASE_USER: Username of the database user.
  • DATABASE_PASSWORD: Password of the database user.


This section lets you add and remove environment variables from the module’s config map. These values will be exposed to your module in the current deployment environment and will not carry over to different environments.

Here, you can also define variable substitutions that reference other modules and resources in your app. See the next section for more information.

NOTE: You should not store sensitive credentials in the module’s config map. Use the Secrets section instead.

Variable substitutions

You can use variable substitutions within environment variables to dynamically reference values that depend on the environment (e.g., the module’s database, auto-generated external DNS names). A variable substitution consists of a string that you enter in the value of an environment variable in a module’s configuration map. When you deploy your app, the platform will replace these strings with the values that they reference.

To create a variable substitution:

  1. Click on the module where you would like to create the variable substitution.
  2. Scroll down to the Variables section.
  3. Enter the name of the variable that your code references in the key field.
  4. In the value field, type ${ to bring up an autocomplete dropdown.
    Screenshot: Autocomplete dropdown
    • If you want to create a variable substitution for a database variable, then choose the proper value from dbs.
    • If you want to create a variable substitution that will resolve to the name of one of the other modules in your app, choose modules.
      See the next section for information about which variable substitutions you can create.
  5. Click Create.

Your variable substitution will be created. In order to apply it, you must re-deploy your app.


This section lets you securely define sensitive variables to be exposed to your module in the runtime environment.

A “secret” can be any credential, key, or password that would compromise your application/business security if exposed. Some examples:

  • Database credentials
  • Private keys for signing or identity (e.g., SSH keys or API keys)
  • Private certificates for communication (e.g., PGP, SSL)

The Humanitec platform stores these credentials in a secure secrets management system.

See the Secrets page for information about how to define secrets for your module.

Container logs

This section shows the logs for the container that the platform builds for this module. You can use these logs to troubleshoot runtime issues with your module.

How do I update a module?

The Humanitec platform handles module updates and versioning through release tags in the module’s git repository.

To apply an update to a module:

  1. Go to the module’s git repository and create a new release tag.
  2. Log in to the platform and select the app that contains the module you want to update.
  3. Click on the module you want to update.
  4. The module’s configuration screen will load. In the Repository section at the top, click on the dropdown and click the Refresh tags link.
    Screenshot: Refresh tags to get new versions of a module
  5. The platform will pull the latest release tags for your module and load them in the dropdown menu. Select the version of the module you want to apply.
  6. Re-deploy your app.

How do I remove a module from an app?

On the app overview screen, click on the module you want to remove, and then click the Remove module button in the lower left:

Screenshot: Remove module from app

Note that this will only remove the module from the specific environment you have selected. Other environments in the app may still include the module.

Reference: List of variable substitutions

Note: This list will expand over time.

Database references

Variable substitution name Description The name of the database that your module connects to.
dbs.postgres.engine Database engine used. Will always be POSTGRES. The DNS name or IP of the database server.
dbs.postgres.username Username of the Postgres ROLE that has access to the database defined in
dbs.postgres.password Password of the Postgres ROLE that has access to the database defined in
dbs.postgres.port Port on the server defined by

Module references

Variable substitution name Description
module.{MODULE-NAME} In-cluster DNS name of the module.
modules.{MODULE-NAME}.service.external-name DNS name of the module, which is generated if you expose the module externally.