Skip to content

Commit d1ed0e9

Browse files
davidpirogovdavidpirogov
authored
Introduce devcontainer to repository (#23)
* feat: add development container configuration and README * chore: update .gitignore to include .python-version so that people can use it with local development choices
1 parent 6cf4d7f commit d1ed0e9

File tree

6 files changed

+214
-1
lines changed

6 files changed

+214
-1
lines changed

‎.devcontainer/Dockerfile.dev‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
ARG UV_VERSION=0.8.13
2+
3+
FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
4+
5+
FROM mcr.microsoft.com/devcontainers/base:bookworm
6+
7+
COPY --from=uv /uv /uvx /bin/
8+
9+
# Python environment variables for development
10+
ENV PYTHONUNBUFFERED=1 \
11+
PYTHONDONTWRITEBYTECODE=1 \
12+
PYTHONIOENCODING=utf-8 \
13+
PIP_NO_CACHE_DIR=1 \
14+
PIP_DISABLE_PIP_VERSION_CHECK=1 \
15+
UV_NO_CACHE=1 \
16+
UV_PROJECT_ENVIRONMENT=/app/.venv \
17+
LANG=C.UTF-8 \
18+
LC_ALL=C.UTF-8
19+
20+
USER vscode
21+
22+
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
23+
24+
WORKDIR /app
25+
26+
HEALTHCHECK --interval=60s --timeout=5s --start-period=60s --retries=3 \
27+
CMD test -d /app && whoami || exit 1

‎.devcontainer/README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Development Container
2+
3+
This project uses a [Development Container](https://containers.dev/) to provide a consistent development environment.
4+
5+
## Getting Started
6+
7+
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
8+
2. Install [VS Code](https://code.visualstudio.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
9+
3. Open this folder in VS Code
10+
4. When prompted, click "Reopen in Container" (or run command: `Dev Containers: Reopen in Container`)
11+
12+
## Local Customization
13+
14+
To customize your local development environment without modifying the committed configuration, create a `.devcontainer/devcontainer.local.json` file (this file is gitignored).
15+
16+
### Example: Add Additional VS Code Extensions
17+
18+
```json
19+
{
20+
"customizations": {
21+
"vscode": {
22+
"extensions": [
23+
"esbenp.prettier-vscode",
24+
"usernamehw.errorlens"
25+
]
26+
}
27+
}
28+
}
29+
```
30+
31+
### Example: Mount Additional Volumes
32+
33+
```json
34+
{
35+
"mounts": [
36+
"source=${localEnv:HOME}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,consistency=cached"
37+
]
38+
}
39+
```
40+
41+
### Example: Override or Add Environment Variables
42+
43+
The container sets several Python-related environment variables by default (see `Dockerfile.dev`). You can override them or add new ones using `remoteEnv`:
44+
45+
```json
46+
{
47+
"remoteEnv": {
48+
"PYTHONUNBUFFERED": "0",
49+
"DEBUG": "1",
50+
"LOG_LEVEL": "DEBUG"
51+
}
52+
}
53+
```
54+
55+
See `devcontainer.local.json.example` for a complete list of default environment variables that can be overridden.
56+
57+
Alternatively, create a `.devcontainer/.env` file (also gitignored):
58+
```bash
59+
DEBUG=1
60+
LOG_LEVEL=DEBUG
61+
```
62+
63+
And reference it in `devcontainer.local.json`:
64+
```json
65+
{
66+
"runArgs": ["--env-file", ".devcontainer/.env"]
67+
}
68+
```
69+
70+
### Example: Forward Additional Ports
71+
72+
```json
73+
{
74+
"forwardPorts": [8080, 3000]
75+
}
76+
```
77+
78+
## How It Works
79+
80+
The Dev Container will:
81+
- Build from `Dockerfile.dev`
82+
- Mount your workspace to `/app`
83+
- Install Git and GitHub CLI features
84+
- Run `uv sync --all-groups` to create a virtual environment at `/app/.venv`
85+
- Configure VS Code to use the virtual environment's Python interpreter
86+
- Set up bash as the default terminal
87+
88+
### Default Environment Variables
89+
90+
The following Python-related environment variables are set in the container:
91+
92+
- **`PYTHONUNBUFFERED=1`** - Ensures real-time output in logs
93+
- **`PYTHONDONTWRITEBYTECODE=1`** - Prevents `.pyc` file creation
94+
- **`PYTHONIOENCODING=utf-8`** - Ensures UTF-8 encoding for I/O
95+
- **`PIP_NO_CACHE_DIR=1`** - Disables pip caching to reduce container size
96+
- **`PIP_DISABLE_PIP_VERSION_CHECK=1`** - Suppresses pip update warnings
97+
- **`UV_NO_CACHE=1`** - Disables uv caching
98+
- **`UV_PROJECT_ENVIRONMENT=/app/.venv`** - Sets the virtual environment location for uv
99+
- **`LANG=C.UTF-8`** - Sets locale for proper Unicode handling
100+
- **`LC_ALL=C.UTF-8`** - Sets all locale categories to UTF-8
101+
102+
These can be overridden in `devcontainer.local.json` using the `remoteEnv` property.
103+
104+
### Virtual Environment
105+
106+
The project uses `uv` to manage dependencies. When the container is created:
107+
1. `uv sync --all-groups` is automatically run to create a virtual environment at `/app/.venv`
108+
2. VS Code is configured to use `/app/.venv/bin/python` as the Python interpreter
109+
3. All dependencies from `pyproject.toml` (including dev groups) are installed
110+
111+
To manually update dependencies, run:
112+
```bash
113+
uv sync --all-groups
114+
```
115+
116+
## Rebuilding the Container
117+
118+
If you modify the Dockerfile or devcontainer configuration:
119+
1. Run command: `Dev Containers: Rebuild Container`
120+
2. Or run: `Dev Containers: Rebuild Container Without Cache` for a clean build

‎.devcontainer/devcontainer.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
// To customize this for your local environment without committing changes,
3+
// create a .devcontainer/devcontainer.local.json file (it's gitignored).
4+
// See .devcontainer/README.md for examples.
5+
"name": "toon-python (devcontainer)",
6+
"build": {
7+
"dockerfile": "Dockerfile.dev",
8+
"context": ".."
9+
},
10+
"workspaceFolder": "/app",
11+
"mounts": [
12+
"source=${localWorkspaceFolder},target=/app,type=bind,consistency=cached"
13+
],
14+
"features": {
15+
"ghcr.io/devcontainers/features/git:1": {},
16+
"ghcr.io/devcontainers/features/github-cli:1": {}
17+
},
18+
"remoteEnv": {
19+
// Python environment variables (can be overridden in devcontainer.local.json)
20+
// These supplement the ENV vars set in Dockerfile.dev
21+
},
22+
"postCreateCommand": "uv sync --all-groups",
23+
"customizations": {
24+
"vscode": {
25+
"settings": {
26+
"python.defaultInterpreterPath": "/app/.venv/bin/python"
27+
}
28+
}
29+
}
30+
}

‎.devcontainer/devcontainer.local.json.example‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
// Example local devcontainer configuration
3+
// Copy this to devcontainer.local.json and customize as needed
4+
// This file is gitignored and won't be committed
5+
6+
"remoteEnv": {
7+
// Override Python environment variables
8+
// Uncomment and modify any of these to override defaults from Dockerfile.dev:
9+
10+
// "PYTHONUNBUFFERED": "0",
11+
// "PYTHONDONTWRITEBYTECODE": "0",
12+
// "PYTHONIOENCODING": "utf-8",
13+
// "PIP_NO_CACHE_DIR": "0",
14+
// "PIP_DISABLE_PIP_VERSION_CHECK": "0",
15+
// "UV_NO_CACHE": "0",
16+
// "UV_PROJECT_ENVIRONMENT": "/custom/path/.venv",
17+
// "LANG": "en_US.UTF-8",
18+
// "LC_ALL": "en_US.UTF-8",
19+
20+
// Add custom environment variables for local development:
21+
// "DEBUG": "1",
22+
// "LOG_LEVEL": "DEBUG"
23+
},
24+
25+
// You can also override other devcontainer settings:
26+
// "features": {},
27+
// "customizations": {
28+
// "vscode": {
29+
// "extensions": []
30+
// }
31+
// }
32+
}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ venv/
6464
ENV/
6565
env.bak/
6666
venv.bak/
67+
.python-version
6768

6869
# IDEs
6970
.vscode/
@@ -74,6 +75,10 @@ venv.bak/
7475
.claude/
7576
CLAUDE.md
7677

78+
# DevContainer local overrides
79+
.devcontainer/devcontainer.local.json
80+
.devcontainer/.env
81+
7782
# macOS
7883
.DS_Store
7984
.AppleDouble

‎.python-version‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)