Table of Contents

Bonsai Environments

By default, Bonsai is installed system-wide and can be used to run any workflow. However, as projects grow, it is common to have to install new packages to access specific functionality, or update the version of existing packages to get the latest bug fixes and patches.

If you have many projects, you might notice that older projects require specific obsolete package versions which are not compatible with newer projects, resulting in setups that break when the system-wide installation gets updated since only one version of the package can be installed at any one time.

Bonsai addresses these problems by supporting the creation of reproducible package environments. An environment is a self-contained, portable, installation of Bonsai that records a snapshot of all the packages required to run the workflows in your project. This makes it much easier to share a project with other people, or keep track of multiple separate projects in our local machine, and be assured you always have everything you need in the right place.

Environment Basics

The key to creating and updating environments is the Bonsai.config file, which keeps a record of all currently installed dependencies for a specific Bonsai setup. You can find this file in the same location of the Bonsai executable (Bonsai.exe). Anytime you install or update a package, Bonsai will automatically modify the config file.

The contents of the Bonsai.config file are compared with the current state of the Packages folder when Bonsai starts. If there are any missing packages the Bonsai bootstrapper will download them automatically to recover the expected state of the installation folder.

There is a second configuration file located next to the Bonsai.config file called NuGet.config. This file stores a list of all the remote, and local, NuGet package sources where the Package Manager should look for new packages. While this file needs to be included in the environment, most users do not need to modify it.

Portable Method

Tip

We recommend this approach for the casual user.

The easiest way to create a self-contained Bonsai environment is to download the portable version of Bonsai and install the packages which are necessary for a specific project. For example, to share a project that depends on the Vision package:

  1. Start by downloading the latest Bonsai portable release.
  2. After extracting all the files from the Bonsai.zip file, your folder will look like this:

Portable Bonsai release

  1. Run Bonsai.exe. During this first run, Bonsai will bootstrap the core dependencies and create an initial Bonsai.config file.
  2. Install the Bonsai - Vision package using the Package Manager. The Bonsai.config file will be modified to specify this package as a new dependency. Any additional dependencies which might be needed for the package to run will also be added.
  3. Close Bonsai.

You now have a local Bonsai environment folder that you can keep separate for experiments or share with anyone else who needs it. Alternatively, once you have a modified Bonsai.config file, you can also simply copy the Bonsai.config file into a new portable installation, and the Bonsai bootstrapper will download and resolve the missing or inconsistent packages.

Template Method

Tip

We recommend this approach for users who need to deploy and maintain multiple environments. This approach assumes familiarity with the command-line.

We have also provided a command-line tool for "one-click" deployment which installs packages automatically and streamlines the process for creating new environments.

  1. Install .NET SDK.
  2. Install Bonsai.Templates with the following command.
dotnet new install Bonsai.Templates
  1. Navigate to the folder where you want to create a new Bonsai environment and run this command.
dotnet new bonsaienv

This creates by default a .bonsai folder with a minimal bonsai environment in your current directory. It will also prompt to run a powershell script to install any packages based on Bonsai.config. Before running the powershell script, you can replace the Bonsai.config file with a modified version or run the powershell script after by navigating to the .bonsai folder and running:

./Setup.cmd
  1. You can supply additional options to change the default settings. The following command for instance will create a new folder project1 containing a bonsai environment folder named env.
dotnet new bonsaienv -o project1 -n .env

To install new packages in this environment, simply open the local Bonsai.exe and install the packages you need.

To share this environment with others, all you need are these 4 files.

  • Setup.ps1
  • Setup.cmd.
  • NuGet.config
  • Bonsai.config

Other users will be able to easily install your current Bonsai dependencies by running the Setup.cmd file.

Adding Local Dependencies

Tip

For new package developers, you may need to install local NuGet packages as dependencies during testing.

The NuGet.config file can be modified to specify new package sources by adding new entries.

For example, to add a new package source named LocalPackages pointing to the Desktop folder:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="Gallery" value="Gallery" />
    <add key="Bonsai Packages" value="https://www.myget.org/F/bonsai/api/v3/index.json" />
    <add key="Community Packages" value="https://www.myget.org/F/bonsai-community/api/v3/index.json" />
    <add key="LocalPackages" value="C:\Users\BonsaiUser\Desktop"/>
  </packageSources>
</configuration>

You can also use relative paths if you want to keep package sources relative to the local environment. For instance:

<add key="LocalPackages" value=".\LocalPackages"/>
Note

NuGet.config files can be deployed hierarchically. You can have other NuGet.config files located higher in the file system to specify package sources that should be shared across multiple projects or specific for the local machine. For more information on this and other settings see the Common NuGet configurations documentation page.

Similar to Bonsai.config the NuGet.config file will be used as part of the bootstrapper process when Bonsai.exe starts.

Version Control

To keep track of environments, all that is needed are these four files from the template method

  • Setup.ps1
  • Setup.cmd.
  • NuGet.config
  • Bonsai.config

Since all these files are encoded as text, they are easily version controlled using a distributed version control system such as git. Because of this, we often keep this folder inside our project repository and keep updating it with new dependencies as the project evolves.

To prevent installed packages and other binary files from being tracked, you can add the following lines to the .gitignore file for convenience:

Packages
*.exe
*.exe.settings
Edit this page