Build and Test

The Chef Habitat Studio is a self-contained, minimal, clean environment in which you can develop, build, and package software.

Windows based studios run inside a Powershell Core environment and have a path that only includes the Windows system directories and core Chef Habitat services. The studio includes a Supervisor running in the background and the Chef Habitat build system.

There are two "flavors" of Windows Studio available: A Docker-based container Studio and a local Studio. The container studio offers the highest level of isolation and a better guarantee of a clean environment that will have no side effects on your local environment, but it does require Docker for Windows to be installed and running in Windows container mode. A local Studio simply launches a new Powershell Core environment on your local Windows system and creates a new PSDrive targeting an alternative habitat environment separate from your local C:\hab environment. Both types of Studios require a native Windows environment. If you are not running on a Windows host, running on a local Windows VM should be sufficient but you will not be able to use the container Studio due to the Hyper-V requirements with Docker for Windows. You will need to use the local Studio instead. Alternatively you can also use a Windows cloud instance that has Docker preinstalled on AWS or Azure.

This topic covers the following areas:

Building your package

From the root of your local project, run the following:

PS C:\contosouniversity> $env:HAB_DOCKER_OPTS="--memory 2gb -p 80:8099"
PS C:\contosouniversity> hab studio enter -D

Assuming you are on a Windows host with Docker for Windows running in Windows container mode, this will enter a Powershell based Studio inside of a Windows container. We also set the HAB_DOCKER_OPTS variable which is forwarded to docker run when the Studio spawns its container. This will forward port 8099 which is what our application listens to in the container to port 80 locally. It also ensures that the Container is given 2 GB of ram. This is only important on a Windows 10 host which will run containers in Hyper-V Isolation mode where containers are spawned in their own minimal VM and allocated 1GB of memory by default. For many scenarios, including ours, 1 GB is simply not enough and can lead to odd and surprising results - not the good kind of surprise!

Note If you use a "fancy" console like conemu, console2, etc, you will want to use a standard Powershell or CMD based elevated (run as administrator) console when entering a container based Studio. Even better, use the new Windows Terminal application. Otherwise standard input and output render extremely awkwardly and eventually becomes nearly impossible to navigate.

You may also remove the -D argument to enter a local powershell studio. This will start up much faster but lack some of the isolation benefits of a container.

The src directory in the Chef Habitat Studio environment is the directory you were in when you entered the Studio. In this case, because you are in the root of your local project repo, the default src directory is the root of your project.

Run build to build your package.

[HAB-STUDIO] Chef Habitat:\src> build

Note If you build your web application in a CI/CD workflow, you can use the non-interactive build option to build your package. To do this, change directory to the root of your project and run hab pkg build. A Studio will be created, your package will be built, and then Studio will exit without requiring user input.

Testing your package locally

Whenever you enter the Chef Habitat Studio, a Supervisor begins running in the background. When you are ready to test your application, run hab svc load myorigin/contosouniversity.

You can see the streaming output by running Get-SupervisorLog. Type Ctrl-C to exit the streaming output.

Following the output, it may take a couple minutes for the DSC to fully apply and for the website to start running. Once the log emits "contosouniversity is running," our application should be ready to accept connections and be viewable in a local browser via http://localhost/contoso_university.

Exporting and Running your Docker container

After you have built your package and are ready to test it outside of the Studio, export it to a Docker container. We will source the last_build.ps1 variables which will provide us with a $pkg_artifact variable with the .hart filename of our build artifact and then export that file to a Docker image.

PS C:\contosouniversity> . ./results/last_build.ps1
PS C:\contosouniversity> hab pkg export docker ./results/$pkg_artifact

Note If you were building inside a Windows container, make sure to exit the studio before exporting the hart file. Also, you must have Docker for Windows running in Windows container mode in order to export docker images.

Note The command above is for local testing only. If you have uploaded your package to Builder, you can export it by calling hab pkg export docker origin/package. The default is to use the latest stable release; however, you can override that by specifying a different channel in an optional flag.

The following example shows how to start the Docker container running your Chef Habitat package.

PS C:\contosouniversity> docker run --env HAB_LICENSE="accept-no-persist" -p 80:8099 -it myorigin/contosouniversity

The `--env HAB_LICENSE="accept-no-persist"` accepts the Chef license, but does not persist that decision for future runs. The license has allowances for demo and trial purproses.

Setting `-p 80:8099` maps port 8099 from the app running within the Docker container to port 80 on your host machine. Please ensure that you don't have any other running applications listening on port 80.

Once your application is started you may access the application at any time by visiting localhost/contoso_university in a web browser.

For more information on using the Chef Habitat Studio, see Plan Builds.

Debugging your plan

When debugging your plan, it is important to understand what you can use to debug buildtime issues versus what you can use to debug runtime issues.

Debugging at buildtime

If you have to customize how your web application is built, such as overriding build phases through callbacks, it is helpful to know what environment variables are available to you, to make sure you have successfully copied/referenced files, or performed the business logic you intended to at that specific point in the build.

There are several built-in functions you can call in your plan.ps1 to help you with these issues, but you will likely find Powershell's own Set-PSBreakpoint to be the most helpful. You can use its -Command argument and set it to any of the build phase callback functions. When that function is invoked, you will be dropped into an interactive prompt where you can examine variables and files to debug your build.

Debugging at runtime

Debugging at runtime involves using a few different techniques to understand how your running service is behaving, how it interacts with peers in different topologies, how it handles configuration updates, and so on.

For verifying that files were copied into the appropriate paths for your service and paths resolve correctly in runtime hooks, log into the VM or connect to the Docker container that is running the service and examine the files and directories at /hab/svc/contosouniversity/. You can access the file structure by running the following command.

PS C:\contosouniversity> docker exec -it CONTAINERID powershell

Once in the container, to observe HTTP endpoint data (such as census or butterfly information), start up your service, then connect to the HTTP endpoint using Invoke-WebRequest. You can pipe the JSON output to ConvertFrom-Json and then ConvertTo-Json to provide a filtered and readable view on the output.

PS C:\> (Invoke-WebRequest http://localhost:9631/census -UseBasicParsing).Content | ConvertFrom-Json | ConvertTo-Json

For information on what endpoint information you can query, see Monitoring services.

Next: Connect to Database