Update docs for 0.13 series (#2312)

## Summary
* Update Services docs to include all new features (attach, port
selection)
* Document `--patch` flag and json config
* Document installation via nix flake
* Document Devbox Environment Variables

## How was it tested?
localhost, `devbox run -- pnpm build`

---------

Signed-off-by: John Lago <[email protected]>
Co-authored-by: Lucille Hua <[email protected]>

Author: Lagoja

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
-

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
+
+<!-- Markdown Table of 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

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
-

docs/app/docs/configuration.md

@@ -36,14 +36,16 @@ Packages can be structured as a list of package names (`<packages>@<version>`) 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"
         "package_name": string,
         "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": [

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 <package_name>` 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 <package_name>` 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

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 <package>`.
+
+## 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`|

docs/app/docs/faq.md

@@ -31,52 +31,52 @@ 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
 ```
 
 ## 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 <package>@<version> --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 <package>@<version> --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?
 
 You can add customized packages to your Devbox environment using our [Flake support](./guides/using_flakes.md). You can use these flakes to modify or override packages from nixpkgs, or to create your own custom packages.
 
 ## 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?
 

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)