From e38336f8bdd62c03e0e62c336dd6f1f8109c977d Mon Sep 17 00:00:00 2001 From: John Lago <750845+Lagoja@users.noreply.github.com> Date: Fri, 22 Sep 2023 15:11:43 -0700 Subject: [PATCH 1/2] Update plugin documentation --- docs/app/docs/guides/creating_plugins.md | 101 +++++++++++++++++------ docs/app/docs/guides/plugins.md | 38 ++++++--- 2 files changed, 104 insertions(+), 35 deletions(-) diff --git a/docs/app/docs/guides/creating_plugins.md b/docs/app/docs/guides/creating_plugins.md index a12df054522..3df165a77be 100644 --- a/docs/app/docs/guides/creating_plugins.md +++ b/docs/app/docs/guides/creating_plugins.md @@ -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 `. -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": { - "": "" - }, - "create_files": { - "": "" - }, - "init_hook": [ - "" - ] -} -``` -A plugin can define services by adding a `process-compose.yaml` file in its `create_files` stanza. +## Plugin Design ### Plugin Lifecycle @@ -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": { + "": "" + }, + "create_files": { + "": "" + }, + "shell": { + "init_hook": [ + "" + ] + } +} +``` + +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: @@ -120,6 +138,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 `. +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. diff --git a/docs/app/docs/guides/plugins.md b/docs/app/docs/guides/plugins.md index 701c17e1d12..71a1075802f 100644 --- a/docs/app/docs/guides/plugins.md +++ b/docs/app/docs/guides/plugins.md @@ -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 `. +## Using Plugins + +### Built-in PLguins + +If you add one of the packages listed above to your project using `devbox add `, 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 ` * [Apache](../devbox_examples/servers/apache.md) (apacheHttpd) @@ -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 `, 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:/?dir=" ] -} ``` ## An Example of a Plugin: Nginx From 127b37e0b03051fad6a4c30d3237c39a1331a319 Mon Sep 17 00:00:00 2001 From: John Lago <750845+Lagoja@users.noreply.github.com> Date: Fri, 22 Sep 2023 15:59:14 -0700 Subject: [PATCH 2/2] clarify init_hook --- docs/app/docs/guides/creating_plugins.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/app/docs/guides/creating_plugins.md b/docs/app/docs/guides/creating_plugins.md index 3df165a77be..9212af78f6e 100644 --- a/docs/app/docs/guides/creating_plugins.md +++ b/docs/app/docs/guides/creating_plugins.md @@ -126,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. This will run every time a shell is started, so you should avoid any resource heavy or long running processes in this step. +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. ### Adding Services