Chef Habitat Builder

Chef Habitat Builder acts as the core of Chef’s Application Delivery Enterprise hub. Chef Habitat Builder was first launched as a cloud service and as the repository of all available plan templates built by Chef and the supporting community. Due to the fact that the application source code is stored alongside the build package, many users expressed a preference for storing packages and running Chef Habitat Builder on-prem. As a result, Chef Habitat Builder can be consumed either as a cloud based or on-premises solution. Plan files are stored in the Chef Habitat Builder SaaS, where they can be viewed and accessed by the Chef Habitat community and then shared with the on-premises version of the builder where they can then be copied and maintained locally.

Chef Habitat Builder Enterprise Components Include:

  • Application Manifest - The Application Manifest provides a single application directory, which includes---at a minimum---the compiled app artifact, dynamic links to all direct and transitive runtime dependencies ,and instructions to install and run the app.
  • Deployment Channel Management - Pre-canned deployment channels that can be used as-is or a user can custom design their own channels. Apps that are deployed through Chef Habitat can subscribe to a channel and be auto-upgraded whenever the app is promoted.
  • Origin Management - Save your application delivery content in uniquely named spaces that you can control.
  • Content Library - Hundreds of pre-built application delivery packages and core dependencies, which makes it easy to get started with Chef Habitat.
  • Custom Data and Reporting APIs - Rich APIs enable the capability to export to CSV or JSON.
  • DevOps Integration APIs - Provides an API so that clients can find and download the necessary packages to run their applications. Additional APIs also enable easy integration with other popular DevOps tools, including Jenkins, Terraform, Artifactory, Hashi Vault, and many others.
  • Role Based User Access - Improves your organizations operational safety by letting you assign specific levels of access to each origin member.

For more information on how the SaaS and On-Prem versions of Chef Habitat Builder work together, read the blog - Chef Habitat Builder On-Prem Enhancements that Extend Support to Airgap Environments and Simplify Set-Up

Get Started

Whether you are looking to leverage the SaaS or on-prem version of Chef Habitat Builder, you will need to create an account on the SaaS version of Chef Habitat Builder. After you have then downloaded the version, you will then sync the two accounts.

This documentation covers everything from creating an account to setting up automated builds and exporting packages to a variety of container registries.


Get an Account

Prerequisites

You need to set a few things up before you can get started with Chef Habitat Builder:

Sign-in and Authorize Chef Habitat Builder

Chef Habitat Builder automatically creates your account the first time you sign in using the GitHub authentication process. You'll also need to authorize the Chef Habitat Builder application in Github.

Head over to the Chef Habitat Builder sign-in page at https://bldr.habitat.sh/#/sign-in to get started.

  1. To sign in with an existing GitHub account, select Sign in with GitHub
  2. If you need to set up a GitHub account, select the Sign up here link

Chef Habitat sign in with Github

Signing in with your GitHub account and authorizing the Chef Habitat Builder application the first time you sign in grants you access to the Chef Habitat Builder platform. Once you've completed signing in and authorizing Chef Habitat Builder, you'll arrive at the 'My Origins' view.

Authorize the Chef Habitat Application

Set up a Profile

Use the Profile tab to:

  • See the GitHub account used to sign in
  • Add an email to your profile
  • Create your personal access token

Access your profile by selecting the round icon at the top right corner of any page. Select the profiles option from the drop-down menu to customize your profile and create your personal access token.

Access your Chef Habitat Builder profile

Register an Email Address

Adding an email address to your profile gives the Chef Habitat team permission to contact you directly about important information. If you use an email address associated with a GitHub account, it will also use your GitHub avatar. Save your changes by selecting save.

Register your email address

Create a Personal Access Token

Chef Habitat Builder uses an access token, called a personal access token or a Habitat authentication token (HAB_AUTH_TOKEN), to give you access to actions that you would like to take on Chef Habitat Builder. The personal access token is the first level of permissions that you need to for any interactions with Chef Habitat Builder, such as uploading packages or checking the status of build jobs.

Create your personal access token at the bottom of the profile page (below the save button), by selecting Generate Token.

Create your personal access token

Your generated access token will appear in the field. The access token is visible in the tab once, and navigating away from or reloading the page will cause it to vanish from the display. Copy your access token by selecting the icon on the right side of the field and set it as an environment variable before continuing.

Copy your personal access token

Set the personal access token as a Windows Environment Variable

You can use your personal access token as a Windows environment variable for a single session by passing it in the command line or save it in your user settings for use across sessions.

Save your personal authorization token as a permanent environment variable in Windows using:

SETX HAB_AUTH_TOKEN <token> /m

Replacing with the contents of your generated personal access token.

You can also save your personal access token as a permanent environment variable using the Windows user interface. In your Windows help bar, enter environment and select Edit the system environment variables from the list of suggestions.

This opens the System Properties window on the Advanced tab. Select the Environment Variables button.

Navigate to Windows Environment Variables

In the next window, select the New button in the top part. This opens a dialog box that lets you set individual user variables.

Make new user variable

Create a permanent environment variable by entering HAB_AUTH_TOKEN as the variable name. Next, paste the authorization token that you copied after you generated a new token on your profile page as the variable value. After you select the OK, you will see the new token in the user variables field.

Save your HAB_AUTH_TOKEN

To test that your new token works correctly, open the Command Prompt---which you can find by entering command in the Windows search box---and entering echo %HAB_AUTH_TOKEN%. You should see the value that you pasted into the environment variable.

Set the personal access token as a macOS Environment Variable

Set the HAB_AUTH_TOKEN in the CLI with:

export HAB_AUTH_TOKEN=<token>

Replacing <token> with the contents of your generated personal access token.

To use your personal access token across sessions, set it as an environment variable in your interactive shell configuration file, such as your .bashrc.

export HAB_AUTH_TOKEN=<token>

Then initialize the path from the command line, by running:

source ~/.bashrc


Origins

An origin is a place on Chef Habitat Builder where you can store, share, and build packages. It is a unique namespace within Chef Habitat Builder, and while you can delete or transfer an origin, you can't rename an origin after it is created. One example of an origin is the "core" origin, which is the set of foundational packages managed and versioned by the core Chef Habitat maintainers.

You can join existing origins by invitation and you can create your own origins. For more on invitations, see origin membership and RBAC.

Create an Origin

Chef Habitat Builder without origins

To create an origin, select the Create origin button on the My Origins page which opens the Create New Origin form. (Chef Habitat Builder > My Origins )

Creating an origin

First, enter a unique name that you want to associate with your packages. Chef Habitat will only let you create an origin with a unique name. Some examples that you'll see in Chef Habitat Builder are team names, user names, and abstract concepts.

Next, choose a privacy setting to set as the default for new packages. You can override this setting when uploading individual packages from the CLI or by connecting a plan file that declares a package as private. The difference between public and private packages is:

  • Anyone can find and use public packages
  • Only users with origin membership can find and use private packages

When you select Save and Continue, Chef Habitat Builder:

  1. Creates your origin
  2. Creates an origin key pair
  3. Redirects Chef Habitat Builder to the origin page

Origin successfully created

Create an Origin with the Chef Habitat CLI

Use the hab origin commands to manage your origins from the command line.

Create an origin from the command line with the hab origin create command

hab origin create <origin>

The results of this command differ slightly from creating an origin on the Chef Habitat Builder site. The CLI command:

  1. Creates an origin on the Chef Habitat Builder site
  2. Does not generate an origin key pair

For more information, see the hab origin create CLI documentation.


Origin Membership & RBAC

Prerequisites:

Role-Based Access Control (RBAC) for Chef Habitat Builder (SaaS and on-prem)

New in: 1.6.140

RBAC provides your organization with better operational safety by letting you assign specific levels of access to each user that belongs to an origin. With RBAC in place, existing standard origin 'members' from earlier versions are assigned the 'Maintainer' role. This role has similar permissions of the previous generic 'member' role, and the areas of difference are detailed below. The origin owner role remains unchanged.

When you join or create an origin, Chef Habitat Builder identifies your personal access token and assigns it a membership role for that origin. Your membership role defines the level of access that you have to the resources in an origin. By default, you're assigned the "read-only" role when you join an origin, and you're assigned the 'owner' role when you create an origin.

RBAC Origin Member Roles:

  • Read-Only: This user can read an origin's packages, channels, origin membership, jobs, keys, integrations, invitations, roles, settings but cannot add to, change, or delete anything else in the origin, including uploading packages and inviting users to the origin. Read-Only is the default membership role for users joining the origin.
  • Member: In addition to read-only access, an origin 'Member' can upload and build packages in the 'unstable' channel, but they cannot promote packages to other channels.
  • Maintainer: Existing origin 'members' are now 'Maintainers'. This role has full read and write access to packages, channels, origin membership, jobs, integrations, invitations, settings. However, the 'Maintainer' role is more limited than the past role, in that 'Maintainers' only have read access to packages, channels, origin membership, jobs, keys, integrations, and settings. Origin 'Maintainers' can read origin membership roles and see and send invitations, but they cannot otherwise change origin membership--their own or anybody else's. Finally, 'Maintainers' can neither read nor write origin secrets.
  • Administrator: In addition to 'Maintainer' access, the 'Administrator' role adds the missing privileges for writing origin keys and membership roles, as well as for reading and writing origin secrets. Administrators have full read and write access to packages, channels, origin membership, jobs, keys, integrations, invitations, roles, secrets, settings.
  • Owner: As in the past, the origin 'Owner' has full read and write access to the origin. Only Owners can delete the origin or transfer ownership to another member.

Comparison of RBAC Member Roles and Actions

Action Read-Only Member Maintainer Administrator Owner
Packages
View packages Y Y Y Y Y
Upload packages to unstable N Y Y Y Y
Promote packages from unstable N N Y Y Y
Build Jobs
View build jobs Y Y Y Y Y
Trigger unstable build job N Y Y Y Y
Channels
View channels Y Y Y Y Y
Add/Update/Delete channels N N Y Y Y
Origin Keys
View keys Y Y Y Y Y
Add/Update/Delete keys N N N Y Y
Origin Membership
View origin membership Y Y Y Y Y
View invitations Y Y Y Y Y
Send Invitations N N Y Y Y
Revoke Invitations N N Y Y Y
Member Roles
View member roles Y Y Y Y Y
Update member roles N N N Y Y
Origin Settings
View settings Y Y Y Y Y
Add/Update/Delete settings N N N Y Y
Origin Secrets
View secrets N N N Y Y
Add/Update/Delete secrets N N N Y Y
Cloud Integrations
View integrations Y Y Y Y Y
Add/Update/Delete integrations N N Y Y Y
Ownership
Transfer Origin N N N N Y
Delete Origin N N N N Y

Manage Origin Membership

In tandem with the changes to the Builder membership roles, we've also updated the hab CLI to support RBAC. We're working on adding role management to the Chef Habitat Builder site, but in the meantime, you'll need to use the CLI for now.

Manage origin membership

Manage origin membership with hab origin invitations

Manage Chef Habitat Builder origin membership with the Chef Habitat CLI, using the hab origin invitations command.

All Chef Habitat Builder users can accept, ignore, and see invitations for their accounts.

View origin invitations:

hab origin invitations list

Accept origin invitations:

hab origin invitations accept <ORIGIN> <INVITATION_ID>

Ignore origin invitations:

hab origin invitations ignore <ORIGIN> <INVITATION_ID>

Send origin membership invitations:

hab origin invitations send <ORIGIN> <INVITEE_ACCOUNT>

Origin administrators and owners can see all pending origin membership invitations:

hab origin invitations pending <ORIGIN>

Origin administrators and owners can rescind an origin membership invitation:

hab origin invitations rescind <ORIGIN> <INVITATION_ID>

Origin owners can transfer origin ownership to another member:

hab origin transfer [OPTIONS] <ORIGIN> <NEW_OWNER_ACCOUNT>

Manage membership roles with hab rbac

You can use role based access control (RBAC) from the command line. An origin MEMBER_ACCOUNT is the name used to sign in to Chef Habitat builder. You can find the list of user names on an origin's Members Tab. (Builder > Origin > Members)

The RBAC command syntax is:

hab origin rbac <SUBCOMMAND>

The syntax for the show subcommand is:

hab origin rbac show <MEMBER_ACCOUNT> --origin <ORIGIN>

See an origin member's RBAC role:

hab origin rbac show bluewhale --origin two-tier-app

The syntax for the set subcommand is:

hab origin rbac set [FLAGS] [OPTIONS] <MEMBER_ACCOUNT> <ROLE> --origin <ORIGIN>

Set an origin membership RBAC role with:

hab origin rbac set bluewhale admin --origin two-tier-app


Origin Keys

Prerequisites:

When you create an origin, Chef Habitat Builder automatically generates origin keys. Origin key cryptography is asymmetric: it has a public origin key that you can distribute freely, and a private origin key that you should distribute only to users belonging to the origin. All Chef Habitat Builder users with access to the origin can view the origin public key revisions in the origin key tab (Builder > Origin > Keys) and download the origin public key, but only users with the origin 'administrator' or 'owner' roles can view or download the origin private key, or change the origin key pair.

Keys Actions Read-Only Member Maintainer Administrator Owner
View keys Y Y Y Y Y
Add/Update/Delete keys N N N Y Y

Chef Habitat uses origin keys:

  • When you build an artifact in your local environment, Chef Habitat signs the artifact with a public key
  • When you upload an artifact to Chef Habitat Builder or Builder on-prem, Chef Habitat verifies that the artifact was signed with its public key
  • When you install an artifact on a Chef Habitat Supervisor, Chef Habitat uses the public origin key to authorize the artifact's installation; Chef Habitat only installs artifacts for which it has the public origin key
  • When you download an artifact to your local environment, Chef Habitat uses the public origin key to verify the artifact's integrity before it starts the installation

Chef Habitat Builder origin key names follow the format:

<origin>-<datetime>.pub (public key)
<origin>-<datetime>.sig.key (private key, also called a "signing key")

For example, in:

testorigin-20190416223046.pub
testorigin-20190416223046.sig.key

  • "testorigin" is the origin's name
  • "20190416223046" is the date and time of the key's creation, which was 2019-04-16 22:30:46.
  • .pub is the file extension for the public key
  • .sig.key is the file extension for the private key, which is also called a "signing key"

The Keys Tab

When you create an origin, Chef Habitat Builder automatically generates an origin key pair and saves both keys. To view your origin keys on Chef Habitat Builder, navigate to your origin and select the Keys tab. (Builder > Origins > Keys) You will always be able to view and download origin public keys, but you will only see the private keys for origins in which you are an "administrator" or "owner".

Viewing your origin keys

Download Origin Keys

Download your private or public origin key by selecting the download icon from the right end of the key details, under the Actions heading.

Detail of the download icon

Upload Origin Keys

You can upload origin keys that you generate on the command line to Chef Habitat Builder by selecting either the Upload a private key or Upload a public key icon, and copy your key into the form that appears.

Example form content for uploading an origin key in Builder

Managing Origin Keys with the CLI

Run Chef Habitat CLI commands from your local environment or from within the Chef Habitat Studio.

See the CLI documentation for more information on the hab origin key commands.

Find Your Local Origin Keys

Chef Habitat stores your public and private origin keys at ~/.hab/cache/keys on Linux systems, C:\hab\cache\keys on Windows, and at /hab/cache/keys inside of the Chef Habitat Studio environment.

To find your origin keys in your local environment:

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la ~/.hab/cache/keys

To find your existing origin keys from inside of the Chef Habitat Studio:

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la /hab/cache/keys

Generate Origin Keys with the CLI

When you create an origin through the site, Chef Habitat Builder automatically generates an origin key pair.

The Chef Habitat CLI creates origin key pairs through two different commands, for two different uses:

  • Use hab setup to generate your first origin key pair as part of setting up the hab CLI
  • Use the hab origin key generate <ORIGIN> command to create an key pair for an origin created with the hab origin create command

Create origin keys with the hab command:

hab origin key generate <ORIGIN>

Download Origin Keys with the CLI

To get your public origin key using the command line, use:

hab origin key download <ORIGIN>

Upload Origin Keys with the CLI

Creating an origin with the hab origin create command registers the origin on Chef Habitat Builder without creating an origin key pair. The hab origin key generate command creates the key pair and saves them in your local environment, but it does not upload either origin key to Chef Habitat Builder.

  • Only "administrators" and "owners" can upload new keys to an origin.
  • Builder requires the public origin key to upload artifacts for that origin, so you'll need to upload it.
  • Builder requires the private origin key to enable new artifact builds from packages with plans linked to that origin.

Upload origin keys with the hab command:

hab origin key upload <ORIGIN>

Upload the origin private key:

hab origin key upload --secret <ORIGIN>

Upload both origin keys at the same time:

hab origin key upload --secfile <PATH_TO_PRIVATE_KEY> --pubfile <PATH_TO_PUBLIC_KEY>

Import Origin Keys with the CLI

Use hab origin key import to read the key from a standard input stream into Chef Habitat Builder:

hab origin key import <enter or paste key>
hab origin key import <PATH_TO_KEY>
curl <URL_THAT_RETURNS_KEY> | hab origin key import

Troubleshoot Origin Key Import

On a macOS, you may encounter an upload failure. To remediate this failure:

  • Check that your HAB_AUTH_TOKEN environment variable is properly set and initialized
  • Add your SSL_CERT_FILE to the environment variables in your interactive shell configuration file, such as your .bashrc.
export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem

Initialize the setting from the command line with:

source ~/.bashrc


Origin Settings

The Origin Settings tab contains:

  • Default Package Settings
  • Origin Secrets

Everyone with origin membership can see the Settings tab, but only origin administrators and owners can add, update, or delete settings content.

Settings Actions Read-Only Member Maintainer Administrator Owner
View settings Y Y Y Y Y
Add/Update/Delete settings N N N Y Y
Origin Secrets Actions
View secrets N N Y Y Y
Add/Update/Delete secrets N N N Y Y

The administrator or owner's view of the origin settings tab with a public default package setting and a saved origin secret

Default Package Settings

The Default Package Settings define the visibility of build artifacts (.hart files). Everyone with origin membership can view the origin settings, but only origin administrators and owners can add, update, or delete settings.

  • Public packages are visible in search results and can be used by every Chef Habitat Builder user
  • Private artifacts do not appear in search results and are available only to users with origin membership

Change the default setting for the origin by switching from Public Packages to Private Packages. The default setting required for each origin and users with more than one origin can set some as public and others as private. Packages can have different default visibility settings than their origin's. Change the default visibility setting in for individual packages in that package's setting tab (Builder > Origin > Package > Settings).

Origin Secrets

Everyone with origin membership can view origin secrets, but only origin administrators and owners can add, update, or delete settings. Origin Secrets are located at the bottom of the Settings tab (Builder > Origin > Settings > Origin Secrets) and they let you encrypt and store secrets as environment variables. Origin secrets are useful for plans that require access to protected resources at build time, such as private source-code repositories and cloud storage providers.

Origin secrets are retained by the origin and are available for any of that origin's packages. The origin secrets in your local environment are encrypted with an origin encryption key. Only Chef Habitat Builder can read encrypted origin secrets.

Manage Origin Secrets with the Chef Habitat CLI

You can view the list of origin secrets and delete them in Chef Habitat Builder. However, the primary way of interacting with origin secrets is with the Chef Habitat CLI.

List Secrets

To list all of the secrets in an origin, use:

hab origin secret list --origin <ORIGIN>

Set Origin Secrets as Environment Variables

Add your origin secrets as environment variables in your local environment:

export HAB_ORIGIN=<ORIGIN>
export HAB_AUTH_TOKEN=<TOKEN>
hab origin secret list

Save an Origin Secret

To save an origin secret give the secret a name and the key value:

hab origin secret upload AWS_ACCESS_KEY_ID <your-key-id>
hab origin secret upload AWS_SECRET_ACCESS_KEY <your-secret-access-key>

The output should similar to:

$ hab origin secret upload AWS_ACCESS_KEY_ID 1234567890EXAMPLE
↓ Downloading latest public encryption key
79 B / 79 B | [========================================] 100.00 % 120.23 KB/s
☑ Cached habicat-20200123456789.pub
☛ Encrypting value for key AWS_ACCESS_KEY_ID.
✓ Encrypted AWS_ACCESS_KEY_ID=[REDACTED].
↑ Uploading secret for key AWS_ACCESS_KEY_ID.
✓ Uploaded secret for AWS_ACCESS_KEY_ID.

Delete an Origin Secret

To delete an origin secret from an origin with the CLI

hab origin secret delete AWS_ACCESS_KEY_ID
hab origin secret delete AWS_SECRET_ACCESS_KEY

See Using Origin Secrets in Plans for guidance on using origin secrets.

See the hab origin secret CLI documentation for more information on these commands.


Upload and Promote Packages

Everyone with access to the origin can view origin packages, but only origin members, maintainers, administrators, and owners can upload packages to the 'unstable' channel Origin maintainers, administrators and owners can promote packages from the 'unstable' channel.

While you can build and run Chef Habitat packages without sharing them on Chef Habitat Builder, uploading them there enables greater collaboration and automated package rebuilds as underlying dependencies or your connected GitHub repository are updated.

Note: Chef Habitat Builder can only build Linux based plans (plan.sh) at this time.

Setting up Chef Habitat Builder is easily done on the website: these steps take you through connecting your local Studio development experience with Builder.

You interact with Chef Habitat Builder by:

  • Creating an account.
  • Creating an origin, or being invited to join an origin that already exists.
  • Setting up hab to authenticate with Builder.
  • Uploading the private and public keys for that origin.
  • Connecting your Github repositories and opting into rebuilds.

Chef Habitat Builder supports both public and private origins, packages, and Github repositories.

Create a Builder Account

If you haven't created an account yet, see the Create a Builder Account section above.

Create or Join an Existing Origin

You can create your own origin in Builder or be invited to join an existing one. If you already built some Chef Habitat packages on your local computer prior to signing up for an account, you must rename your local packages' pkg_origin if the origin you want already exists.

Set up Chef Habitat to Authenticate to Builder

When you upload a package to Builder, you are required to supply an auth token as part of the hab pkg upload subcommand. You can generate a Chef Habitat personal access token via the Builder site Profile page for use with the hab command-line utility.

Once you have this token, you can set the HAB_AUTH_TOKEN environment variable to this value, so that any commands requiring authentication will use it.

Create an Origin Key Pair

After finishing the basic account creation steps, you need to create your origin key pair. Habitat will use the private origin key to sign the artifacts (.hart files) created by building your plan and verify the integrity of your artifacts with the public origin key.

You can create an origin key pair by running hab cli setup from your host machine, or by running hab origin key generate <ORIGIN> from either the host machine or from within the studio.

Your public and private origin keys are located at ~/.hab/cache/keys on your host machine and at /hab/cache/keys inside the studio environment.

Upload Your Origin Keys

If you created a new Habitat origin from your host machine or from the Studio, Builder will not have either of the origin keys corresponding to your artifact. Builder will not accept uploaded artifacts without first having the correct origin public key.

You can upload keys for the origin through the web interface for Builder, or by using the hab origin key upload command. You must have the access token for authentication, as described earlier, before you can upload keys.

Upload Packages to Builder

As long as you are already a member of the Habitat origin, once Builder possesses at least the public origin key, then you may upload one or more artifacts to that origin with the hab pkg upload command. After Habitat validates the cryptographic integrity of the artifact, it is then uploaded and stored on Builder. Uploading artifacts is a privileged operation for which you must have the access token.

Promote Packages

Chef Habitat supports continuous deployment workflows through the use of channels. A channel is a tag for a package that the Supervisors in a service group can subscribe to. Channels are useful in CI/CD scenarios where you want to gate a package before making it the default version of the package that users should consume. You can think of this split as the difference between test and production, or nightly releases versus stable releases of products.

By default, newly uploaded packages are placed in the unstable channel. However, the default package that is downloaded is the latest stable version of a package, unless overridden in commands such as hab sup run, hab svc load, and hab pkg install. If you want to promote your package to the stable channel, run the hab pkg promote command as follows:

$ hab pkg promote -z <TOKEN> origin/package/version/release stable

Note You can also promote packages to the stable channel using the promote to stable button in the web app.

For more information on how to use channels, see Continuous Deployment Using Channels.

Running Packages from Builder

Note: When running private packages from Builder, it's necessary to add your Chef Habitat access token to the machine where you intend to deploy the package, via export HAB_AUTH_TOKEN=<token>.

You can instruct the Supervisor to download and run packages from Builder by using the hab sup and hab svc commands, for example:

$ hab sup run
$ hab svc load core/postgresql

If the Supervisor does not have the core/postgresql package in its local cache, it will contact Builder, retrieve the latest version and the public key for the core origin, verify the cryptographic integrity of the package, and then start it.

You may also supply a --channel argument to instruct the Supervisor to use a different channel for the purposes of continuous deployment:

$ hab svc load core/postgresql --channel unstable

Running Packages from Exported Tarballs

An exported tarball package contains the Chef Habitat client/binary as well as dependencies specified by your artifact.

After deploying the tarball to your target server, extract the contents to the root filesystem (/):

$ tar zxf core-nginx-1.11.10-20170616000025.tar.gz --directory /

You can instruct the Supervisor to run packages from an exported tarball:

$ /hab/bin/hab svc start core/nginx

Note: On a clean server, this will download additional packages to satisfy the Supervisor dependencies. You will also require a hab group and hab user on the system for most services.


Using Multiple Plans

If you have a GitHub repository with multiple components inside, you will most likely also have individual plans for those components that are located inside of component subfolders. By default, Builder will only look for a package plan in either the root of the repository, or in a habitat subfolder at the root. If it does not find a plan file in those locations, it will not automatically issue builds when it detects file changes in the repository.

In order to tell Builder about the location of the individual plan files, and in order provide more fine-grained control over when component packages are built, you can programmatically customize how and when Builder will build your plans by specifying build behavior in a .bldr.toml file at the root of the repository that you connect to Builder.

Using this file, Builder only builds packages when source files or directories are updated in paths specified in .bldr.toml. This allows you to configure the building, publishing, and post-processing phases of a plan build in Builder.

To enable this functionality, do the following:

  1. Create a .bldr.toml in the root of your repository.

  2. Open it and add an entry for each component package that you want to build.

    The .bldr.toml file is in TOML format, so create a TOML table specifying the $pkg_name value for that plan and then add a plan_path field specifying the path to your plan.sh file (you do not need to include plan.sh explicitly in the path). If all the files related to the plan are under the plan path, then you are done. Otherwise, you will need an additional 'paths' field specifying Unix-style path globs to files that are associated with the plan you specified in the 'plan_path'. File or directory changes made in these path locations determine which packages will be rebuilt. Basically, when a file is committed, Builder will check to see whether it falls underneath the plan_path hierarchy, or matches one of the globs in the paths field if it was specified - if the answer is yes, then Builder will issue a build for that commit.

    It's important to note that the entries for plan_path and paths do not behave the same. If you have something like plan_path = "habitat", that behaves as if you had written plan_path = "habitat/*" - that is, it will automatically check every file under the habitat directory. However, if you have something like paths = [ "src" ], that is not automatically expanded to src/*. That line will only watch for changes to a file called src. If you're wanting to watch for changes to any file inside the src directory, then you must explicitly specify the glob, like so: paths = [ "src/*" ].

    For example, in the Chef Habitat repository itself, this TOML states that the hab-launcher, hab-studio, and hab-sup packages will be rebuilt if there are any changes in any of the specified components sub-directories. Note that hab-studio does not need to specify a path because all of it's files are within the plan_path hierarchy, but that is not the case for the other projects.

    # .bldr.toml
    [hab-launcher]
    plan_path = "components/launcher/habitat"
    paths = [
    "components/launcher/*",
    "components/launcher-protocol/*",
    "support/ci/builder-base-plan.sh",
    ]
    [hab-studio]
    plan_path = "components/studio"
    [hab-sup]
    plan_path = "components/sup"
    paths = [
    "components/sup/*",
    "components/eventsrv-client/*",
    "components/launcher-client/*",
    "components/butterfly/*",
    "components/core/*",
    "components/builder-depot-client/*",
    ]

    Notice that in order to specify that we're interested in all files inside of the directories in our paths entries, we had to add the /* glob to the end manually.

    It's also worth pointing out that there are multiple wildcard characters you can use when specifying path components.

  • ? will match any single character.
  • * will match any (possibly empty) sequence of characters
  • ** matches the current directory and arbitrary subdirectories. This sequence must form a single path component, so both **a and b** are invalid. More than two consecutive * characters is also invalid.
  • [...] matches any character inside the brackets. You can also specify a range, such as [0-9] to match any digit or [a-z] to match any lowercase letter.
  • [!...] is the negation of [...] so it will match any character not in the brackets.

    Note that while the above set of rules bears a remarkable resemblance to regular expressions, we do not support full regular expression syntax. Only what's shown here is supported. Here is an example.

    # .bldr.toml
    [hab-sup]
    plan_path = "components/sup" # automatically checks every file inside the 'sup' directory
    paths = [
    "components/sup/?", # matches any file with a single character file name inside the 'sup' directory
    "components/eventsrv-client/*", # matches any file inside the 'eventsrv-client' directory
    "components/launcher-client/**/*", # matches any file inside the 'launcher-client' directory and also any of its sub-directories
    "components/butterfly/[0-9]*" # matches any file inside the 'butterfly' directory that begins with a number
    ]

Set up Automated Builds

By connecting a plan file in Chef Habitat Builder, you can trigger both manual (via the web UI, or via the hab command line) as well as automated package rebuilds whenever a change is merged into the master branch of the repository containing your Chef Habitat plan, or when a dependent package updates (rebuilds).

Connect a Plan

To connect a plan to Builder, view one of your origins (while signed in), click the Connect a plan file button, and complete the following steps:

  • Install the Builder GitHub App
  • Choose the GitHub organization and repository containing your Chef Habitat plan
  • Choose a privacy setting for the package
  • Specify container-registry publishing settings (optional)
  • Specify auto-build option (default is off)

Auto-build Option

The auto-build option controls whether or not your package will get automatically re-built. This option is a useful capability to have - for example, if you have a demo app that doesn’t need to be kept constantly up to date when some underlying dependency updates. Auto-build encompasses both builds that are triggered by Github web hooks (on commits to master), as well as builds that are triggered by a dependency updating.

By default, new plan connections will have auto-build turned off.