Skip to content

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

Steps

  1. Open your project in VS Code:
code path/to/your/project
  1. VS Code will detect the .devcontainer configuration and prompt you to Reopen in Container. Click the prompt, or press F1 and run Dev Containers: Reopen in Container.

  2. 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-users group. 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

  1. Navigate to your project directory:
cd <project-directory>
  1. 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/python so 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-cov to 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.