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
- Testing your package locally
- Exporting and Running your Docker container
- Debugging your plan
From the root of your local project, run the following:
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.
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.
build to build your package.
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.
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
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
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.
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.
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.
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.
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.
For information on what endpoint information you can query, see Monitoring services.