Perform local developer setup

Introduction

As a developer using the Humanitec tools, most of your familiar workflows will remain unchanged. The tools introduce some new concepts, most notably the Score workload specification, which may reduce the complexity of your work and open up new testing possibilities.

This tutorial guides you through the setup of the Humanitec developer toolbox to support these new possibilities. You will see how to:

  • Set up the humctl CLI
  • Create and validate Score files
  • Enhance your IDE for working with Score
  • List available Resource Types
  • Deploy Score files locally using Docker Compose

If your organization uses a Cloud Development Environment (CDE), follow the same steps to configure it using your CDE provider’s documentation.

Prerequisites

To get started you’ll need:

  • Your developer workstation or Cloud Development Environment you wish to set up
  • (optional) The Visual Studio Code IDE installed locally
    • Using any other IDE will work. At this point, the best tooling support in the form of an extension is available for Visual Studio Code only
  • (optional) Docker Compose installed locally
  • A set of data provided to you by your Platform Engineering team:
    • A Humanitec user account
    • The Organization ID of your Humanitec Organization, e.g. my-org

Install the humctl CLI

humctl is the CLI to interact with the Humanitec Platform Orchestrator.

Follow the instructions on the CLI page to install humctl to your workstation.

Run this command to ensure humctl is in your path. The expected output is: humctl version XX.YY.ZZ

humctl version

Configure humctl autocomplete

The humctl CLI supports autocompletion for a number of popular shells.

Run this command to find the instructions for your shell:

# To see available shells:
humctl completion

# To generate the autocompletion script for your shell, e.h. bash:
humctl completion bash

Follow the instructions presented by the online help output to set up autocomplete for your shell.

Validate that it works: these commands should now provide you with autocomplete assistance when using the <tab> key. Depending on your shell, you may have to press <tab> twice.

$ humctl <tab>
$ humctl cre<tab>
$ humctl create <tab>

Perform Humanitec authentication

Use your Humanitec user account to access your Humanitec Organization. The account gives you access via both the Humanitec Portal and the CLI.

Login in to the Portal by opening https://app.humanitec.io . Select the authentication mechanism used by your Organization.

Then login to the CLI. Follow the instructions presented in your shell:

humctl login

For greater convenience, set the target Humanitec Organization for the CLI so can omit providing it via the --org flag in subsequent commands:

humctl config set org <your-org-id>

Explore Score

Score is a workload specification designed to simplify development for cloud-native developers. With Score, you can define your workload once using the Score Specification and then use a Score implementation to translate it to multiple platforms such as Docker Compose or Kubernetes. The Humanitec tools natively handle Score.

You do not need to know much about Score for this setup tutorial. Still, if you have not done so, it is a good idea to familiarize yourself with the basics. We suggest you take a few minutes to read this piece:

Make sure you have a score.yaml Score file available locally for the upcoming steps. E.g. you may copy the example from the Score for developers page, or use the humctl CLI to generate a starter file for you:

humctl score init

Validate Score files using humctl

Score is based on a JSON schema ( reference ).

Use can validate Score files against the specification using the humctl CLI. The CLI can also show warnings if Resource Types used in resource declarations are not available in your Organization.

To experience this capability, apply the modifications shown below to your Score file one by one, save the file, and validate it each time using this command:

humctl score validate score.yaml

# Score spec violation: add an empty container declaration
...
containers:
  demo:
...

# Score spec violation: add a container with disallowed characters in its name
...
containers:
  ///:
    image: .
...

# Score spec violation: add an unspecified property to a container declaration
...
containers:
  demo:
    some: property
...

# Score spec violation: add a resource declaration without a type and an unspecified property
...
resources:
  my-resource:
    some: property
...

# Humanitec config violation: add a non-existing resource type (requires CLI authentication)
...
resources:
  my-resource:
    type: dummy
...

Install the Humanitec VS Code extension

If you are using Visual Studio Code, you can use the official Humanitec VS Code extension, bringing features like:

  • Validate Score files
  • List available Resource Types (more on this below )
  • Easy switch between Orgs/Apps/Envs
  • and more

Visit the Visual Studio Marketplace site for installation instructions and usage examples.

Configure the IDE linter for Score

Developers can benefit from YAML linter functionalities in their Integrated Development Environments (IDEs) when working with Score files, which are themselves written in YAML.

Linting will detect any schema violation and thus assist you in authoring valid Score files. It is available for most IDEs.

Follow the instructions in the Score documentation to set it up for your IDE.

Validate that it works: open your Score file in your IDE and apply some or all of the Score spec checks shown above . Each should each be flagged as a problem.

List available Resource Types

When describing your Workload with Score, you declare its resource dependencies in the resources section of your Score file like this:

...
resources:
  my-db:
    type: postgres

The type must be one of the Resource Types supported in your Humanitec Organization. The Platform Engineering team is responsible for making Resource Types available for developers to use. This will usually be a subset of all the Resource Types listed in the reference.

You can list available Resource Types through the CLI as well the Humanitec VS Code extension.

humctl score available-resource-types

Example output:

Name                            Type                    Category        Class
Environment                     environment             score           default
Service                         service                 score           default
Persistent Volume               volume                  datastore       default
Redis                           redis                   datastore       default
DNS                             dns                     dns             default
Route                           route                   ingress         default
Google Cloud Service Account    gcp-service-account     gcp             default
MongoDB                         mongodb                 datastore       default
Azure Blob Storage              azure-blob              datastore       default
AMQP Broker                     amqp                    messaging       default
Dapr State Store                dapr-state-store        datastore       default

To see more details of each Resource Type like available inputs and outputs, request a different output format:

humctl score available-resource-types -o yaml

Select the Humanitec extension and expand the Available Resources view.

Expand each Resource Type to see more details like available inputs and outputs.

Deploy Score file locally with Docker Compose

This step is optional, but highly recommended especially if you are new to Score.

You may deploy Score files locally using Docker Compose and the corresponding Score implemenentation score-compose. You need to have Docker Compose installed to continue. Using this options will provide you with a local testing capability for fast feedback cycles.

The Score documentation provides a starter page covering the essential steps. Open this page and follow the instructions:

Note that the score-compose implementation comes with out-of-the-box support for a considerable number of Resource Types. See the list of resource provisioners for details on available types and the way to add more.

Recap

Congratulations! You have successfully completed the tutorial and learned how to perform your local developer setup. Specifically, you learned how to:

  • ✅ Set up the humctl CLI
  • ✅ Create and validate Score files
  • ✅ Enhance your IDE for working with Score
  • ✅ List available Resource Types
  • ✅ Deploy Score files locally using Docker Compose

Next steps

Explore more capabilities of Score in conjunction with the Humanitec Platform Orchestrator by browsing our Score examples .

Deploy your first Workload via the Platform Orchestrator by following the Deploy your Workload tutorial.

See how to have a temporary environment created automatically for every pull request in the Deploy ephemeral Environments tutorial.

Deploy your Workload