Bootstrap core Habitat packages

When you first deploy Chef Habitat On-Prem Builder, it doesn’t include any pre-installed packages. This page explains how to bootstrap Builder with packages from Chef’s public Habitat Builder.

Generate a personal access token

You need a personal access token in your Habitat On-Prem Builder deployment to bootstrap the core packages and authenticate with the hab client.

If you don’t already have a token, generate one:

In the top right corner of your Habitat On-Prem Builder site, select your Gravatar icon, then select Profile.
On the profile page, generate your access token and save it securely.

Add a license key

In Chef Habitat SaaS Builder, you must have a Progress Chef license key in your Builder profile so you can access official Chef-maintained packages.

Enable native package support

Some new low level core origin packages include native packages. To host these packages, you must configure your Habitat Builder deployment to allow native package support. Enable the nativepackages feature and specify core as an allowed native package origin. Edit your On-Prem Builder’s /hab/user/builder-api/config/user.toml file so the [api] section looks like this:

[api]
features_enabled = "nativepackages"
targets = ["x86_64-linux", "aarch64-linux", "x86_64-windows"]
allowed_native_package_origins = ["core"]

Bootstrap Builder in an online environment

Bootstrapping is the initial process of populating your empty On-Prem Builder with essential packages from the public Habitat Builder. This is typically done once when you first set up your Builder instance.

Chef Habitat On-Prem Builder doesn’t include any pre-installed package sets. You need to upload packages to populate Habitat Builder deployment. To help bootstrap your On-Prem Builder with core packages, you can install the habitat/pkg-sync package. This package downloads packages from the public SaaS Builder and then uploads them in bulk to your Habitat Builder deployment.

To bootstrap Habitat On-Prem Builder with a full set of base core packages, run:

sudo hab pkg install habitat/pkg-sync

hab pkg exec habitat/pkg-sync pkg-sync \
  --bldr-url <PRIVATE_BUILDER_URL> \
  --origin core \
  --channel base \
  --private-builder-token <PRIVATE_BUILDER_TOKEN> \
  --public-builder-token <PUBLIC_BUILDER_TOKEN>

Bootstrap Builder in an airgapped environment

You can’t transfer packages directly to Habitat Builder in an airgapped environment using pkg-sync, so instead you have to download packages from the public Habitat Builder and upload them to your airgapped deployment.

Before you begin, you will need your personal access token that you use to communicate with your Habitat On-Prem Builder deployment and the URL of your Habitat On-Prem Builder deployment.

To bootstrap an airgapped On-Prem Builder with stable core packages, follow these steps:

Download the habitat/pkg-sync package on a machine with internet access:
```
sudo hab pkg install habitat/pkg-sync
```

Generate a list of packages to download:

hab pkg exec habitat/pkg-sync pkg-sync --generate-airgap-list --origin core --channel base

Download packages into the builder_bootstrap directory on your computer:

hab pkg download --target x86_64-linux --channel base --file package_list_x86_64-linux.txt --download-directory builder_bootstrap
hab pkg download --target x86_64-windows --channel base --file package_list_x86_64-windows.txt --download-directory builder_bootstrap

Archive the builder_bootstrap directory, then copy and extract the archive on a computer running in the airgapped environment.

Bulk upload packages to Habitat Builder:

export HAB_AUTH_TOKEN=<ON_PREM_BUILDER_INSTANCE_TOKEN>
hab pkg bulkupload --url https://<ON_PREM_BUILDER_DOMAIN> --channel base --auto-create-origins builder_bootstrap/