Skip to content

Commit b92f214

Browse files
docs: Add base image details and Python version management guide
- Added comprehensive base image section with complete Dockerfile - Documented Python 3.13 default and available tools - Added guides for using pyenv and uv for different Python versions - Included virtual environment best practices for compatibility - Added setup command examples for Python version management Addresses customer support request for Python 3.12 compatibility with packages like argis==2.4.0
1 parent 7bd1f04 commit b92f214

File tree

1 file changed

+176
-1
lines changed

1 file changed

+176
-1
lines changed

docs/sandboxes/setup-commands.mdx

Lines changed: 176 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,176 @@ Codegen lets you configure custom setup commands that run once when initializing
1111
`npm install`
1212
</Tip>
1313

14+
## Base Image
15+
16+
Codegen sandboxes are built on a custom Docker image that provides a comprehensive development environment. The base image includes:
17+
18+
- **Python 3.13** (via `ghcr.io/astral-sh/uv:python3.13-bookworm`)
19+
- **Node.js 22.14.0** (managed via NVM)
20+
- **Essential development tools**: git, curl, ripgrep, fd-find, gh (GitHub CLI)
21+
- **Package managers**: uv, npm, yarn, pnpm
22+
- **Editors**: nano, vim
23+
- **System utilities**: tmux, supervisor, nginx
24+
25+
<details>
26+
<summary>View the complete Dockerfile</summary>
27+
28+
```dockerfile
29+
ARG TARGETPLATFORM=linux/amd64
30+
31+
FROM --platform=$TARGETPLATFORM ghcr.io/astral-sh/uv:python3.13-bookworm
32+
33+
# Set environment variables to prevent interactive prompts during installation
34+
ENV NVM_DIR=/usr/local/nvm \
35+
NODE_VERSION=22.14.0 \
36+
DEBIAN_FRONTEND=noninteractive \
37+
NODE_OPTIONS="--max-old-space-size=8192" \
38+
PYTHONUNBUFFERED=1 \
39+
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
40+
PYTHONPATH="/usr/local/lib/python3.13/site-packages" \
41+
IS_SANDBOX=True
42+
43+
ENV PATH=$NVM_DIR/versions/node/$NODE_VERSION/bin:/usr/local/nvm:/usr/local/bin:$PATH
44+
45+
ARG INVALIDATE_FILES_LAYER=1
46+
# Copy configuration files and set permissions
47+
COPY sshd_config /etc/ssh/sshd_config
48+
COPY ssh_config /etc/ssh/ssh_config
49+
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
50+
COPY start.sh /usr/local/bin/start.sh
51+
COPY setup_ssh_user.sh /usr/local/bin/setup_ssh_user.sh
52+
COPY setup_ssh_keys.sh /usr/local/bin/setup_ssh_keys.sh
53+
COPY nginx.conf /etc/nginx/nginx.conf
54+
COPY error.html /usr/share/nginx/html/error.html
55+
COPY tmux_output_script.sh /usr/local/bin/tmux_output_script.sh
56+
57+
# Install dependencies and set up environment in a single layer
58+
RUN apt-get update && apt-get install -y -o Dpkg::Options::="--force-confold" \
59+
git \
60+
curl \
61+
fd-find \
62+
gh \
63+
lsof \
64+
ripgrep \
65+
openssh-server \
66+
nginx-full \
67+
fcgiwrap \
68+
tmux \
69+
nano \
70+
vim \
71+
supervisor \
72+
netcat-openbsd \
73+
&& rm -rf /var/lib/apt/lists/* \
74+
&& mkdir -p -m 755 /etc/apt/keyrings \
75+
&& wget -nv -O- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
76+
&& chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
77+
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
78+
# Set up environment variables and save it to /etc/profile.d/nvm.sh
79+
&& echo "export NVM_DIR=\"$NVM_DIR\"" >> /etc/profile.d/nvm.sh \
80+
&& echo "[ -s \"$NVM_DIR/nvm.sh\" ] && \. \"$NVM_DIR/nvm.sh\"" >> /etc/profile.d/nvm.sh \
81+
&& echo "export PATH=\"$NVM_DIR/versions/node/$NODE_VERSION/bin:\$PATH\"" >> /etc/profile.d/nvm.sh \
82+
&& echo "export NVM_BIN=\"$NVM_DIR/versions/node/$NODE_VERSION/bin\"" >> /etc/profile.d/nvm.sh \
83+
&& echo "export NODE_VERSION=\"$NODE_VERSION\"" >> /etc/profile.d/nvm.sh \
84+
&& echo "export NODE_OPTIONS=\"--max-old-space-size=8192\"" >> /etc/profile.d/nvm.sh \
85+
&& echo "export DEBIAN_FRONTEND=noninteractive" >> /etc/profile.d/nvm.sh \
86+
&& echo "export PYTHONUNBUFFERED=1" >> /etc/profile.d/nvm.sh \
87+
&& echo "export COREPACK_ENABLE_DOWNLOAD_PROMPT=0" >> /etc/profile.d/nvm.sh \
88+
&& echo "export PYTHONPATH=\"/usr/local/lib/python3.13/site-packages\"" >> /etc/profile.d/nvm.sh \
89+
&& echo "export IS_SANDBOX=true" >> /etc/profile.d/nvm.sh \
90+
&& echo "export NPM_CONFIG_YES=true" >> /etc/profile.d/nvm.sh \
91+
&& echo "export PIP_NO_INPUT=1" >> /etc/profile.d/nvm.sh \
92+
&& echo "export YARN_ENABLE_IMMUTABLE_INSTALLS=false" >> /etc/profile.d/nvm.sh \
93+
&& chmod +x /etc/profile.d/nvm.sh \
94+
# Run the SSH setup script
95+
&& /usr/local/bin/setup_ssh_user.sh \
96+
# Install nvm, Node.js, and code-server
97+
&& mkdir -p $NVM_DIR \
98+
&& curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash \
99+
&& . $NVM_DIR/nvm.sh \
100+
&& nvm install $NODE_VERSION \
101+
&& nvm use $NODE_VERSION \
102+
&& npm install -g yarn pnpm \
103+
&& corepack enable \
104+
&& corepack prepare yarn@stable --activate \
105+
&& corepack prepare pnpm@latest --activate \
106+
&& curl -fsSL https://raw.githubusercontent.com/coder/code-server/refs/tags/v4.99.1/install.sh | sh \
107+
&& uv tool install uvicorn[standard]
108+
109+
ENTRYPOINT ["/usr/local/bin/start.sh"]
110+
```
111+
112+
</details>
113+
114+
## Working with Different Python Versions
115+
116+
The sandbox comes with Python 3.13 by default, but some packages may not yet be compatible with this version. Here are strategies for handling different Python versions:
117+
118+
### Using pyenv for Multiple Python Versions
119+
120+
If you need to work with a different Python version, you can install and use `pyenv`:
121+
122+
```bash
123+
# Install pyenv
124+
curl https://pyenv.run | bash
125+
126+
# Add pyenv to PATH (for current session)
127+
export PATH="$HOME/.pyenv/bin:$PATH"
128+
eval "$(pyenv init -)"
129+
eval "$(pyenv virtualenv-init -)"
130+
131+
# Install Python 3.12 (or your desired version)
132+
pyenv install 3.12.0
133+
134+
# Set Python 3.12 as the local version for your project
135+
pyenv local 3.12.0
136+
137+
# Create a virtual environment with Python 3.12
138+
python -m venv venv
139+
source venv/bin/activate
140+
141+
# Install your dependencies
142+
pip install -r requirements.txt
143+
```
144+
145+
### Using uv with Specific Python Versions
146+
147+
The `uv` package manager (already installed) can also manage Python versions:
148+
149+
```bash
150+
# Install a specific Python version with uv
151+
uv python install 3.12
152+
153+
# Create a project with a specific Python version
154+
uv init --python 3.12 my_project
155+
cd my_project
156+
157+
# Install dependencies with the specified Python version
158+
uv add your-package-name
159+
```
160+
161+
### Virtual Environment Best Practices
162+
163+
When working with packages that require older Python versions:
164+
165+
```bash
166+
# Create a virtual environment with a specific Python version
167+
python3.12 -m venv venv_312
168+
source venv_312/bin/activate
169+
170+
# Verify the Python version
171+
python --version
172+
173+
# Install packages that require Python 3.12
174+
pip install argis==2.4.0 # Example package that needs older Python
175+
176+
# Deactivate when done
177+
deactivate
178+
```
179+
180+
<Warning>
181+
Remember to activate your virtual environment in your setup commands if you need specific Python versions for your project dependencies.
182+
</Warning>
183+
14184
## Accessing Setup Commands
15185

16186
To configure setup commands for a repository:
@@ -48,7 +218,11 @@ npm install
48218
```
49219

50220
```bash
51-
# Install Python dependencies
221+
# Setup with specific Python version for compatibility
222+
pyenv install 3.12.0
223+
pyenv local 3.12.0
224+
python -m venv venv
225+
source venv/bin/activate
52226
pip install -r requirements.txt
53227
```
54228

@@ -67,3 +241,4 @@ npm run build
67241
The environment variables listed in the "Env Variables" section are available
68242
during the execution of these setup commands.
69243
</Tip>
244+

0 commit comments

Comments
 (0)