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
Starts a new interactive shell and runs your target script in it. The shell will exit once your target script is completed or when it is terminated via CTRL-C. Scripts can be defined in your `devbox.json`
4
+
5
+
For more details, read our [scripts guide](../guides/scripts.md)
6
+
7
+
```bash
8
+
devbox run <script> [flags]
9
+
```
10
+
11
+
## Options
12
+
13
+
```text
14
+
-c, --config string path to directory containing a devbox.json config file
15
+
-h, --help help for run
16
+
```
17
+
18
+
## SEE ALSO
19
+
20
+
*[devbox](./devbox.md) - Instant, easy, predictable shells and containers
Copy file name to clipboardExpand all lines: docs/app/docs/configuration.md
+56-11Lines changed: 56 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,11 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
9
9
{
10
10
"packages": [],
11
11
"shell": {
12
-
"init_hook": "..."
12
+
"init_hook": "...",
13
+
"scripts": {}
14
+
},
15
+
"nixpkgs": {
16
+
"commit": "..."
13
17
},
14
18
"install_stage": {
15
19
"command": "..."
@@ -31,7 +35,13 @@ You can add packages to your devbox.json using `devbox add <package_name>`, and
31
35
32
36
### Shell
33
37
34
-
You can configure `devbox shell` to run a custom commands at startup by setting an `init_hook`. This hook runs after any other `~/.*rc` scripts, allowing you to override environment variables or further customize the shell.
38
+
The Shell object defines init hooks and scripts that can be run with your shell. Right now two fields are supported: *init_hooks*, which run a set of commands every time you start a devbox shell, and *scripts*, which are commands that can be run using `devbox run`
39
+
40
+
#### Init Hook
41
+
42
+
The init hook is used to run shell commands before the shell finishes setting up. This hook runs after any other `~/.*rc` scripts, allowing you to override environment variables or further customize the shell.
43
+
44
+
The init hook will run every time a new shell is started using `devbox shell` or `devbox run`, and is best used for setting up environment variables, aliases, or other quick setup steps needed to configure your environment. For longer running tasks, you should consider using a Script.
35
45
36
46
This is an example `devbox.json` that customizes the prompt and prints a welcome message:
37
47
@@ -53,9 +63,41 @@ Welcome! See CONTRIBUTING.md for tips on contributing to devbox.
53
63
📦 devbox>
54
64
```
55
65
66
+
#### Scripts
67
+
68
+
Scripts are commands that are executed in your Devbox shell using `devbox run <script_name>`. They can be used to start up background process (like databases or servers), or to run one off commands (like setting up a dev DB, or running your tests).
69
+
70
+
Scripts can be defined by giving a name, and one or more commands. Single command scripts can be added by providing a name, and a string:
71
+
72
+
```json
73
+
"scripts": {
74
+
"print_once": "echo \"Hello Once!\""
75
+
}
76
+
```
77
+
78
+
To run multiple commands in a single script, you can pass them as an array:
79
+
80
+
```json
81
+
"scripts": {
82
+
"print_twice": [
83
+
"echo \"Hello Once!\"",
84
+
"echo \"Hello Twice!\""
85
+
]
86
+
}
87
+
```
88
+
89
+
### Nixpkgs
90
+
91
+
The Nixpkg object is used to optionally configure which version of the Nixpkgs repository you want Devbox to use for installing packages. It currently takes a single field, `commit`, which takes a commit hash for the specific revision of Nixpkgs you want to use.
92
+
93
+
If a Nixpkg commit is not set, Devbox will automatically add a default commit hash to your `devbox.json`. To upgrade your packages to the latest available versions in the future, you can replace the default hash with the latest nixpkgs-unstable hash from https://status.nixos.org
94
+
95
+
To learn more, consult our guide on [setting the Nixpkg commit hash](guides/pinning_packages.md).
96
+
97
+
56
98
### Stages
57
99
58
-
Stages are used to configure and run commands at different points of container creation. For languages that support autodetction, Devbox will automatically detect and configure the correct stage commands for your project based on your source code. You can override any of these stages by configuring them in your devbox.json
100
+
Stages are used to configure and run commands at different points of container creation. For languages that support autodetection, Devbox will automatically detect and configure the correct stage commands for your project based on your source code. You can override any of these stages by configuring them in your devbox.json
59
101
60
102
- The **install stage** will run after your base container has been initialized and your Nix packages are installed. This stage should be used to download and build your application's dependencies
61
103
- The **build stage** runs after the install stage, and should be used to build or bundle your application.
@@ -81,14 +123,17 @@ An example of a devbox configuration for a Rust project called `hello_world` mig
This doc will explain how to select and pin specific package versions in Devbox by setting a Nixpkg commit in your devbox.json
6
+
7
+
## Background
8
+
9
+
The Nix Package Manager, which Devbox uses to install your shell packages, stores it's package definitions in a Github Repository at [NixOS/nixpkgs](https://github.com/NixOS/nixpkgs). This repository contains the Nix build definitions for over 80,000 different packages. New packages or changes to build definitions are added (and deprecated packages are removed) by committing to the repo.
10
+
11
+
Because Nix uses Git to store it's package definitions, we can install specific packages from older versions of the Nix Store by specifying the commit that we want to use. You can also use this commit to pin your project to a specific version of Nixpkgs, so that any developer using your project will get the exact same packages.
12
+
13
+
## Pinning the Nixpkg commit in your Devbox.json
14
+
15
+
Devbox stores the Nixpkg commit in your project's `devbox.json`, under the `nixpkgs.commit`. If you do not specify one in your config, Devbox will automatically add a default commit hash when you run a command like `devbox add`, `devbox shell`, or `devbox run`:
This hash ensures that Devbox will install the same packages whenever you start a shell. By checking this into source control, you can also ensure that any other developers who run your project will get the same packages.
23
+
24
+
## Using the latest version of Nixpkgs
25
+
26
+
To use the latest available packages in Nix, you can replace the commit in `devbox.json` with the latest `nixpkgs-unstable` hash from https://status.nixos.org.
27
+
28
+
## Look up a commit hash for a specific package
29
+
30
+
In most cases, the packages available in Devbox's default commit should suffice for your use cases. However, if you need a specific minor version, or an older version of a package that is no longer included in Nixpkgs, you may need update the commit SHA. Unfortunately, Nix does not have an official way to find the Nixpkg commit SHA for a specific version of a package.
31
+
32
+
However, there is an unofficial search tool at https://lazamar.co.uk/nix-versions/ that can be used to list the Nixpkg commits for different versions of a specific package.
This doc describes how to configure and run scripts using `devbox run`. Scripts started with `devbox run` are launched in a interactive `devbox shell` that terminates once the script finishes, or is interrupted by CTRL-C.
6
+
7
+
Scripts will run after your packages finish installing, and after your `init_hook` completes.
8
+
9
+
## Configuring scripts
10
+
11
+
Scripts can be added in your `devbox.json`. Scripts require a unique name, and a command or list of commands to run:
12
+
13
+
```json
14
+
"shell": {
15
+
"init_hook": "echo \"Hello \"",
16
+
"scripts": {
17
+
"echo_once": "echo \"World\"",
18
+
"echo_twice": [
19
+
"echo \"World\"",
20
+
"echo \"Again\""
21
+
]
22
+
}
23
+
}
24
+
```
25
+
26
+
## Running your scripts
27
+
28
+
To run a script, use `devbox run <script_name>`. This will start your shell, run your `init_hook`, and then run the script:
29
+
30
+
```bash
31
+
$ devbox run echo_once
32
+
Installing nix packages. This may take a while... done.
33
+
Starting a devbox shell...
34
+
Hello
35
+
World
36
+
37
+
$ devbox run echo_twice
38
+
Installing nix packages. This may take a while... done.
39
+
Starting a devbox shell...
40
+
Hello
41
+
World
42
+
Again
43
+
```
44
+
45
+
Your devbox shell will exit once the last line of your script has finished running, or when you interrupt the script with CTRL-C (or a SIGINT signal).
46
+
47
+
48
+
## Tips on using Scripts
49
+
50
+
1. Since `init_hook` runs everytime you start your shell, you should use primarily use it for setting environment variables and aliases. For longer running tasks like database setup, you can create and run a Devbox script
51
+
2. You can use Devbox scripts to start and manage long running background processes and daemons. For example -- If you are working on a LAMP stack project, you can use scripts to start MySQL and Apache in separate shells and monitor their logs. Once you are done developing, you can use CTRL-C to exit the processes and shells
52
+
3. If a script feels too long to put it directly in `devbox.json`, you can save it as a shell script in your project, and then invoke it in your `devbox scripts`.
53
+
4. For more ideas, see the LAMP stack example in our [Devbox examples repo](https://github.com/jetpack-io/devbox-examples/tree/main/stacks/lamp-stack).
0 commit comments