feat: Add base image details and Python version management guide (#1114)

codegen-sh[bot] · kopekC · web-flow · commit 5eb29973c16f · 2025-05-29T23:09:43.000-04:00
## Summary This PR updates the sandbox documentation to address customer support requests about Python version compatibility, specifically for packages like `argis==2.4.0` that require Python 3.12. ## Changes Made ### Base Image Documentation - Added comprehensive "Base Image" section with complete Dockerfile - Documented the Python 3.13 default environment - Listed all available tools and package managers (uv, npm, yarn, pnpm, etc.) - Included Node.js 22.14.0 and essential development tools ### Python Version Management - Added "Working with Different Python Versions" section - Documented three approaches: 1. **pyenv** for multiple Python versions 2. **uv** package manager for version management 3. **Virtual environment best practices** ### Setup Command Examples - Added practical examples for Python version setup - Included commands for creating virtual environments with specific Python versions - Added warnings about activating virtual environments in setup commands ## Customer Impact This directly addresses the support channel question about forcing Python 3.12 for dependencies that aren't compatible with Python 3.13. Users can now: - Understand what's included in the base sandbox image - Set up Python 3.12 environments for compatibility - Use proper virtual environment practices - Configure setup commands for their specific Python version needs ## Related - Addresses customer support request from Slack thread - Follows repo rules for `.mdx` format in `docs/` directory - Updates `docs/sandboxes/setup-commands.mdx` as requested --- [💻 View my work](https://codegen.sh/agent/trace/27229) • [About Codegen](https://codegen.com) --------- Co-authored-by: codegen-sh[bot] <131295404+codegen-sh[bot]@users.noreply.github.com> Co-authored-by: KopekC <ed@codegen.com>
diff --git a/docs/docs.json b/docs/docs.json
@@ -40,6 +40,7 @@
 						"pages": [
 							"sandboxes/overview",
 							"sandboxes/setup-commands",
+							"sandboxes/base-image",
 							"sandboxes/editor",
 							"sandboxes/environment-variables",
 							"sandboxes/web-preview"
diff --git a/docs/sandboxes/base-image.mdx b/docs/sandboxes/base-image.mdx
@@ -0,0 +1,121 @@
+---
+title: "Base Image"
+sidebarTitle: "Base Image"
+icon: "docker"
+---
+
+Codegen sandboxes are built on a custom Docker image that provides a comprehensive development environment. The base image includes:
+
+- **Python 3.13** (via `ghcr.io/astral-sh/uv:python3.13-bookworm`)
+- **Node.js 22.14.0** (managed via NVM)
+- **Essential development tools**: git, curl, ripgrep, fd-find, gh (GitHub CLI)
+- **Package managers**: uv, npm, yarn, pnpm
+- **Editors**: nano, vim
+- **System utilities**: tmux, supervisor, nginx
+
+## Dockerfile
+
+```dockerfile
+ARG TARGETPLATFORM=linux/amd64
+FROM --platform=$TARGETPLATFORM ghcr.io/astral-sh/uv:python3.13-bookworm
+
+# Set environment variables to prevent interactive prompts during installation
+ENV NVM_DIR=/usr/local/nvm \
+    NODE_VERSION=22.14.0 \
+    DEBIAN_FRONTEND=noninteractive \
+    NODE_OPTIONS="--max-old-space-size=8192" \
+    PYTHONUNBUFFERED=1 \
+    COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
+    PYTHONPATH="/usr/local/lib/python3.13/site-packages" \
+    IS_SANDBOX=True
+
+ENV PATH=$NVM_DIR/versions/node/$NODE_VERSION/bin:/usr/local/nvm:/usr/local/bin:$PATH
+
+ARG INVALIDATE_FILES_LAYER=1
+# Copy configuration files and set permissions
+COPY sshd_config /etc/ssh/sshd_config
+COPY ssh_config /etc/ssh/ssh_config
+COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+COPY start.sh /usr/local/bin/start.sh
+COPY setup_ssh_user.sh /usr/local/bin/setup_ssh_user.sh
+COPY setup_ssh_keys.sh /usr/local/bin/setup_ssh_keys.sh
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY error.html /usr/share/nginx/html/error.html
+COPY tmux_output_script.sh /usr/local/bin/tmux_output_script.sh
+
+# Install dependencies and set up environment in a single layer
+RUN apt-get update && apt-get install -y -o Dpkg::Options::="--force-confold" \
+    git \
+    curl \
+    fd-find \
+    gh \
+    lsof \
+    ripgrep \
+    openssh-server \
+    nginx-full \
+    fcgiwrap \
+    tmux \
+    nano \
+    vim \
+    supervisor \
+    netcat-openbsd \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p -m 755 /etc/apt/keyrings \
+    && wget -nv -O- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+    && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+    && 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 \
+    # Set up environment variables and save it to /etc/profile.d/nvm.sh
+    && echo "export NVM_DIR=\"$NVM_DIR\"" >> /etc/profile.d/nvm.sh \
+    && echo "[ -s \"$NVM_DIR/nvm.sh\" ] && \. \"$NVM_DIR/nvm.sh\"" >> /etc/profile.d/nvm.sh \
+    && echo "export PATH=\"$NVM_DIR/versions/node/$NODE_VERSION/bin:\$PATH\"" >> /etc/profile.d/nvm.sh \
+    && echo "export NVM_BIN=\"$NVM_DIR/versions/node/$NODE_VERSION/bin\"" >> /etc/profile.d/nvm.sh \
+    && echo "export NODE_VERSION=\"$NODE_VERSION\"" >> /etc/profile.d/nvm.sh \
+    && echo "export NODE_OPTIONS=\"--max-old-space-size=8192\"" >> /etc/profile.d/nvm.sh \
+    && echo "export DEBIAN_FRONTEND=noninteractive" >> /etc/profile.d/nvm.sh \
+    && echo "export PYTHONUNBUFFERED=1" >> /etc/profile.d/nvm.sh \
+    && echo "export COREPACK_ENABLE_DOWNLOAD_PROMPT=0" >> /etc/profile.d/nvm.sh \
+    && echo "export PYTHONPATH=\"/usr/local/lib/python3.13/site-packages\"" >> /etc/profile.d/nvm.sh \
+    && echo "export IS_SANDBOX=true" >> /etc/profile.d/nvm.sh \
+    && echo "export NPM_CONFIG_YES=true" >> /etc/profile.d/nvm.sh \
+    && echo "export PIP_NO_INPUT=1" >> /etc/profile.d/nvm.sh \
+    && echo "export YARN_ENABLE_IMMUTABLE_INSTALLS=false" >> /etc/profile.d/nvm.sh \
+    && chmod +x /etc/profile.d/nvm.sh \
+    # Run the SSH setup script
+    && /usr/local/bin/setup_ssh_user.sh \
+    # Install nvm, Node.js, and code-server
+    && mkdir -p $NVM_DIR \
+    && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash \
+    && . $NVM_DIR/nvm.sh \
+    && nvm install $NODE_VERSION \
+    && nvm use $NODE_VERSION \
+    && npm install -g yarn pnpm \
+    && corepack enable \
+    && corepack prepare yarn@stable --activate \
+    && corepack prepare pnpm@latest --activate \
+    && curl -fsSL https://raw.githubusercontent.com/coder/code-server/refs/tags/v4.99.1/install.sh | sh \
+    && uv tool install uvicorn[standard]
+
+ENTRYPOINT ["/usr/local/bin/start.sh"]
+```
+
+## Key Features
+
+### Multi-Language Support
+The base image supports both Python and Node.js development out of the box, making it suitable for full-stack applications and polyglot projects.
+
+### Development Tools
+Essential development tools are pre-installed, including:
+- **Git** for version control
+- **GitHub CLI** for GitHub integration
+- **ripgrep** and **fd-find** for fast file searching
+- **tmux** for terminal multiplexing
+- **nginx** for web server capabilities
+
+### Package Managers
+Multiple package managers are available:
+- **uv** for Python package management
+- **npm**, **yarn**, and **pnpm** for Node.js packages
+- **corepack** for managing package manager versions
+
+### SSH and Remote Access
+The image includes SSH server configuration for remote access and development, with proper user setup and key management. 
diff --git a/docs/sandboxes/setup-commands.mdx b/docs/sandboxes/setup-commands.mdx
@@ -11,13 +11,17 @@ Codegen lets you configure custom setup commands that run once when initializing
   `npm install`
 </Tip>
 
+## Base Image
+
+Codegen sandboxes are built on a custom Docker image that provides a comprehensive development environment. For detailed information about the base image, including the complete Dockerfile and available tools, see the [Base Image](/sandboxes/base-image) documentation.
+
 ## Accessing Setup Commands
 
 To configure setup commands for a repository:
 
 1.  Navigate to [codegen.com/repos](https://codegen.com/repos).
 2.  Click on the desired repository from the list.
-3.  You will be taken to the repository's settings page. The setup commands can be found at a URL similar to `https://codegen.com/{your_org}/{repo_name}/settings/setup-commands` (the exact URL structure might vary slightly, look for a "Setup Commands" or "Sandbox Configuration" section).
+3.  You will be taken to the repository's settings page. The setup commands can be found at a URL similar to `https://www.codegen.com/repos/{arepo_name}/setup-commands` 
 
 <Frame caption="Set setup commands at codegen.com/repos">
   <img src="/images/setup-commands-ui.png" alt="Setup Commands UI" />
@@ -48,7 +52,11 @@ npm install
 ```
 
 ```bash
-# Install Python dependencies
+# Setup with specific Python version for compatibility
+pyenv install 3.12.0
+pyenv local 3.12.0
+python -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
 ```
 
@@ -59,6 +67,75 @@ npm ci
 npm run build
 ```
 
+### Working with Different Python Versions
+
+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:
+
+#### Using pyenv for Multiple Python Versions
+
+If you need to work with a different Python version, you can install and use `pyenv`:
+
+```bash
+# Install pyenv
+curl https://pyenv.run | bash
+
+# Add pyenv to PATH (for current session)
+export PATH="$HOME/.pyenv/bin:$PATH"
+eval "$(pyenv init -)"
+eval "$(pyenv virtualenv-init -)"
+
+# Install Python 3.12 (or your desired version)
+pyenv install 3.12.0
+
+# Set Python 3.12 as the local version for your project
+pyenv local 3.12.0
+
+# Create a virtual environment with Python 3.12
+python -m venv venv
+source venv/bin/activate
+
+# Install your dependencies
+pip install -r requirements.txt
+```
+
+#### Using uv with Specific Python Versions
+
+The `uv` package manager (already installed) can also manage Python versions:
+
+```bash
+# Install Python 3.12 and create a virtual environment
+uv venv --python=3.12
+
+# Activate the virtual environment
+source .venv/bin/activate
+
+# Install dependencies
+uv pip install -r requirements.txt --refresh --upgrade
+```
+
+#### Virtual Environment Best Practices
+
+When working with packages that require older Python versions:
+
+```bash
+# Create a virtual environment with a specific Python version
+python3.12 -m venv venv_312
+source venv_312/bin/activate
+
+# Verify the Python version
+python --version
+
+# Install packages that require Python 3.12
+pip install argis==2.4.0  # Example package that needs older Python
+
+# Deactivate when done
+deactivate
+```
+
+<Warning>
+  Remember to activate your virtual environment in your setup commands if you need specific Python versions for your project dependencies.
+</Warning>
+
 <Note>
   Ensure your setup commands are non-interactive and can run to completion
   without user input.
@@ -67,3 +144,4 @@ npm run build
   The environment variables listed in the "Env Variables" section are available
   during the execution of these setup commands.
 </Tip>
+
