Setting Up a Development Environment with Devbox¶

Creating a reliable, reproducible development environment is crucial, especially for infrastructure management tasks like using Ansible. This guide shows you how to set up a powerful development environment using Devbox, ensuring your projects are consistent across your team and deployments. We'll focus on setting up Devbox with Python 3.12.

What is Devbox?¶

Devbox is an open-source tool that provides developer environments using Nix - without requiring you to learn Nix. It creates isolated, reproducible development environments that work across any machine.

Key benefits for development include:

Consistent environments: Everyone on your team uses identical setups
Isolated workspaces: No conflicts with existing system installations (like Python)
Version pinning: Exact versions of tools (like Python) for reliable execution
Simplified dependencies: Package management handled in a declarative way
Portability: Works on macOS, Linux, and WSL on Windows

Prerequisites¶

Before starting, make sure you have:

A system running Linux, macOS, or Windows with WSL
Basic familiarity with command line interfaces
Git installed on your system (recommended for managing your Devbox configuration)

Installing Devbox¶

Let's begin by installing Devbox:

Linux/macOSWindows (PowerShell)

curl -fsSL https://get.jetpack.io/devbox | bash

irm https://get.jetpack.io/devbox | iex

Tip

If you prefer not to use the install script, you can download the binary directly from the Devbox releases page.

Verify your installation:

devbox version

Creating Your Development Environment with Devbox¶

Now let's create a dedicated environment, for example, one suitable for Ansible development with Python 3.12:

Create a new directory for your project:

mkdir my-dev-environment
cd my-dev-environment

Initialize a new Devbox project:
```
devbox init
```
This creates a devbox.json file that will define your development environment.

Edit the devbox.json file to specify Python 3.12 and set up a virtual environment:

{
 "packages": [
   "python@3.12",
   "openssl@latest",
   "gnupg@latest",
   "pwgen@latest" // Example: Include tools needed for your workflow
 ],
 "shell": {
   "init_hook": [
     "if [ ! -d .venv ]; then echo 'Creating virtual environment...' && python -m venv .venv; fi",
     "source .venv/bin/activate",
     "if [ ! -f .venv/.installed ]; then pip install -r requirements.txt && touch .venv/.installed; fi",
    "echo 'Virtual environment activated. Python packages installed from requirements.txt'"
   ],
   "scripts": {
     "update-deps": "source .venv/bin/activate && pip install -r requirements.txt && touch .venv/.installed"
   }
 }
}

Note: The init_hook here automatically creates and activates a Python virtual environment and installs dependencies from requirements.txt when you enter the shell.

Shell Compatibility

The init_hook commands in devbox.json always use bash/sh syntax, regardless of your default shell (Fish, Zsh, etc.). Devbox executes these commands in a bash context internally.

Always use bash/sh syntax in your init_hook - do not adapt the syntax for your shell. The example above with if [ ... ]; then ...; fi and source .venv/bin/activate is correct for all users.

Create a requirements.txt file for your Python dependencies (example for Ansible):
```
# Example for an Ansible project
ansible==9.1.0
ansible-lint==6.22.0
pytest-ansible==25.1.0
yamllint==1.32.0
```
Adjust the versions and packages based on your project's needs. Check for the latest versions when setting up your environment.
Enter your development environment:
```
devbox shell
```
The first time you run this, Devbox will download and install all the specified packages (like Python 3.12). This might take a few minutes, but subsequent launches will be much faster. Your init_hook will also run, setting up the Python virtual environment and installing packages from requirements.txt.

You now have an isolated development environment managed by Devbox! The next steps would typically involve setting up your specific project structure (e.g., for Ansible, web development, etc.) within this environment.

Updating Your Environment¶

When you need to update package versions (like Python or Ansible) or add new tools:

Modify your devbox.json (for Devbox packages) or requirements.txt (for Python packages).
Run devbox update to update Devbox packages specified directly in devbox.json.

If you updated requirements.txt, run the update script defined in devbox.json:

# Assuming the script name 'update-deps' as defined earlier
devbox run update-deps

Or simply exit and re-enter the shell:

exit
devbox shell # init_hook should reinstall requirements

Commit the updated devbox.json, devbox.lock, and requirements.txt files to Git so your team gets the updates.

Troubleshooting Common Issues¶

DevBox shell fails¶

If the devbox shell fails remove installed environment, that will force devbox to reinstall all packages:

rm -rf .devbox
devbox shell

Python Package Installation Failures¶

If the init_hook fails or Python packages don't install correctly:

Check error messages carefully inside 'devbox shell'
Manually trigger the dependency installation script
```
devbox run update-deps
```

Force recreation of the virtual environment (destructive)

rm -rf .venv
devbox shell # This will re-trigger the init_hook

Check network connectivity / proxy settings if packages fail to download

Next - Setup Ansible