Skip to content

Commit

Permalink
Reorganise content and formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@banchan86
banchan86 committed Sep 6, 2024
1 parent 8d781d9 commit 1ff1c7c
Showing 1 changed file with 51 additions and 56 deletions.
107 changes: 51 additions & 56 deletions articles/environments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,50 +11,72 @@ If you have many projects, you might notice that older projects require specific

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.

## Creating an environment
## 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.

```ps
dotnet new install Bonsai.Templates
```
Navigate to the folder where you want to create a new Bonsai environment.
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.

```ps
dotnet new bonsaienv
```
This creates by default a bonsai environment in your current directory with a `.bonsai` folder and runs a powershell script to install any dependencies for a minimal Bonsai installation.
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`](xref:packages) should look for new packages. While this file needs to be included in the environment, most users do not need to modify it.

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`.
## Portable Method
> [!TIP]
> We recommend this approach for the casual user.
```ps
dotnet new bonsaienv -o project1 -n .env
```
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`](xref:Bonsai.Vision) package:

## Updating environments
1. Start by downloading the [latest Bonsai portable release](https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip).
2. After extracting all the files from the `Bonsai.zip` file, your folder will look like this:

To install new packages in this environment, simply open the local `Bonsai.exe` and install the packages you need.
![Portable Bonsai release](~/images/environments-portablerelease.png)

The key to 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.
3. Run `Bonsai.exe`. During this first run, Bonsai will bootstrap the core dependencies and create an initial `Bonsai.config` file.
4. Install the **Bonsai - Vision** package using the [`Package Manager`](xref:packages). 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.
5. Close Bonsai.

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.
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.

## Packaging and Deploying environments
## 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.
If there is an existing Bonsai.config and/or NuGet.config in the folder, these will be used as part of the environment reconstruction process. In this case, it is enough to navigate to the folder where `Bonsai.config` is and simply run:
We have also provided a command-line tool for "one-click" deployment which installs packages automatically and streamlines the process for creating new environments.

```ps1
1. Install [`.NET SDK`](https://dotnet.microsoft.com/en-us/download).
2. Install `Bonsai.Templates` with the following command.
```cmd
dotnet new install Bonsai.Templates
```
3. Navigate to the folder where you want to create a new Bonsai environment and run this command.
```cmd
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:

```cmd
./Setup.cmd
```
4. 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`.
```cmd
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.

You can now move the new `.bonsai` folder to where you want to setup a new bonsai environment. When we run `Bonsai.exe` for the first time, the bootstrapper will attempt to download and resolve all core dependencies.
To share this environment with others, all you need are these 4 files.

- `Setup.ps1`
- `Setup.cmd`.
- `NuGet.config`
- `Bonsai.config`

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

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`](xref:packages) should look for new packages.
## Adding Local Dependencies
> [!TIP]
> For [new package](xref:create-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. For example, you may want to install local NuGet packages as dependencies (e.g. when testing [your own packages](xref:create-package)).
The `NuGet.config` file can be modified to specify new package sources by adding new entries.

To do this we just need to add new entries in the `NuGet.config` file. For example, to add a new package source named `LocalPackages` pointing to the Desktop folder:
For example, to add a new package source named `LocalPackages` pointing to the Desktop folder:

```xml
<?xml version="1.0" encoding="utf-8"?>
Expand All @@ -77,44 +99,17 @@ You can also use relative paths if you want to keep package sources relative to
> [!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](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior) documentation page.
## Version control and "one-click" Bonsai deployment
Similar to `Bonsai.config` the `NuGet.config` file will be used as part of the bootstrapper process when `Bonsai.exe` starts.

Now that we know how to create and reuse Bonsai environments, we will show you one way to streamline this whole process.

1. Create the `Bonsai.config` and, if necessary, modify your `NuGet.config` files.
2. Create a new folder and add these two files to it.
3. Add the following `PowerShell` script to the folder (e.g.: open a new text file and copy-paste the code) and name it `Setup.ps1`:

```powershell
if (!(Test-Path "./Bonsai.exe")) {
Invoke-WebRequest "https://github.com/bonsai-rx/bonsai/releases/download/2.7/Bonsai.zip" -OutFile "temp.zip"
Move-Item -Path "NuGet.config" "temp.config"
Expand-Archive "temp.zip" -DestinationPath "." -Force
Move-Item -Path "temp.config" "NuGet.config" -Force
Remove-Item -Path "temp.zip"
Remove-Item -Path "Bonsai32.exe"
}
& .\Bonsai.exe --no-editor
```

When executed, this small script will attempt to download a portable version of a Bonsai release, unzip it, and delete all the unnecessary files.

4. Add a second batch command file `Setup.cmd` that targets and runs `Setup.ps1`. It will look this:

```cmd
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```

5. Your folder should now contain only four files:
## Version Control
To keep track of environments, all that is needed are these four files from the [template method](#template-method)

- `Setup.ps1`
- `Setup.cmd`.
- `NuGet.config`
- `Bonsai.config`

You can now simply share this folder with another person who will be able to easily install your current Bonsai dependencies by running the `Setup.cmd` or `Setup.ps1` file.

As a final bonus, since all these files are encoded as text, they are easily version controlled using a distributed version control system such as [`git`](https://git-scm.com/). Because of this, we often keep this folder inside our project repository and keep updating it with new dependencies as the project evolves.
Since all these files are encoded as text, they are easily version controlled using a distributed version control system such as [`git`](https://git-scm.com/). 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:

Expand Down

0 comments on commit 1ff1c7c

Please sign in to comment.