You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: articles/environments.md
+46-47
Original file line number
Diff line number
Diff line change
@@ -11,13 +11,18 @@ If you have many projects, you might notice that older projects require specific
11
11
12
12
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.
13
13
14
-
## Creating an environment
15
-
14
+
## Environment Basics
16
15
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.
17
16
18
17
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.
19
18
20
-
The easiest way to create a self-contained Bonsai environment is then 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:
19
+
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.
20
+
21
+
## Portable Method
22
+
> [!TIP]
23
+
> We recommend this approach for the casual user.
24
+
25
+
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:
21
26
22
27
1. Start by downloading the [latest Bonsai portable release](https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip).
23
28
2. After extracting all the files from the `Bonsai.zip` file, your folder will look like this:
@@ -28,29 +33,50 @@ The easiest way to create a self-contained Bonsai environment is then to downloa
28
33
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.
29
34
5. Close Bonsai.
30
35
31
-
## Deploying your environment
36
+
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.
32
37
33
-
Now that you have a `Bonsai.config` file with all the dependencies needed to run your project, how can you reproduce this installation elsewhere? As we saw in the previous step, when we run `Bonsai.exe` for the first time, the bootstrapper will attempt to download and resolve all core dependencies.
38
+
## Template Method
39
+
> [!TIP]
40
+
> We recommend this approach for users who need to deploy and maintain multiple environments. This approach assumes familiarity with the command-line.
34
41
35
-
However, if a `Bonsai.config` file is found inside the executable folder, the bootstrapper will also resolve those dependencies at startup time. We can test this by doing the following:
42
+
We have also provided a command-line tool for "one-click" deployment which installs packages automatically and streamlines the process for creating new environments.
36
43
37
-
1. Create a new folder and repeat steps 1. and 2. from the previous section.
38
-
2. This time, before running `Bonsai.exe`, copy your `Bonsai.config` into the folder:
2. Install `Bonsai.Templates` with the following command.
46
+
```cmd
47
+
dotnet new install Bonsai.Templates
48
+
```
49
+
3. Navigate to the folder where you want to create a new Bonsai environment and run this command.
50
+
```cmd
51
+
dotnet new bonsaienv
52
+
```
53
+
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:
39
54
40
-
55
+
```cmd
56
+
./Setup.cmd
57
+
```
58
+
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`.
59
+
```cmd
60
+
dotnet new bonsaienv -o project1 -n .env
61
+
```
62
+
To install new packages in this environment, simply open the local `Bonsai.exe` and install the packages you need.
41
63
42
-
2. Run `Bonsai.exe`.
43
-
3. Add a node that depends on the Vision package (e.g. [`CameraCapture`](xref:Bonsai.Vision.CameraCapture)) to verify that the package has been successfully installed.
64
+
To share this environment with others, all you need are these 4 files.
44
65
45
-
The new folder is now a copy of your previous environment.
66
+
-`Setup.ps1`
67
+
-`Setup.cmd`.
68
+
-`NuGet.config`
69
+
-`Bonsai.config`
46
70
47
-
## Adding local dependencies
71
+
Other users will be able to easily install your current Bonsai dependencies by running the `Setup.cmd` file.
48
72
49
-
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.
73
+
## Adding Local Dependencies
74
+
> [!TIP]
75
+
> For [new package](xref:create-package) developers, you may need to install local NuGet packages as dependencies during testing.
50
76
51
-
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)).
77
+
The `NuGet.config` file can be modified to specify new package sources by adding new entries.
52
78
53
-
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:
79
+
For example, to add a new package source named `LocalPackages` pointing to the Desktop folder:
54
80
55
81
```xml
56
82
<?xml version="1.0" encoding="utf-8"?>
@@ -73,44 +99,17 @@ You can also use relative paths if you want to keep package sources relative to
73
99
> [!Note]
74
100
> `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.
75
101
76
-
## Version control and "one-click" Bonsai deployment
77
-
78
-
Now that we know how to create and reuse Bonsai environments, we will show you one way to streamline this whole process.
79
-
80
-
1. Create the `Bonsai.config` and, if necessary, modify your `NuGet.config` files.
81
-
2. Create a new folder and add these two files to it.
82
-
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`:
Similar to `Bonsai.config` the `NuGet.config` file will be used as part of the bootstrapper process when `Bonsai.exe` starts.
103
103
104
-
5. Your folder should now contain only four files:
104
+
## Version Control
105
+
To keep track of environments, all that is needed are these four files from the [template method](#template-method)
105
106
106
107
-`Setup.ps1`
107
108
-`Setup.cmd`.
108
109
-`NuGet.config`
109
110
-`Bonsai.config`
110
111
111
-
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.
112
-
113
-
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.
112
+
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.
114
113
115
114
To prevent installed packages and other binary files from being tracked, you can add the following lines to the `.gitignore` file for convenience:
0 commit comments