diff --git a/docs/docs.json b/docs/docs.json index d3ddc3338..90ad6e504 100644 --- 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 new file mode 100644 index 000000000..03472149d --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/sandboxes/setup-commands.mdx b/docs/sandboxes/setup-commands.mdx index 2c4ea8c23..bd0ede1f0 100644 --- 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` +## 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` 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 +``` + + + Remember to activate your virtual environment in your setup commands if you need specific Python versions for your project dependencies. + + 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. +