Add devcontainer #3556

lars20070 · 2025-11-25T16:23:33Z

The pull request adds a new dev container for pydantic-ai. It is built using a hybrid approach: the Dockerfile provides low-level customization, while devcontainer.json is used for fine-tuning and IDE integration. Minor changes to devcontainer.json do not require a full rebuild of the entire image, which speeds up the development workflow.

The Dockerfile is based on Microsoft's Debian-style Trixie image for Python 3.12. It uses a non-root user named vscode and installs system dependencies, uv, and the Ollama client. Note that the Ollama instance runs on the host machine for performance reasons.
The devcontainer.json is based on Microsoft's dev container template for Python 3. It installs additional development tools via features, sets important environment variables, and runs uv sync. The container does not enforce any specific IDE configuration; developers are encouraged to mount their own .vscode/ or .cursor/ folders externally.

Added

dev container with Dockerfile and devcontainer.json
CI integration

lars20070 · 2025-11-28T13:23:39Z

@dsfaccini In the beginning, I had thought accessing the Ollama host instance with ollama list and ollama run from inside the container would be convenient. But I have now removed the Ollama CLI entirely. I agree that this is cleaner.

.env.example is a very good point. I have added it to the root directory.
Apologies for the flaky test comments. During early stages of the dev container setup I had seen these tests failing. But I have not been able to reproduce the failing tests since.
I have copied further configs from your branch to devcontainer.json. Most likely there are more missing, and I would appreciate your input.
I have configured MCP servers in .vscode and .cursor which are mounted externally. Works fine in my tests with Context7 and GitHub. In the IDE and MCP setup, I would leave as much as possible to the user.

Thanks for your good comments so far. Hope together we can find a stable and minimal dev container setup. Would be helpful for new contributers to get started.

DouweM · 2025-11-28T21:09:08Z

.devcontainer/Dockerfile

@@ -0,0 +1,27 @@
+ARG PYTHON_VERSION=3.11


Let's use 3.12 as in .python-version

Ok. Changed to 3.12.

DouweM · 2025-11-28T21:10:11Z

.devcontainer/Dockerfile

+# Enable Docker BuildKit for cache mounts
+ENV DOCKER_BUILDKIT=1
+
+# Install system dependencies with cache mount for faster rebuilds (pinned versions)


Pinning means we'll probably never update these; could we not pin even if that means the cache would be invalidated more often?

No. Unrelated to cache. This was for sake of reproducibility and avoid "works on my machine" issues.

I have changed the pinned to latest versions. Less maintenance. I do not expect problems here.

DouweM · 2025-11-28T21:10:42Z

.devcontainer/README.md

@@ -0,0 +1,36 @@
+## Requirements
+
+Please ensure that both [Docker](https://docs.docker.com/desktop/) and optionally [Ollama](https://ollama.com/download) are installed and running on the host machine. To configure your IDE, mount your own `.vscode/` or `.cursor/` folders by uncommenting the `mounts` section in `devcontainer.json`.


"ensure that both X and optionally Y" is a bit contradictory :) I'd rather have hard requirements, and then some section on optional things

Good point. Fixed.

DouweM · 2025-11-28T21:10:58Z

.devcontainer/README.md

+
+The dev container is built using a hybrid approach: the `Dockerfile` provides low-level customization, while `devcontainer.json` is used for fine-tuning and IDE integration. Minor changes to `devcontainer.json` do not require a full rebuild of the entire image, which speeds up the development workflow.
+
+1. The `Dockerfile` is based on Microsoft's Debian-style [Bookworm image for Python 3.11](https://hub.docker.com/r/microsoft/devcontainers-python). It uses a non-root user named `vscode` and installs system dependencies and `uv`.


3.12 please!

DouweM · 2025-11-28T21:11:15Z

.devcontainer/devcontainer.json

+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+  "name": "Python 3",


Pydantic AI?

DouweM · 2025-11-28T21:18:05Z

.env.example

+# ============================================================================
+
+# OpenAI (Required for: OpenAI models, OpenAI-compatible providers)
+# Get your key at: https://platform.openai.com/api-keys


This will get outdated, I'd rather just link to the docs for the provider in question

DouweM · 2025-11-28T21:18:40Z

.env.example

+
+# Brave Search (Optional - for web search tools)
+# Get your key at: https://brave.com/search/api/
+# BRAVE_API_KEY=


We don't have anything Brave related in Pydantic AI

DouweM · 2025-11-28T21:18:54Z

.env.example

+# GitHub Personal Access Token (Optional - for MCP GitHub server)
+# Create at: https://github.com/settings/tokens
+# Needs: repo, read:org scopes
+# GITHUB_PERSONAL_ACCESS_TOKEN=


We don't auto install this so we shouldn't have this

DouweM · 2025-11-28T21:20:25Z

.env.example

+
+# PostgreSQL with pgvector (Optional - for RAG examples)
+# Default when using docker-compose pgvector service:
+# PGVECTOR_DATABASE_URL=postgresql://postgres:postgres@localhost:54321/postgres


I'd rather this file stick to the point, so we don't have to struggle to keep it up to date when we add examples etc. If the example docs states to set a given env var, the user can figure out how to do that in the devcontainer.

For maintenance burden reasons, let's limit this file to the most popular providers; the user can figure out how to set the rest.

DouweM · 2025-11-28T21:20:53Z

.env.example

+# - For testing, use test models or Ollama to avoid API costs
+# - Never commit this file with real API keys
+# - Add .env to .gitignore (already done in this project)
+# - See README.md for detailed setup instructions per provider


This should direct them to the docs shouldn't it?

DouweM · 2025-11-28T21:24:29Z

.github/workflows/ci.yml

+              make lint
+              make typecheck
+              make test
+              echo "Dev container built and run successfully"


As it stands, this CI step will always succeed, even if any of the steps above failed.

For example, on this PR the output currently shows this error, even though the step shows as green:

Coverage failure: total of 99.99 is less than fail-under=100.00

Can we please fix this job to fail when any of the steps fail?

Can we get coverage to 100%? (or mark the uncovered lines as pragma: lax no cover if we can't)

The CI job can now fail, see set -o errexit. Coverage is now 100%.

…DBOS 2.0.0)

lars20070 · 2025-12-01T08:47:27Z

@DouweM Thanks for the helpful comments. They resulted in some major changes. The biggest is the switch from a bookworm to a trixie base image. This upgrade provides SQLite 3.46.1 which is required by DBOS 2.0.0.

For .env.example I would still require your help, since I do not have a valid .env myself. See comments above.

lars20070 added 30 commits November 24, 2025 09:32

devcontainer skeleton

f67e240

first rough version

d314733

fix quotes

7b69310

add devcontainer build to CI

e4ad8dc

fix linter

aed9f66

try free up disk space

364aea7

free up further space

a600a24

fix action name

c2fd567

improved comment

4f8ab24

move system lib installation to Dockerfile

1cbb322

remove redundant feature

9537063

fix linter

d6652c2

add docker-in-docker

cb873e0

simplify uv sync

d2d548e

add cache mounts

05ef5c9

fix linter

50d9067

fix Apple Silicon optimization

fef5933

copy uv into container (might run uv sync inside)

f4fbb9e

install Ollama CLI

5c3263c

improve docs

b29b5a9

improve docs

f140e33

pin versions and fail gracefully

d225123

typo

9a2453f

further simplification

f8a6a69

remove comments

e1c7b55

disable flaky test

ba4d5d6

.vscode and .cursor mount points

62dfcc2

add docu

3d84498

add pre-commit installation

216fbfa

basic docu

0f557d4

lars20070 added 6 commits November 28, 2025 10:43

remove TODO

785ebfe

add .env template

95a7df8

configure ports

1e3603b

fix working directory

a22569e

remove Ollama cli

7c0779b

remove Ollama cli

cefa997

DouweM mentioned this pull request Nov 28, 2025

Add devcontainer setup for AI coding agents #3437

Closed

5 tasks

DouweM requested changes Nov 28, 2025

View reviewed changes

DouweM self-assigned this Nov 28, 2025

DouweM added the awaiting author revision label Nov 28, 2025

DouweM changed the title ~~dev container~~ Add devcontainer Nov 28, 2025

DouweM requested changes Nov 28, 2025

View reviewed changes

lars20070 added 15 commits November 29, 2025 08:48

Python 3.12 instead of 3.11, latest versions instead of pinned versions

03bafdd

update README

b10de36

exit CI on first error

0dbfbc0

improve exit in CI

f6efcc0

remove unnecessary config

046afdc

skip DBOS test for now

dfbdf50

remove CI env var

dc62fc9

upgrade bookworm to trixie (required for SQLite 3.42.0+ required for …

fb6285b

…DBOS 2.0.0)

revert formatting in test

97bffef

fix typo

8b97df9

remove node

7d4985c

copy .env into container

446246a

update instructions

028c060

update env variables

20fde03

make install instead of uv sync

8411228

lars20070 requested a review from DouweM December 1, 2025 08:52

		@@ -0,0 +1,36 @@
		## Requirements

		Please ensure that both [Docker](https://docs.docker.com/desktop/) and optionally [Ollama](https://ollama.com/download) are installed and running on the host machine. To configure your IDE, mount your own `.vscode/` or `.cursor/` folders by uncommenting the `mounts` section in `devcontainer.json`.


		The dev container is built using a hybrid approach: the `Dockerfile` provides low-level customization, while `devcontainer.json` is used for fine-tuning and IDE integration. Minor changes to `devcontainer.json` do not require a full rebuild of the entire image, which speeds up the development workflow.

		1. The `Dockerfile` is based on Microsoft's Debian-style [Bookworm image for Python 3.11](https://hub.docker.com/r/microsoft/devcontainers-python). It uses a non-root user named `vscode` and installs system dependencies and `uv`.

Add devcontainer #3556

Are you sure you want to change the base?

Add devcontainer #3556

Uh oh!

Conversation

lars20070 commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added

Uh oh!

lars20070 commented Nov 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lars20070 commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lars20070 commented Nov 25, 2025 •

edited

Loading

lars20070 commented Dec 1, 2025 •

edited

Loading