diff --git a/docs/app/docs/cli_reference/devbox_add.md b/docs/app/docs/cli_reference/devbox_add.md index e5208dcbd40..13d8b48c217 100644 --- a/docs/app/docs/cli_reference/devbox_add.md +++ b/docs/app/docs/cli_reference/devbox_add.md @@ -33,9 +33,9 @@ devbox add prometheus --outputs=out,cli | `--environment string` | Jetify Secrets environment to use, when supported (e.g.secrets support dev, prod, preview.) (default "dev") | | `-e, --exclude-platform strings` | exclude packages from a specific platform. | | `-h, --help` | help for add | -| `-o, --outputs strings` | specify the outputs to install for the nix package | +| `-o, --outputs strings` | specify the outputs to install for the nix package | | `-p`, `--platform strings` | install packages only on specific platforms. | -| `--patch-glibc` | Patches ELF binaries to use a newer version of `glibc` | +| `--patch` | Allow Devbox to patch your packages to fix issues with missing native libraries (auto, always, never) (default "auto")| | `-q, --quiet` | quiet mode: Suppresses logs. | Valid Platforms include: @@ -54,4 +54,3 @@ The platforms below are also supported, but will build packages from source ## SEE ALSO * [devbox](./devbox.md) - Instant, easy, predictable shells and containers - diff --git a/docs/app/docs/cli_reference/devbox_services_attach.md b/docs/app/docs/cli_reference/devbox_services_attach.md new file mode 100644 index 00000000000..19d48933d5e --- /dev/null +++ b/docs/app/docs/cli_reference/devbox_services_attach.md @@ -0,0 +1,21 @@ +# devbox services attach + +Attach to a running instance of `devbox services`. This command lets you launch the TUI for process-compose if you started your services in the background with `devbox services up -b`. + +Note that terminating the TUI will not stop your backgrounded services. To stop your services, use `devbox services stop`. + +```bash +devbox services attach [flags] +``` + +## Options + + +| Option | Description | +| --- | --- | +| `-h, --help` | help for ls | +| `-q, --quiet` | Quiet mode: Suppresses logs. | + +### SEE ALSO + +* [devbox services](devbox_services.md) - Interact with devbox services diff --git a/docs/app/docs/cli_reference/devbox_services_up.md b/docs/app/docs/cli_reference/devbox_services_up.md index fa532b5dc32..4dd30677f0d 100644 --- a/docs/app/docs/cli_reference/devbox_services_up.md +++ b/docs/app/docs/cli_reference/devbox_services_up.md @@ -31,10 +31,11 @@ devbox services up web | `-e, --env stringToString` | environment variables to set in the devbox environment (default []) | | `--env-file string` | path to a file containing environment variables to set in the devbox environment | | `-h, --help` | help for up | +| `--pcflags stringArray` | additional flags to pass directly to process-compose | +| `-p, --pcport int` | specify the port for process-compose to use. You can also set the pcport by exporting DEVBOX_PC_PORT_NUM | | `--process-compose-file string` | path to process compose file or directory containing process compose-file.yaml\|yml. Default is directory containing devbox.json | | `-q, --quiet` | Quiet mode: Suppresses logs. | ## SEE ALSO * [devbox services](devbox_services.md) - Interact with devbox services - diff --git a/docs/app/docs/configuration.md b/docs/app/docs/configuration.md index 84c1ef4936f..d4523f0b240 100644 --- a/docs/app/docs/configuration.md +++ b/docs/app/docs/configuration.md @@ -36,7 +36,7 @@ Packages can be structured as a list of package names (`@`) o If you need to provide more options to your packages (such as limiting which platforms will install the package), you can structure packages as a map, where each package follows the schema below: -```json +```js { "packages": { // If only a version is specified, you can abbreviate the maps as "package_name": "version" @@ -44,6 +44,8 @@ If you need to provide more options to your packages (such as limiting which pla "package_name": { // Version of the package to install. Defaults to "latest" "version": string, + // Whether native library patching is enabled for this package. This defaults to `auto`, but can be overridden to `always` or `never` for individual packages. + "patch": ["auto" | "always" | "never"], // List of platforms to install the package on. Defaults to all platforms "platforms": [string], // List of platforms to exclude this package from. Defaults to no excluded platforms @@ -244,9 +246,9 @@ To run multiple commands in a single script, you can pass them as an array: ### Include -Includes can be used to explicitly add extra configuration from [plugins](./guides/plugins.md) to your Devbox project. Plugins are parsed and merged in the order they are listed. +Includes can be used to explicitly add extra configuration from [plugins](./guides/plugins.md) to your Devbox project. Plugins are parsed and merged in the order they are listed. -Note that in the event of a conflict, plugins near the end of the list will override plugins at the beginning of the list. Likewise, if a setting in your project config conflicts with a plugin (e.g., your `devbox.json` has a script with the same name as a plugin script), your project config will take precedence. +Note that in the event of a conflict, plugins near the end of the list will override plugins at the beginning of the list. Likewise, if a setting in your project config conflicts with a plugin (e.g., your `devbox.json` has a script with the same name as a plugin script), your project config will take precedence. ```json { "include": [ diff --git a/docs/app/docs/devbox_examples/languages/go.md b/docs/app/docs/devbox_examples/languages/go.md index 962b98a902d..0629c9b5f1a 100644 --- a/docs/app/docs/devbox_examples/languages/go.md +++ b/docs/app/docs/devbox_examples/languages/go.md @@ -20,7 +20,7 @@ Go projects can be run in Devbox by adding the Go SDK to your project. If your p This will install the latest version of the Go SDK. You can find other installable versions of Go by running `devbox search go`. You can also view the available versions on [Nixhub](https://www.nixhub.io/packages/go) -If you need additional C libraries, you can add them along with `gcc` to your package list. For example, if libcap is required for yoru project: +If you need additional C libraries, you can add them along with `gcc` to your package list. For example, if libcap is required for your project: ```json "packages": [ @@ -32,9 +32,9 @@ If you need additional C libraries, you can add them along with `gcc` to your pa ## Installing go packages that have CLIs -Installing go packages in your devbox shell is as simple as `go get ` but some packages come with a CLI of their own (e.g., `godotenv`). That means after installing the package you should be able to use the CLI binary and also control where that binary is installed. This is done by setting `$GOPATH` or `$GOBIN` env variable. +Installing go packages in your devbox shell is as simple as `go get ` but some packages come with a CLI of their own (e.g., `godotenv`). That means after installing the package you should be able to use the CLI binary and also control where that binary is installed. This is done by setting `$GOPATH` or `$GOBIN` env variable. -With Devbox you can set these variables in the `"env"` section of your `devbox.json` file. +With Devbox you can set these variables in the `"env"` section of your `devbox.json` file. In the example below we are setting `$GOPATH` to be the same directory of our project and therefore `godotenv` binary will be located in the `bin/` subdirectory of `$GOPATH`: ```json diff --git a/docs/app/docs/env_variables.md b/docs/app/docs/env_variables.md new file mode 100644 index 00000000000..ed12516e67f --- /dev/null +++ b/docs/app/docs/env_variables.md @@ -0,0 +1,33 @@ +--- +title: Devbox Env Variables +--- + +The following is a list of Environment variables used by Devbox to manage your environment. Some of these variables are set by Devbox, while others can be used to manage how Devbox sets up your shell. + +Note that this list only describes variables that are set by Devbox itself. [Devbox plugins](/guides/plugins) may set their own environment variables, which are documented in their respective pages and via `devbox info `. + +## Environment Variables Set by Devbox Shell + +Below are some useful environment variables that Devbox sets up for you. These variables can be used in your scripts to access information or write scripts for your current project environment. + +| Variable | Description | +|:--------|:-----------| +|`DEVBOX_CONFIG_DIR`| The directory where Devbox stores user-editable config files for your project's packages. These files can be checked into source control | +|`DEVBOX_PACKAGES_DIR`| The directory containing the binaries and files for the packages in your current project | +| `DEVBOX_PROJECT_ROOT` | The root directory of your current project. This will match the directory location of the `devbox.json` file for your currently running shell | +| `DEVBOX_PURE_SHELL` | Indicates whether you are running your current shell in pure mode. Pure mode clears your current environment variables before starting a devbox shell | +| `DEVBOX_SHELL_ENABLED` | Whether or not Devbox is enabled in the current shell. This is automatically set to `1` when you start a shell, run a script, or start services | +| `DEVBOX_WD` | Your current working directory. This can be used when writing scripts that you want to run in your current directory, instead of DEVBOX_PROJECT_ROOT | + + +## Environment Variables for Managing Devbox + +Below are some environment variables that can be used to manage how Devbox sets up your shell. These variables can be set in your shell or in your `devbox.json` file. + +| Variable | Description | Value | +|:--------|:-----------|:------------| +|`DEVBOX_DEBUG` | Enable debug output for Devbox. If set to 1, this will print out additional information about what Devbox is doing. | 0 | +|`DEVBOX_FEATURE_DETSYS_INSTALLER` | If enabled, Devbox will use the Determinate Systems installer to setup Nix on your system. _This variable must be set on your host_ | 0 | +|`DEVBOX_NO_PROMPT` | Disables the default shell prompt modification for Devbox. Usually used if you want to configure your own prompt for indicating that you are in a devbox sell | 0 | +|`DEVBOX_PC_PORT_NUM` | Sets the port number for process-compose when running Devbox services. If this variable is unset and a port is not provided via the CLI, Devbox will choose a random available port | `unset` | +|`DEVBOX_USE_VERSION` | Setting this variable will force Devbox to use a different version than the current latest. For example: `DEVBOX_USE_VERSION=0.13.0` will install and use Devbox v0.13 for all Devbox commands. _This variable must be set on your host_ | `unset`| diff --git a/docs/app/docs/faq.md b/docs/app/docs/faq.md index 0ca6df6f516..c003a01c505 100644 --- a/docs/app/docs/faq.md +++ b/docs/app/docs/faq.md @@ -31,15 +31,15 @@ Yes! Devbox can be installed on any Linux distribution, including NixOS. You can ## A package I installed is missing header files or libraries I need for development. Where do I find them? -In order to save space, Devbox and Nix only install the required components of packages by default. Development header files and libraries are often installed in a separate output of the package (usually `dev`), which can be installed using the `--output` flag on the `devbox add` command. +In order to save space, Devbox and Nix only install the required components of packages by default. Development header files and libraries are often installed in a separate output of the package (usually `dev`), which can be installed using the `--output` flag on the `devbox add` command. -For example, the command below will install both the default output `out`, and the `cli` output for the prometheus package: +For example, the command below will install both the default output `out`, and the `cli` output for the prometheus package: ```bash devbox add prometheus --outputs=out,cli ``` -You can also specify non-default outputs in [flake references](./guides/using_flakes.md): +You can also specify non-default outputs in [flake references](./guides/using_flakes.md): ```bash devbox add github:NixOS/nixpkgs#prometheus^out,cli @@ -47,22 +47,22 @@ devbox add github:NixOS/nixpkgs#prometheus^out,cli ## One of my project's packages is taking a long time to install. How can I speed up the installation process? -Packages may take a long time to install if they do not have a binary available in the public Nix Cache. If a prebuilt binary is not available, Nix will built the package from source. +Packages may take a long time to install if they do not have a binary available in the public Nix Cache. If a prebuilt binary is not available, Nix will built the package from source. If prebuilt binaries are not available in the public cache, you may want to use the [Jetify Cache](./cloud/cache/index.md) or the [Jetify Prebuilt Cache](./cloud/cache/prebuilt_cache.md) to cache the binaries you build for future use. Using a package cache can reduce package install by up to 90% compared to building from source. ## I'm trying to build a project, but it says that I'm missing `libstdc++`. How do I install this library in my project? -This message means that your project requires an implementation of the C++ Standard Library installed and linked within your shell. You can add the libstdc++ libraries and object files using `devbox add stdenv.cc.cc.lib`. +This message means that your project requires an implementation of the C++ Standard Library installed and linked within your shell. You can add the libstdc++ libraries and object files using `devbox add stdenv.cc.cc.lib`. -## I'm seeing a ``GLIBC_X.XX' not found` error when I try to install my packages, or when I install packages from PyPi/RubyGems/NPM/Cargo/other package manager in my shell +## I'm seeing errors like ``GLIBC_X.XX' not found` when I try to install my packages, or when I install packages from PyPi/RubyGems/NPM/Cargo/other package manager in my shell -This message usually occurs when using older packages, or when mixing different versions of packages within a single shell. The error tends to occur because each Nix package comes bundled with all of it's dependencies, including a version of the C Standard Library, to ensure reproducibility. If your interpreter (Python/Ruby/Node) or runtime is using an older version of `glibc` than what your other packages expect, they will throw this error. +This message usually occurs when using older packages, or when mixing different versions of packages within a single shell. The error tends to occur because each Nix package comes bundled with all of it's dependencies, including a version of the C Standard Library, to ensure reproducibility. If your interpreter (Python/Ruby/Node) or runtime is using an older version of `glibc` than what your other packages expect, they will throw this error. -There are three ways to work around this issue: -1. You can update your packages to use a newer version (using `devbox add`). This newer version will likely come bundled with a newer version of `glibc`. +There are three ways to work around this issue: +1. You can update your packages to use a newer version (using `devbox add`). This newer version will likely come bundled with a newer version of `glibc`. 2. You can use `devbox update` to get the latest Nix derivation for your package. Newer derivations may come bundled with newer dependencies, including `glibc` -3. If you need to use an exact package version, but you still see this error, you can patch it to use a newer version of glibc using `devbox add @ --patch-glibc`. This will patch your package to use a newer version of glibc, which should resolve any incompatibility issues you might be seeing. **This patch will only affect packages on Linux.** +3. If you need to use an exact package version, but you still see this error, you can patch it to use a newer version of glibc using `devbox add @ --patch always`. This will patch your package to use the latest version of glibc available in the Nix store, as well as patching it to use any native libraries you have installed with Devbox. ## How can I use custom Nix packages or overrides with Devbox? @@ -70,13 +70,13 @@ You can add customized packages to your Devbox environment using our [Flake supp ## Can I use Devbox if I use [Fish](https://fishshell.com/)? -Yes. In addition to supporting POSIX compliant shells like Zsh and Bash, Devbox also works with Fish. +Yes. In addition to supporting POSIX compliant shells like Zsh and Bash, Devbox also works with Fish. -Note that `init_hooks` in Devbox will be run directly in your host shell, so you may have encounter some compatibility issues if you try to start a shell that uses a POSIX-compatible script in the init_hook. +Note that `init_hooks` in Devbox will be run directly in your host shell, so you may have encounter some compatibility issues if you try to start a shell that uses a POSIX-compatible script in the init_hook. ## How can I rollback to a previous version of Devbox? -You can use any previous version of Devbox by setting the `DEVBOX_USE_VERSION` environment variable. For example, to use version 0.8.0, you can run the following or add it to your shell's rcfile: +You can use any previous version of Devbox by setting the `DEVBOX_USE_VERSION` environment variable. For example, to use version 0.8.0, you can run the following or add it to your shell's rcfile: ```bash export DEVBOX_USE_VERSION=0.8.0 @@ -92,7 +92,12 @@ By default, Devbox will prefix your prompt with `(devbox)` when inside a `devbox DEVBOX_NO_PROMPT=true ``` -You can now detect being inside a `devbox shell` and change your prompt using the method of your choosing. +If you are using Fish: + +```fish +set -U devbox_no_prompt true +``` + ## How can I uninstall Devbox? diff --git a/docs/app/docs/guides/services.md b/docs/app/docs/guides/services.md index ea685e32390..ec46564abba 100644 --- a/docs/app/docs/guides/services.md +++ b/docs/app/docs/guides/services.md @@ -16,6 +16,16 @@ You can also start a specific service by passing the name as an argument. For ex If you want to restart your services (for example, after changing your configuration), you can run `devbox services restart` +## Starting your Services in the Background + +If you want to start your services in the background, without launching the process-compose TUI, you can use the `-b` flag. For example, to start all services in the background, you can run `devbox services up -b`. + +Services started in the background will continue running, even if the current shell is closed. To stop your backgrounded services, run `devbox services stop`. + +To see the current state of your running services, you can run `devbox services ls`. + +You can also attach the process-compose TUI to your running background services by running `devbox services attach`. + ## Defining your Own Services If you have a process or service that you want to run with your Devbox project, you can define it using a process-compose.yml in your project's root directory. For example, if you want to run a Django server, you could add the following yaml: @@ -76,8 +86,6 @@ You can stop your services with `devbox services stop`. This will stop process-c If you want to stop a specific service, you can pass the name as an argument. For example, to stop just `postgresql`, you can run `devbox services stop postgresql` - - ## Further Reading * [**Devbox Services CLI Reference**](../cli_reference/devbox_services.md) diff --git a/docs/app/docs/installing_devbox.mdx b/docs/app/docs/installing_devbox.mdx index 9b456ecfc13..ce8405f9291 100644 --- a/docs/app/docs/installing_devbox.mdx +++ b/docs/app/docs/installing_devbox.mdx @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; Select your OS below for the steps to install Devbox. - + Run the following install script as a *non-root user* to install the latest version of Devbox: @@ -39,7 +39,7 @@ If you would like to install Nix yourself, we recommend the [Determinate Nix Ins -You can use Devbox on a Windows machine using [**Windows Subsystem for Linux 2**](https://learn.microsoft.com/en-us/windows/wsl/install). +You can use Devbox on a Windows machine using [**Windows Subsystem for Linux 2**](https://learn.microsoft.com/en-us/windows/wsl/install).
Installing WSL2 @@ -71,7 +71,7 @@ Devbox requires the [Nix Package Manager](https://nixos.org/download/). If Nix i -Devbox is available through the [**Nix Package Manager**](https://search.nixos.org/packages?channel=unstable&show=devbox&from=0&size=50&sort=relevance&type=packages&query=devbox). +Devbox is available through the [**Nix Package Manager**](https://search.nixos.org/packages?channel=unstable&show=devbox&from=0&size=50&sort=relevance&type=packages&query=devbox). To install on NixOS: @@ -85,18 +85,38 @@ To install on a non NixOS: nix-env -iA nixpkgs.devbox ``` -or +or ```bash nix profile install nixpkgs#devbox ``` +Note: New releases of Devbox need to be updated in Nixpkgs before they are available for installation. If you want to use the latest version of Devbox, you can install it using the [Nix Flake](.?install-method=flake). + + + + +You can also install Devbox on a NixOS/Nixpkgs system using our Nix Flake. Using the Nix Flake can help you access pre-releases and final releases of Devbox as soon as they are published. + +To get the latest version: + +```bash +nix profile install github:jetify-com/devbox/latest +``` + +To install a specific version, you can run the following command (only supports versions 0.13.2 and above). + +```bash +nix profile install github:jetify-com/devbox/0.13.2 +``` + + ## Updating Devbox -Devbox will notify you when a new version is available. To update to the latest released version of Devbox, you can run `devbox version update`. +Devbox will notify you when a new version is available. To update to the latest released version of Devbox, you can run `devbox version update`. If you installed Devbox with Nix, you can update Devbox via Nix using `nix-env -u devbox`, or `nix profile upgrade`. @@ -104,15 +124,15 @@ You can find release notes and details on the [Releases page](https://github.com ## Rolling Back or Pinning a Specific Version of Devbox -You can rollback or pin the version of Devbox on your system using the `DEVBOX_USE_VERSION` environment variable. For example, to use version 0.8.0: +You can rollback or pin the version of Devbox on your system using the `DEVBOX_USE_VERSION` environment variable. For example, to use version 0.8.0: ```bash export DEVBOX_USE_VERSION=0.8.0 ``` -Setting this variable will use the specified version of Devbox even if a newer version has been installed on your machine. +Setting this variable will use the specified version of Devbox even if a newer version has been installed on your machine. -If you installed Devbox with Nixpkgs, you will need to pin Devbox in your profile or Nix configuration. You can find the Nixpkg commits for previous versions of Devbox on [Nixhub](https://www.nixhub.io/packages/devbox). +If you installed Devbox with Nixpkgs, you will need to pin Devbox in your profile or Nix configuration. You can find the Nixpkg commits for previous versions of Devbox on [Nixhub](https://www.nixhub.io/packages/devbox). ## Next Steps diff --git a/docs/app/sidebars.js b/docs/app/sidebars.js index 2aebba600bf..b135a4c1752 100644 --- a/docs/app/sidebars.js +++ b/docs/app/sidebars.js @@ -169,6 +169,10 @@ const sidebars = { type: "doc", id: "configuration", }, + { + type: "doc", + id: "env_variables", + }, { type: "doc", id: "devbox_cloud/beta_faq", @@ -251,16 +255,18 @@ const sidebars = { }, ], - apiSidebar: [{ - type: "category", - label: "Nixhub API Reference", - collapsed: false, - link: { - type: "doc", - id: "nixhub/index" + apiSidebar: [ + { + type: "category", + label: "Nixhub API Reference", + collapsed: false, + link: { + type: "doc", + id: "nixhub/index", + }, + items: require("./docs/nixhub/sidebar"), }, - items: require("./docs/nixhub/sidebar"), - }], + ], }; export default sidebars;