Using Devbox 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>
.
Current Plugins
Plugins are available for the following packages. You can activate the plugins for these packages by running devbox add <package_name>
:
- Apache (apacheHttpd)
- Nginx (nginx)
- Caddy (caddy)
- PostgreSQL (postgresql)
- Redis (redis)
- PHP (php, php80, php81, php82)
- Ruby(ruby, ruby_3_1, ruby_3_0)
- Pip (python39Packages.pip, python310Packages.pip, python311Packages.pip)
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
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 plugin in your project by adding it to the includes
section of your devbox.json
file. For example, to explicitly add the plugin for Nginx, you can add the following to your devbox.json
file:
{
"includes": [
"plugin:nginx"
]
}
An Example of a Plugin: Nginx
Let's take a look at the plugin for Nginx. To get started, let's initialize a new devbox project, and add the nginx
package:
cd ~/my_proj
devbox init && devbox add nginx
Devbox will install the package, activate the nginx
plugin, and print a short explanation of the plugin's configuration
Installing nix packages. This may take a while... done.
nginx NOTES:
nginx can be configured with env variables
To customize:
* Use $NGINX_CONFDIR to change the configuration directory
* Use $NGINX_LOGDIR to change the log directory
* Use $NGINX_PIDDIR to change the pid directory
* Use $NGINX_RUNDIR to change the run directory
* Use $NGINX_SITESDIR to change the sites directory
* Use $NGINX_TMPDIR to change the tmp directory. Use $NGINX_USER to change the user
* Use $NGINX_GROUP to customize.
Services:
* nginx
Use `devbox services start|stop [service]` to interact with services
This plugin creates the following helper files:
* ~/my_project/devbox.d/nginx/nginx.conf
* ~/my_project/devbox.d/nginx/fastcgi.conf
* ~/my_project/devbox.d/web/index.html
This plugin sets the following environment variables:
* NGINX_CONFDIR=~/my_project/devbox.d/nginx/nginx.conf
* NGINX_PATH_PREFIX=~/my_project/.devbox/virtenv/nginx
* NGINX_TMPDIR=~/my_project/.devbox/virtenv/nginx/temp
To show this information, run `devbox info nginx`
nginx (nginx-1.22.1) is now installed.
Based on this info page, we can see that Devbox has created the configuration we need to run nginx
in our local shell. Let's take a look at the files it created:
% tree
.
├── devbox.d
│ ├── nginx
│ │ ├── fastcgi.conf
│ │ └── nginx.conf
│ └── web
│ └── index.html
└── devbox.json
These files give us everything we need to run NGINX, and we can modify the nginx.conf
and fastcgi.conf
to customize how Nginx works.
We can also see in the info page that Devbox has configured an NGINX service for us. Let's start this service with devbox services start nginx
, and then test it with curl
:
> devbox services start nginx
Installing nix packages. This may take a while... done.
Starting a devbox shell...
Service "nginx" started
> curl localhost:80
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Hello World!</title>
</head>
<body>
Hello World!
</body>
</html>
Plugin Configuration in detail
When Devbox detects a plugin for an installed package, it automatically applies its configuration and prints a short explanation. Developers can review this explanation anytime using devbox info <package_name>
.
Services
If your package can run as a daemon or background service, Devbox can configure and manage that service for you with devbox services
.
To learn more, visit our page on Devbox Services.
Environment Variables
Devbox stores default environment variables for your package in .devbox/virtenv/<package_name>/.env
in your project directory. Devbox automatically updates these environment variables whenever you run devbox shell
or devbox run
to match your current project, and developers should not check these .env
files into source control.
Customizing Environment Variables
If you want to customize the environment variables, you can override them in the init_hook
of your devbox.json
Helper Files
Helper files are files that your package may use for configuration purposes, such as NGINX's nginx.conf
file. When installing a package, Devbox will check for helper files in your project's devbox.d
folder and create them if they do not exist. If helper files are already present, Devbox will not overwrite them.
Customizing Helper Files
Developers should directly edit helper files and check them into source control if needed
Plugins Source Code
Devbox Plugins are written in JSON and stored in the main Devbox Repo. You can view the source code of the current plugins here