Environment Setup¶
This guide covers how to set up your development environment after generating a project from the template.
Dev Container Setup (VS Code)¶
The fastest path to a working environment. Everything is configured inside the container.
Prerequisites¶
- VS Code
- Dev Containers extension
- Docker Desktop installed and running
Steps¶
- Open your project in VS Code:
code path/to/your/project
-
VS Code will detect the
.devcontainerconfiguration and prompt you to Reopen in Container. Click the prompt, or pressF1and runDev Containers: Reopen in Container. -
Wait for the container to build (first time takes a few minutes).
Docker Troubleshooting¶
- Docker must be running before you reopen in a container. Start Docker Desktop and wait for the engine status to show "Running."
- Windows permission errors: Your account may need to be added to the
docker-usersgroup. In an elevated PowerShell:net localgroup docker-users "YOUR_DOMAIN\YOUR_USERNAME" /ADD, then sign out and back in. - Container build fails: Try rebuilding via
F1>Dev Containers: Rebuild Container.
Local Development Setup¶
Prerequisites ¶
On Windows, all three can be installed via winget in PowerShell:
winget install --id Git.Git
winget install --id astral.uv
winget install --id Casey.Just
Steps ¶
- Navigate to your project directory:
cd <project-directory>
- Run the install command:
just install
This runs uv sync to create the virtual environment and install all dependencies, then runs pre-commit install to set up pre-commit hooks.
Installing Additional Packages¶
Add a new package:
uv add <package>
Update all packages to their latest compatible versions:
uv lock -U
Just Commands¶
Run just with no arguments to see all available commands.
| Command | Description |
|---|---|
just |
Show available commands |
just install |
Install dependencies and pre-commit hooks |
just render |
Render Quarto reports in reports/ to reports/_output |
just ruff |
Run Ruff linting (--fix) and formatting |
just run_jupyter |
Start a Jupyter notebook server |
VS Code Settings¶
The template includes .vscode/settings.json and .vscode/launch.json with sensible defaults.
settings.json¶
- Python interpreter: Set to
.venv/bin/pythonso VS Code picks up the uv-managed virtual environment automatically. - Default terminal: zsh on macOS and Linux, Git Bash on Windows.
launch.json¶
- Debug Tests: A launch configuration for debugging pytest. It sets
PYTEST_ADDOPTS=--no-covto disable coverage during debug sessions (coverage interferes with the debugger's breakpoints).
Next Steps¶
After setting up your environment, you're ready to start developing. See the Project Structure guide for an overview of what's in your project.