Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update plugin documentation #1502

Merged
merged 2 commits into from
Sep 22, 2023
Merged

Update plugin documentation #1502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e38336f
Update plugin documentation
Lagoja Sep 22, 2023
127b37e
clarify init_hook
Lagoja Sep 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 80 additions & 27 deletions docs/app/docs/guides/creating_plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,40 +8,33 @@ Plugins make it easier to get started with packages that require additional setu

Before writing a plugin, we recommend reading the [User Documentation](https://www.jetpack.io/devbox/docs/guides/plugins/) on plugins, as well as inspecting and testing a few of the plugins in the [plugin directory](https://github.com/jetpack-io/devbox/tree/main/plugins) of our repo. Note that the plugins in this directory are compiled into the Devbox binary, but your plugin can be sourced from a local directory or from within your project.


If you're looking for plugin ideas, check out our [Issues page](https://github.com/jetpack-io/devbox/issues?q=is%3Aissue+is%3Aopen+label%3A%22plugin+request%22) for any user requests.

Before contributing, please consult our [Contributing Guide](https://github.com/jetpack-io/devbox/CONTRIBUTING.md) and [Code of Conduct](https://github.com/jetpack-io/devbox/CODE_OF_CONDUCT.md) for details on how to contribute to Devbox.

### Testing your Plugin
## Creating a Plugin

1. Create a new `devbox.json` in an empty directory using `devbox init`.
2. Add your plugin to the `include` section of the `devbox.json` file. Add any expected packages using `devbox add <pkg>`.
3. Check that your plugin creates the correct files and environment variables when running `devbox shell`
4. If you are looking for sample projects to test your plugin with, check out our [examples](https://github.com/jetpack-io/devbox/tree/main/examples).
We recommend organizing your plugin with the following directory structure, where the top-level folder matches the name of your plugin:

## Plugin Design
```
my-plugin/
├── README.md
├── plugin.json
├── config/
│   ├── my-plugin.conf
│   └── process-compose.yaml
└── test/
├── devbox.json
└── devbox.lock
```

Plugins are defined as Go JSON Template files, using the following schema:
* **README.md** -- Should contain a description of how your plugin works, and what files, variables, and services it adds to Devbox Projects
* **plugin.json** -- This file is a Go JSON Template that defines your plugin. See the sections below for more detail
* **config/** -- This folder contains any support or configuration files required by your plugin, as well as the process-compose.yaml for defining services
* **test/** -- This directory contains an example project for testing your plugin

```json
{
"name": "",
"version": "",
"readme": "",
"env": {
"<key>": "<value>"
},
"create_files": {
"<destination>": "<source>"
},
"init_hook": [
"<bash commands>"
]
}
```

A plugin can define services by adding a `process-compose.yaml` file in its `create_files` stanza.
## Plugin Design

### Plugin Lifecycle

Expand All @@ -62,6 +55,31 @@ flowchart TD
H[Start Services]
```

### Plugin.json Schema

Plugins are defined as Go JSON Template files, using the following schema:

```json
{
"name": "",
"version": "",
"readme": "",
"env": {
"<key>": "<value>"
},
"create_files": {
"<destination>": "<source>"
},
"shell": {
"init_hook": [
"<bash commands>"
]
}
}
```

A plugin can define services by adding a `process-compose.yaml` file in its `create_files` stanza.

### Template Placeholders

Devbox's Plugin System provides a few special placeholders that should be used when specifying paths for env variables and helper files:
Expand Down Expand Up @@ -108,9 +126,11 @@ Will copy the Caddyfile in the `plugins/caddy` folder to `devbox.d/caddy/Caddyfi

You should use this to copy starter config files or templates needed to run the plugin's package.

#### `init_hook` *string | string[]*
#### `shell.init_hook` *string | string[]*

A single `bash` command or list of `bash` commands that should run before the user's shell is initialized.

A single `bash` command or list of `bash` commands that should run before the user's shell is initialized. This will run every time a shell is started, so you should avoid any resource heavy or long running processes in this step.
This will run every time a shell is started, so you should avoid any resource heavy or long running processes in this step.

### Adding Services

Expand All @@ -120,6 +140,39 @@ Plugins can add services to a user's project by adding a `process-compose.yaml`

See the process compose [docs](https://github.com/F1bonacc1/process-compose) for details on how to write define services in `process-compose.yaml`. You can also check the plugins in this directory for examples on how to write services.

## Testing your Plugin

Testing plugins can be done using an example Devbox project. Follow the steps below to create a new test project

1. Create a new `devbox.json` in an empty directory using `devbox init`.
2. Add your plugin to the `include` section of the `devbox.json` file.
2. Add any expected packages using `devbox add <pkg>`.
3. Check that your plugin creates the correct files and environment variables when running `devbox shell`
4. If you are looking for sample projects to test your plugin with, check out our [examples](https://github.com/jetpack-io/devbox/tree/main/examples).


## Example: MongoDB

The plugin.json below sets the environment variables and config needed to run MongoDB in Devbox. You can view the full example at

```json
{
"name": "mongodb",
"version": "0.0.1",
"readme": "Plugin for the [`mongodb`](https://www.nixhub.io/packages/mongodb) package. This plugin configures MonogoDB to use a local config file and data directory for this project, and configures a mongodb service.",
"env": {
"MONGODB_DATA": "{{.Virtenv}}/data",
"MONGODB_CONFIG": "{{.DevboxDir}}/mongod.conf"
},
"create_files": {
"{{.Virtenv}}/data": "",
"{{.Virtenv}}/process-compose.yaml": "config/process-compose.yaml",
"{{.DevboxDir}}/mongod.conf": "config/mongod.conf"
}
}

```

## Tips for Writing Plugins

* Only add plugins for packages that require configuration to work with Devbox.
Expand Down
38 changes: 28 additions & 10 deletions docs/app/docs/guides/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,22 @@ title: Using Plugins

This doc describes how to use Devbox Plugins with your project. **Plugins** provide a default Devbox configuration for a Nix package. Plugins make it easier to get started with packages that require additional setup when installed with Nix, and they offer a familiar interface for configuring packages. They also help keep all of your project's configuration within your project directory, which helps maintain portability and isolation.

If a plugin is available for your package, it will activate when you install the plugin using `devbox add <package name>`.
## Using Plugins

### Built-in PLguins

If you add one of the packages listed above to your project using `devbox add <pkg>`, Devbox will automatically activate the plugin for that package.

You can also explicitly add a built-in plugin in your project by adding it to the [`include` section](../configuration.md#include) of your `devbox.json` file. For example, to explicitly add the plugin for Nginx, you can add the following to your `devbox.json` file:

```json
{
"include": [
"plugin:nginx"
]
}
```

## Current Plugins
Built-in plugins are available for the following packages. You can activate the plugins for these packages by running `devbox add <package_name>`

* [Apache](../devbox_examples/servers/apache.md) (apacheHttpd)
Expand All @@ -20,20 +33,25 @@ Built-in plugins are available for the following packages. You can activate the
* [Pip](../devbox_examples/languages/python.md) (python39Packages.pip, python310Packages.pip, python311Packages.pip...)
* [Ruby](../devbox_examples/languages/ruby.md)(ruby, ruby_3_1, ruby_3_0...)

Our team is rapidly adding new plugins to Devbox. If you want to request a plugin, please file an issue in the Devbox Repo.

## Using Plugins
### Local PLugins

If you add one of the packages listed above to your project using `devbox add <pkg>`, Devbox will automatically activate the plugin for that package.
You can also [define your own plugins](./creating_plugins.md) and use them in your project. To use a local plugin, add the following to the `include` section of your devbox.json:

You can also explicitly add a plugin in your project by adding it to the [`includes` section](../configuration.md#includes) of your `devbox.json` file. For example, to explicitly add the plugin for Nginx, you can add the following to your `devbox.json` file:
```json
"include": [
"path:./path/to/plugin.json"
]
```

### Github Hosted Plugins

Sometimes, you may want to share a plugin across multiple projects or users. In this case, you provide a Github reference to a plugin hosted on Github. To install a github hosted plugin, add the following to the include section of your devbox.json

```json
{
"includes": [
"plugin:nginx"
"include": [
"github:<org>/<repo>?dir=<plugin-dir>"
]
}
```

## An Example of a Plugin: Nginx
Expand Down