From 0ea88c017e56c227699d2fd406a7a7ced71a5ecb Mon Sep 17 00:00:00 2001 From: Eric Lavigne Date: Thu, 9 Oct 2025 12:27:05 -0600 Subject: [PATCH] SERVER-111809: Add more detailed documentation for dev containers (#42380) GitOrigin-RevId: 7735060dbb806d0a7dbf51fb32bfc3fd2c7248d1 --- .devcontainer/Dockerfile | 3 + .devcontainer/devcontainer.json | 2 +- .github/CODEOWNERS | 1 + docs/OWNERS.yml | 3 + docs/devcontainer-setup.md | 92 +-- docs/devcontainer/README.md | 114 +++ docs/devcontainer/advanced.md | 336 ++++++++ docs/devcontainer/architecture.md | 563 +++++++++++++ docs/devcontainer/faq.md | 502 ++++++++++++ docs/devcontainer/getting-started.md | 469 +++++++++++ docs/devcontainer/troubleshooting.md | 1104 ++++++++++++++++++++++++++ 11 files changed, 3104 insertions(+), 85 deletions(-) create mode 100644 docs/devcontainer/README.md create mode 100644 docs/devcontainer/advanced.md create mode 100644 docs/devcontainer/architecture.md create mode 100644 docs/devcontainer/faq.md create mode 100644 docs/devcontainer/getting-started.md create mode 100644 docs/devcontainer/troubleshooting.md diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 419b7ba8896..3e07adbcc09 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -56,6 +56,9 @@ USER $USERNAME ENV USER=${USERNAME} RUN /opt/mongodbtoolchain/revisions/*/scripts/install.sh; echo "Toolchain installation complete" +# Add MongoDB toolchain to PATH +ENV PATH="/opt/mongodbtoolchain/v5/bin:${PATH}" + # Bazel telemetry RUN echo "common --bes_keywords=devcontainer:use=true" >> "$HOME/.bazelrc" && \ echo "common --bes_keywords=devcontainer:image=$BASE_IMAGE" >> "$HOME/.bazelrc" && \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 969fe7c52d5..a06dcc83dd9 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -19,7 +19,7 @@ "type": "volume" }, { - "source": "projectname-bashhistory", + "source": "mongo-bashhistory", "target": "/commandhistory", "type": "volume" } diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 2ffe2130724..58d5d1edf6e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -305,6 +305,7 @@ WORKSPACE.bazel @10gen/devprod-build @svc-auto-approve-bot /docs/**/change_streams.md @10gen/query-execution-change-streams @svc-auto-approve-bot /docs/**/cpp_style.md @10gen/server-programmability @svc-auto-approve-bot /docs/**/devcontainer-setup.md @10gen/devprod-correctness @svc-auto-approve-bot +/docs/devcontainer/** @10gen/devprod-correctness @svc-auto-approve-bot /docs/**/exception_architecture.md @10gen/server-programmability @svc-auto-approve-bot /docs/**/golden_data_test_framework.md @10gen/query-optimization @svc-auto-approve-bot /docs/**/idl.md @10gen/server-programmability @svc-auto-approve-bot diff --git a/docs/OWNERS.yml b/docs/OWNERS.yml index 4562b265988..ebdce4d10f0 100644 --- a/docs/OWNERS.yml +++ b/docs/OWNERS.yml @@ -12,6 +12,9 @@ filters: - "devcontainer-setup.md": approvers: - 10gen/devprod-correctness + - "devcontainer/**": + approvers: + - 10gen/devprod-correctness - "exception_architecture.md": approvers: - 10gen/server-programmability diff --git a/docs/devcontainer-setup.md b/docs/devcontainer-setup.md index d324d38cd3a..685f36bc574 100644 --- a/docs/devcontainer-setup.md +++ b/docs/devcontainer-setup.md @@ -1,87 +1,11 @@ -# MongoDB Development with Devcontainers +# MongoDB Development with Dev Containers -**IMPORTANT** The devcontainer setup is currently in the Beta stage +**⚠️ IMPORTANT:** This guide has been replaced with comprehensive documentation. -This guide walks you through setting up a MongoDB development environment using devcontainers as the underlying container orchestration tool. +**👉 Please visit the new [Dev Container Documentation](./devcontainer/README.md) for:** -## Prerequisites - -### Install Docker - -Devcontainers requires Docker to be installed and running on your system, some examples of docker providers are: - -- [Rancher Desktop](https://rancherdesktop.io/) (Recommended) -- [Docker Desktop](https://www.docker.com/products/docker-desktop/) -- [Orbstack](https://orbstack.dev/) -- [Docker Engine](https://docs.docker.com/engine/install/) (Linux only) - -#### Rancher Desktop - -If you choose to use Rancher Desktop, you will be prompted to fill in some settings when you first launch the application. You can use the following settings: - -- Kubernetes: Choose whatever you like, this isn't required for devcontainers -- Container Engine: `dockerd (moby)` -- Configure Path: "Automatic" - -Afterwards, it is recommended to increase the amount of CPU and Memory available to the container engine. You can do this by going to Preferences > Virtual Machine. - -## Setup Instructions - -### 1. Install the Remote Containers VSCode Extension - -Install the [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension from the VSCode marketplace. - -### 2. Clone the MongoDB Repository in a Named Container Volume - -For best performance and compatibility (especially with Bazel on macOS), **do not clone the repository to your local filesystem first**. Instead, open VSCode and use the VSCode command palette: - -1. Open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac). -2. Run **"Dev Containers: Clone Repository in Named Container Volume..."** -3. Enter the repository URL (it is recommended you use the ssh url) -4. Use whatever name you like for the named volume, this name will be presented in the docker volume list if you need to reference it later. -5. VS Code will automatically set up the devcontainer in an isolated volume, improving performance and resolving compatibility issues with Bazel on macOS filesystems over using a bind-mounted workspace. - -If you have already cloned the repository locally, you can still use the command above for a better experience. - -### 3. Fetch Complete Git History (Recommended) - -After the container opens for the first time, it's recommended to run the following command in the terminal to fetch the complete git history since the above clone workflow may only do a shallow clone: - -```bash -git fetch --unshallow --all -``` - -This ensures you have access to the full repository history and all branches, which may be needed for certain development workflows (e.g., `bazel build install-dist`). - -### 4. Access Your Development Environment - -Once setup is complete, VS Code will automatically open with your containerized development environment. You'll have access to: - -- **MongoDB source code** mounted in the container -- **Persistent volumes** for caches and configurations -- **Pre-configured VS Code settings** for MongoDB development -- **All development tools** ready to use - -## Container Features - -### Persistent Storage - -The devcontainer uses several persistent volumes to maintain state across container restarts: - -- **engflow_auth**: Authentication credentials for EngFlow remote execution -- **python3-venv**: Python virtual environment and dependencies -- **cache**: Build caches and other temporary files - -### VS Code Integration - -The container includes pre-configured VS Code settings for: - -- **C/C++ development** with clangd and clang-format -- **Python development** with ruff and mypy -- **JavaScript development** with ESLint and Prettier -- **Bazel integration** for build system support -- **MongoDB-specific** file associations and schemas - -## Additional Resources - -- [VS Code Devcontainer Documentation](https://code.visualstudio.com/docs/devcontainers/containers) +- 📖 [**Getting Started Guide**](./devcontainer/getting-started.md) - Step-by-step setup instructions +- 🏗️ [**Architecture & Technical Details**](./devcontainer/architecture.md) - How everything works under the hood +- 🔧 [**Troubleshooting Guide**](./devcontainer/troubleshooting.md) - Solutions to common issues +- 💡 [**Advanced Usage**](./devcontainer/advanced.md) - Customization and power user features +- ❓ [**FAQ**](./devcontainer/faq.md) - Frequently asked questions diff --git a/docs/devcontainer/README.md b/docs/devcontainer/README.md new file mode 100644 index 00000000000..e9c49f317ea --- /dev/null +++ b/docs/devcontainer/README.md @@ -0,0 +1,114 @@ +# MongoDB Development with Dev Containers + +**⚠️ BETA:** The devcontainer setup is currently in Beta stage. Please report issues and feedback to the team. + +## 📚 Documentation Index + +This is the comprehensive guide for developing MongoDB using Dev Containers. Choose the guide that best fits your needs: + +### 🚀 [Getting Started](./getting-started.md) + +**Start here if you're new to devcontainers or MongoDB development** + +- Prerequisites and system requirements +- Step-by-step setup instructions +- First-time configuration +- Verifying your setup + +### 🏗️ [Architecture & Technical Details](./architecture.md) + +**Understand how the devcontainer works under the hood** + +- Container architecture overview +- Dockerfile breakdown +- Volume management and persistence +- Toolchain installation process +- VS Code integration details +- Feature system explained + +### 🔧 [Troubleshooting](./troubleshooting.md) + +**Having issues? Check here for solutions** + +- Common problems and fixes +- Performance optimization +- Platform-specific issues (macOS, Windows, Linux) +- Docker provider comparison +- Debugging tips + +### 💡 [Advanced Usage](./advanced.md) + +**Power user features and customization** + +- Customizing your devcontainer +- Working with multiple containers +- Remote execution with EngFlow +- Custom toolchain versions +- Integration with CI/CD +- Extending with additional features + +### ❓ [FAQ](./faq.md) + +**Quick answers to common questions** + +- Why use devcontainers? +- Named volumes vs bind mounts +- Updating the container +- Data persistence +- And more... + +## Quick Links + +### VS Code Documentation + +- [Dev Containers Overview](https://code.visualstudio.com/docs/devcontainers/containers) +- [devcontainer.json Reference](https://code.visualstudio.com/docs/devcontainers/containers#_devcontainerjson-reference) +- [Create a Dev Container](https://code.visualstudio.com/docs/devcontainers/create-dev-container) +- [Advanced Container Configuration](https://code.visualstudio.com/docs/devcontainers/containers#_advanced-container-configuration) +- [Dev Containers FAQ](https://code.visualstudio.com/docs/devcontainers/faq) +- [Dev Containers Tips and Tricks](https://code.visualstudio.com/docs/devcontainers/tips-and-tricks) + +### MongoDB Documentation + +- [MongoDB Build Documentation](../../building.md) +- [MongoDB Contributing Guide](../../CONTRIBUTING.rst) + +## What are Dev Containers? + +Dev Containers provide a consistent, reproducible development environment using Docker containers. This ensures: + +- ✅ **Consistency**: Everyone works with identical tooling and dependencies +- ✅ **Isolation**: Your host system stays clean +- ✅ **Portability**: Develop from any machine with Docker +- ✅ **Quick Setup**: Get started in minutes, not hours + +## Benefits for MongoDB Development + +The MongoDB devcontainer provides: + +1. **Pre-configured Build Environment**: All build tools, compilers, and dependencies ready to use +2. **MongoDB Toolchain**: Specific GCC/Clang versions required for building MongoDB +3. **IDE Integration**: VS Code settings optimized for C++, Python, JavaScript, and Bazel +4. **Persistent Caching**: Build artifacts and Python environments preserved across sessions +5. **EngFlow Support**: Built-in support for remote execution and caching + +## System Requirements + +- **Docker**: Allocate as much RAM as possible to Docker (leave ~4-8 GB for host OS) +- **CPU**: Allocate as many cores as possible to Docker (leave 1-2 for host OS) +- **Disk Space**: 60+ GB recommended for container, tools, and build artifacts +- **VS Code**: Latest version with Remote - Containers extension +- **Operating System**: + - macOS (ARM64 or x86_64) + - Windows 10/11 with WSL2 + - Linux (x86_64 or ARM64) + +## Getting Help + +- **Documentation Issues**: Open an issue or PR in the MongoDB repository +- **Devcontainer Problems**: Check [Troubleshooting Guide](./troubleshooting.md) +- **General Questions**: See [FAQ](./faq.md) + +--- + +**Ready to get started?** → [Follow the Getting Started Guide](./getting-started.md) diff --git a/docs/devcontainer/advanced.md b/docs/devcontainer/advanced.md new file mode 100644 index 00000000000..23c18030c8d --- /dev/null +++ b/docs/devcontainer/advanced.md @@ -0,0 +1,336 @@ +# Advanced Dev Container Usage + +This guide covers advanced topics for power users who want to customize and extend their devcontainer setup. + +## Table of Contents + +- [Customizing the Container](#customizing-the-container) +- [Working with Multiple Containers](#working-with-multiple-containers) +- [Adding Custom Features](#adding-custom-features) +- [VS Code Customization](#vs-code-customization) +- [Performance Tuning](#performance-tuning) +- [Backup and Migration](#backup-and-migration) +- [Development Workflows](#development-workflows) + +## Customizing the Container + +### Persistent Dotfiles + +[Learn more about personalizing with dotfiles →](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) + +### Always Installed Features + +[Learn more about adding a set of personalized features](https://code.visualstudio.com/docs/devcontainers/containers#_always-installed-features) + +## Working with Multiple Containers + +### Running Multiple Instances + +You can run multiple devcontainers for different branches: + +```bash +# Clone same repo with different volume names +Dev Containers: Clone Repository in Named Container Volume... +# Volume 1: mongo-main +# Volume 2: mongo-feature-branch +# Volume 3: mongo-bugfix +``` + +Each gets its own: + +- Container instance +- Cache volume +- Python venv + +**Switch between them:** + +- VS Code → File → Recent +- Select the container you want + +### EngFlow Telemetry + +The devcontainer automatically reports metadata to EngFlow via Bazel keywords: + +```bash +# These are added automatically in Dockerfile and postCreateCommand +common --bes_keywords=devcontainer:use=true +common --bes_keywords=devcontainer:image= +common --bes_keywords=devcontainer:docker_server_platform= +``` + +This helps the team understand devcontainer adoption and troubleshoot issues. + +## Adding Custom Features + +### Creating a Custom Feature + +Features are modular additions to your devcontainer. Create one: + +```bash +mkdir -p .devcontainer/features/my-feature +cd .devcontainer/features/my-feature +``` + +**Create `devcontainer-feature.json`:** + +```json +{ + "id": "my-feature", + "version": "1.0.0", + "name": "My Custom Feature", + "description": "Adds my custom tools and configuration", + "options": { + "version": { + "type": "string", + "default": "latest", + "description": "Version to install" + } + } +} +``` + +**Create `install.sh`:** + +```bash +#!/usr/bin/env bash +set -e + +VERSION="${VERSION:-latest}" + +echo "Installing my-feature version $VERSION..." + +# Your installation logic here +apt-get update +apt-get install -y my-package + +echo "my-feature installation complete!" +``` + +**Note**: Custom features are typically contributed to the main devcontainer configuration through pull requests rather than added individually. + +### Example: MongoDB Compass Feature + +```bash +# .devcontainer/features/compass/install.sh +#!/usr/bin/env bash +set -e + +echo "Installing MongoDB Compass..." + +wget https://downloads.mongodb.com/compass/mongodb-compass_latest_amd64.deb +sudo dpkg -i mongodb-compass_latest_amd64.deb || true +sudo apt-get install -f -y +rm mongodb-compass_latest_amd64.deb + +echo "Compass installed!" +``` + +### Example: Database Tools Feature + +```bash +# .devcontainer/features/db-tools/install.sh +#!/usr/bin/env bash +set -e + +echo "Installing MongoDB Database Tools..." + +wget https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2204-x86_64-100.9.4.deb +sudo dpkg -i mongodb-database-tools-*.deb +rm mongodb-database-tools-*.deb + +echo "Database tools installed: mongodump, mongorestore, etc." +``` + +## VS Code Customization + +### User-Specific Settings + +Override devcontainer settings in user `settings.json`. + +[Learn more about container-specific settings →](https://code.visualstudio.com/docs/devcontainers/containers#_container-specific-settings) + +```json +{ + // Your personal preferences + "editor.fontSize": 14, + "editor.tabSize": 2, + "terminal.integrated.fontSize": 13, + + // Override theme + "workbench.colorTheme": "Monokai", + + // Additional formatters + "editor.defaultFormatter": "esbenp.prettier-vscode" +} +``` + +### Additional Extensions + +Install extra extensions without modifying `devcontainer.json`: + +```bash +# Via command line +code --install-extension ms-vscode.hexeditor + +# Or manually in Extensions panel +``` + +### Port Forwarding + +VS Code automatically forwards ports from the container to your host machine. When a service listens on a port inside the container, VS Code detects it and makes it accessible from your browser. + +```bash +# Start mongod on default port 27017 +./bazel-bin/src/mongo/mongod --dbpath /data/db + +# VS Code will automatically forward port 27017 +# Access from host: localhost:27017 +``` + +**Manual port forwarding:** + +- Click on the Ports tab in VS Code terminal panel +- Add port → Enter port number +- Access forwarded ports from your host browser or tools +- **Note**: Some firewall configurations may block forwarded ports + +[Learn more about port forwarding →](https://code.visualstudio.com/docs/devcontainers/containers#_forwarding-or-publishing-a-port) + +## Performance Tuning + +### Docker Performance + +**macOS:** + +- Use VirtioFS instead of osxfs (Docker Desktop 4.6+) +- Settings → Experimental → VirtioFS + +**All platforms:** + +- Allocate as many resources as possible to Docker (see [Getting Started](./getting-started.md)) +- Use named volumes (not bind mounts) +- Enable BuildKit (for faster image builds): + ```bash + export DOCKER_BUILDKIT=1 + ``` + +### File Watching + +Reduce file watcher overhead: + +```json +// Add to VS Code settings.json +{ + "files.watcherExclude": { + "**/bazel-*/**": true, + "**/node_modules/**": true, + "**/.cache/**": true, + "**/python3-venv/**": true + } +} +``` + +## Backup and Migration + +### Backing Up Volumes + +```bash +# Backup a volume to tarball +docker run --rm \ + -v engflow_auth:/data \ + -v $(pwd):/backup \ + ubuntu tar czf /backup/engflow_auth_backup.tar.gz -C /data . + +# Backup all MongoDB dev volumes +for vol in engflow_auth mongo-cache mongo-python3-venv; do + docker run --rm \ + -v $vol:/data \ + -v $(pwd):/backup \ + ubuntu tar czf /backup/${vol}_backup.tar.gz -C /data . +done +``` + +### Restoring Volumes + +```bash +# Create volume +docker volume create engflow_auth + +# Restore from backup +docker run --rm \ + -v engflow_auth:/data \ + -v $(pwd):/backup \ + ubuntu tar xzf /backup/engflow_auth_backup.tar.gz -C /data +``` + +### Migrating to New Machine + +**Option 1: Export and Import Volumes** + +On old machine: + +```bash +# Backup volumes (see above) +# Copy .tar.gz files to new machine +``` + +On new machine: + +```bash +# Restore volumes (see above) +# Clone repository and open devcontainer +``` + +**Option 2: Use Docker Save/Load** + +```bash +# Old machine: Save container image +docker save -o mongo-devcontainer.tar + +# New machine: Load image +docker load -i mongo-devcontainer.tar +``` + +## Development Workflows + +### Debugging Workflow + +**With GDB:** + +```bash +# Build with debug symbols +bazel build --config=dbg install-mongod + +# Run with GDB +gdb bazel-bin/install-mongod/bin/mongod +(gdb) run --dbpath /data/db +(gdb) break my_function +(gdb) continue +``` + +## Tips and Tricks + +### Quick Commands + +```bash +# Rebuild devcontainer from terminal +# Cmd/Ctrl+Shift+P → "Dev Containers: Rebuild Container" + +# Attach to running container +docker exec -it /bin/bash + +# Copy compile_commands.json to host (for external IDE) +docker cp :/workspaces/mongo/compile_commands.json ~/Desktop/ + +# Check what's using disk space +du -sh ~/.cache/* +du -sh /opt/mongodbtoolchain/* +``` + +--- + +**See Also:** + +- [Architecture](./architecture.md) - How it all works +- [Troubleshooting](./troubleshooting.md) - Fix issues +- [FAQ](./faq.md) - Common questions diff --git a/docs/devcontainer/architecture.md b/docs/devcontainer/architecture.md new file mode 100644 index 00000000000..2ef5a0629a4 --- /dev/null +++ b/docs/devcontainer/architecture.md @@ -0,0 +1,563 @@ +# Dev Container Architecture + +This document provides a deep dive into how the MongoDB devcontainer is structured and how all the pieces work together. + +## Table of Contents + +- [Overview](#overview) +- [Directory Structure](#directory-structure) +- [Container Build Process](#container-build-process) +- [Volume Management](#volume-management) +- [Toolchain Installation](#toolchain-installation) +- [Features System](#features-system) +- [VS Code Integration](#vs-code-integration) +- [Post-Creation Scripts](#post-creation-scripts) +- [Environment Variables](#environment-variables) + +## Overview + +The MongoDB devcontainer is built on several key components: + +```mermaid +flowchart TD + VSCode["VS Code"] + Extension["Dev Containers Extension"] + DevContainer["devcontainer.json"] + Dockerfile["Dockerfile"] + Volumes["Volumes
- engflow
- cache
- venv
- history"] + BaseImage["Base Image
(Bazel RBE Ubuntu)"] + Toolchain["MongoDB Toolchain
(GCC, Clang, etc.)"] + Features["Features
- workstation
- git
- bazel
- docker"] + PostCreate["Post-Create Commands
- setup poetry
- setup venv
- setup clangd"] + + VSCode --> Extension + Extension -->|reads| DevContainer + DevContainer -->|references| Dockerfile + DevContainer -->|mounts volumes| Volumes + Dockerfile -->|builds| BaseImage + BaseImage -->|installs| Toolchain + Toolchain -->|runs| Features + Features -->|executes| PostCreate +``` + +## Directory Structure + +``` +.devcontainer/ +├── devcontainer.json # Main configuration file +├── Dockerfile # Container image definition +├── toolchain_config.env # Toolchain version and checksum +├── toolchain.py # Toolchain management script +├── features/ # Custom devcontainer features +│ └── workstation/ +│ ├── devcontainer-feature.json +│ ├── install.sh +│ └── setup.sh +└── OWNERS.yml # Code ownership info +``` + +## Container Build Process + +### 1. Base Image Selection + +The Dockerfile starts from MongoDB's Remote Build Execution (RBE) image: + +```dockerfile +# The base image version is managed in .devcontainer/Dockerfile +# Check that file for the current version +ARG BASE_IMAGE=quay.io/mongodb/bazel-remote-execution:ubuntu24- +FROM $BASE_IMAGE +``` + +This base image includes: + +- Ubuntu 24.04 LTS +- Basic build tools +- Bazel dependencies +- System libraries needed for MongoDB + +### 2. User Creation + +A non-root user is created with the same username as your host user: + +```dockerfile +ARG USERNAME=mongo-dev +ARG USER_UID=1000 +ARG USER_GID=$USER_UID + +RUN groupadd $USERNAME && useradd -s /bin/bash --gid $USER_GID -m $USERNAME +``` + +**Why?** + +- Avoids permission issues with mounted volumes +- Matches your host user ID for file ownership +- Follows security best practices (don't run as root) + +### 3. Sudo Access + +The user gets passwordless sudo access for administrative tasks: + +```dockerfile +RUN echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/devcontaineruser +``` + +### 4. Persistent Bash History + +Bash history is configured to persist across container restarts: + +```dockerfile +RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \ + && mkdir /commandhistory \ + && touch /commandhistory/.bash_history \ + && chown -R $USERNAME /commandhistory \ + && echo "$SNIPPET" >> "/home/$USERNAME/.bashrc" +``` + +The `/commandhistory` directory is mounted from a Docker volume. + +### 5. Toolchain Installation + +See [Toolchain Installation](#toolchain-installation) section below. + +### 6. Bazel Telemetry + +Build event keywords are added for analytics: + +```dockerfile +RUN echo "common --bes_keywords=devcontainer:use=true" >> "$HOME/.bazelrc" && \ + echo "common --bes_keywords=devcontainer:image=$BASE_IMAGE" >> "$HOME/.bazelrc" && \ + echo "common --bes_keywords=devcontainer:username=$USERNAME" >> "$HOME/.bazelrc" +``` + +This helps MongoDB track devcontainer usage and identify issues. + +## Volume Management + +The devcontainer uses several Docker volumes for persistence: + +### Volume Configuration + +From `devcontainer.json`: + +```json +"mounts": [ + { + "source": "engflow_auth", + "target": "/home/${localEnv:USER}/.config/engflow_auth", + "type": "volume" + }, + { + "source": "${containerWorkspaceFolderBasename}-cache", + "target": "/home/${localEnv:USER}/.cache", + "type": "volume" + }, + { + "source": "mongo-bashhistory", + "target": "/commandhistory", + "type": "volume" + } +] +``` + +### Volume Descriptions + +| Volume | Purpose | Survives Container Rebuild? | Size Impact | +| -------------------------- | ---------------------------------- | --------------------------- | ----------- | +| `engflow_auth` | EngFlow authentication credentials | ✅ Yes | Small | +| `{workspace}-cache` | Bazel cache, tool caches | ✅ Yes | Large | +| `mongo-bashhistory` | Command history | ✅ Yes | Small | +| `{workspace}-python3-venv` | Python virtual environment | ✅ Yes | Medium | + +### Workspace Volume + +The workspace itself is in a separate volume created by the clone command: + +```bash +docker volume ls +# Shows: mongo-workspace (or your chosen name) +``` + +**Benefits of Named Volumes:** + +- Fast I/O (no filesystem translation layer) +- Survives container deletion +- Can be backed up with `docker volume` commands +- No host filesystem dependencies + +### Managing Volumes + +```bash +# List all volumes +docker volume ls + +# Inspect a volume +docker volume inspect engflow_auth +``` + +## Toolchain Installation + +MongoDB requires specific compiler versions. The toolchain installation process ensures consistency. + +### Toolchain Configuration + +The `toolchain_config.env` file contains architecture-specific toolchain definitions for both ARM64 and AMD64: + +```bash +# Generated by toolchain.py +# DO NOT EDIT MANUALLY - run: python3 toolchain.py generate + +# ARM64 Toolchain +TOOLCHAIN_ARM64_URL="https://s3.amazonaws.com/boxes.10gen.com/build/toolchain/mongodbtoolchain-ubuntu2404-arm64-..." +TOOLCHAIN_ARM64_SHA256="" +TOOLCHAIN_ARM64_KEY="build/toolchain/mongodbtoolchain-ubuntu2404-arm64-..." +TOOLCHAIN_ARM64_LAST_MODIFIED="2025-07-21T20:49:55+00:00" + +# AMD64 Toolchain +TOOLCHAIN_AMD64_URL="https://s3.amazonaws.com/boxes.10gen.com/build/toolchain/mongodbtoolchain-ubuntu2404-..." +TOOLCHAIN_AMD64_SHA256="" +TOOLCHAIN_AMD64_KEY="build/toolchain/mongodbtoolchain-ubuntu2404-..." +TOOLCHAIN_AMD64_LAST_MODIFIED="2025-07-21T19:57:00+00:00" +``` + +**Note**: This file is auto-generated. To update toolchain versions, run: + +```bash +python3 .devcontainer/toolchain.py generate +``` + +### Installation Process + +The Dockerfile automatically selects the correct toolchain based on the target platform: + +```dockerfile +# Load configuration and select architecture-specific toolchain +ARG TARGETPLATFORM +COPY .devcontainer/toolchain_config.env /tmp/toolchain_config.env +RUN set -e; \ + . /tmp/toolchain_config.env; \ + # Select toolchain based on platform + if [ "$TARGETPLATFORM" = "linux/arm64" ]; then \ + TOOLCHAIN_URL="$TOOLCHAIN_ARM64_URL"; \ + TOOLCHAIN_SHA256="$TOOLCHAIN_ARM64_SHA256"; \ + ARCH="arm64"; \ + elif [ "$TARGETPLATFORM" = "linux/amd64" ]; then \ + TOOLCHAIN_URL="$TOOLCHAIN_AMD64_URL"; \ + TOOLCHAIN_SHA256="$TOOLCHAIN_AMD64_SHA256"; \ + ARCH="amd64"; \ + else \ + echo "Unsupported platform: $TARGETPLATFORM"; \ + exit 1; \ + fi; \ + echo "Target platform: $TARGETPLATFORM"; \ + echo "Architecture: $ARCH"; \ + echo "Installing toolchain from: $TOOLCHAIN_URL"; \ + + # Download + curl -fSL "$TOOLCHAIN_URL" -o /tmp/toolchain.tar.gz; \ + + # Verify checksum (security!) + echo "$TOOLCHAIN_SHA256 /tmp/toolchain.tar.gz" | sha256sum -c -; + +# Extract +RUN mkdir -p /opt/mongodbtoolchain/revisions && \ + tar -xzf /tmp/toolchain.tar.gz -C /opt/mongodbtoolchain/revisions; \ + rm /tmp/toolchain.tar.gz; \ + chown -R ${USERNAME} /opt/mongodbtoolchain; + +# Run installation script +USER $USERNAME +RUN /opt/mongodbtoolchain/revisions/*/scripts/install.sh +``` + +**Multi-Architecture Support:** + +- The `TARGETPLATFORM` build argument is automatically set by Docker based on your host architecture +- Supports both `linux/arm64` (Apple Silicon, ARM servers) and `linux/amd64` (Intel/AMD processors) +- Each architecture gets its own optimized toolchain binary +- Build fails safely if run on an unsupported platform + +### Toolchain Contents + +The MongoDB toolchain includes: + +- **GCC**: Primary C/C++ compiler +- **Clang**: Alternative compiler and tools (clang-format, clang-tidy) +- **Python**: For build scripts +- **gdb**: GNU debugger with pretty printers +- **binutils**: Assembler, linker, and other tools + +### Toolchain Updates + +The toolchain is managed by the MongoDB team. When updates are available, you'll get them automatically when you: + +- Pull the latest changes from the repository +- Rebuild your devcontainer + +You don't need to manually update the toolchain. + +## Features System + +Dev Containers support modular "features" - reusable units of functionality. + +### Feature Configuration + +From `devcontainer.json`: + +```json +"features": { + "./features/workstation": {}, // Custom + "ghcr.io/devcontainers/features/git:1": {}, // Official + "ghcr.io/devcontainers-community/features/bazel:1": {}, // Community + "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},// Official + "ghcr.io/devcontainers/features/common-utils:2": { // Official + "username": "${localEnv:USER}" + } +} +``` + +### Custom Workstation Feature + +The `features/workstation` feature is MongoDB-specific. + +**Structure:** + +``` +features/workstation/ +├── devcontainer-feature.json # Metadata and configuration +├── install.sh # Runs during image build +└── setup.sh # Runs during container creation +``` + +**What it does:** + +1. **Mounts Python venv volume** (from `devcontainer-feature.json`): + + ```json + "mounts": [ + { + "source": "${containerWorkspaceFolderBasename}-python3-venv", + "target": "${containerWorkspaceFolder}/python3-venv", + "type": "volume" + } + ] + ``` + +2. **Runs setup script** that installs: + - pipx (Python package installer) + - poetry (dependency manager) + - db-contrib-tool (MongoDB contribution tool) + - clangd configuration + - GDB pretty printers for Boost + - Python virtual environment with all dependencies + +### Official Features + +- **git**: Latest Git with credential helper +- **bazel**: Bazelisk (Bazel version manager) +- **docker-outside-of-docker**: Access to host Docker daemon +- **common-utils**: zsh, Oh My Zsh, and other utilities + +## VS Code Integration + +### Settings + +The `devcontainer.json` includes extensive VS Code settings: + +#### C/C++ Configuration + +```json +"clangd.checkUpdates": true, +"clangd.path": "${workspaceFolder}/buildscripts/clangd_vscode.sh", +"clang-format.executable": "${workspaceRoot}/bazel-out/.../clang-format", +``` + +**Why clangd?** + +- Faster IntelliSense than Microsoft C++ extension +- Better standard library support +- Integrates with compile_commands.json + +#### Python Configuration + +```json +"python.defaultInterpreterPath": "python3-venv/bin/python", +"python.autoComplete.extraPaths": [ + "/opt/mongodbtoolchain/v5/share/gcc-*/python" +], +"mypy-type-checker.importStrategy": "fromEnvironment", +"editor.defaultFormatter": "charliermarsh.ruff" +``` + +Uses the virtual environment Python and Ruff for formatting. + +#### JavaScript Configuration + +```json +"prettier.prettierPath": "bazel-bin/node_modules/.aspect_rules_js/prettier@3.4.2/node_modules/prettier", +"eslint.validate": ["javascript"], +"editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" +} +``` + +Uses Bazel-managed Prettier and ESLint. + +#### Format on Save + +```json +"[c]": { + "editor.defaultFormatter": "xaver.clang-format", + "editor.formatOnSave": true +}, +"[cpp]": { + "editor.defaultFormatter": "xaver.clang-format", + "editor.formatOnSave": true +}, +"[python]": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "charliermarsh.ruff" +}, +"[javascript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true +} +``` + +### Extensions + +Recommended extensions are automatically installed: + +- **llvm-vs-code-extensions.vscode-clangd**: C++ IntelliSense +- **dbaeumer.vscode-eslint**: JavaScript linting +- **ms-python.python**: Python support +- **charliermarsh.ruff**: Python formatting/linting +- **xaver.clang-format**: C++ formatting +- **bazelbuild.vscode-bazel**: Bazel support +- **redhat.vscode-yaml**: YAML support +- And more... + +## Post-Creation Scripts + +After the container starts, several commands run to finalize setup: + +### From devcontainer.json + +```json +"postCreateCommand": { + "fixVolumePerms": "sudo chown -R $(whoami): ${containerEnv:HOME}/.config/engflow_auth && sudo chown -R $(whoami): ${containerEnv:HOME}/.cache", + "venvActivation": "echo 'source ${containerWorkspaceFolder}/python3-venv/bin/activate && ${containerWorkspaceFolder}/buildscripts/poetry_sync.sh' >> ~/.bashrc && echo 'source ${containerWorkspaceFolder}/python3-venv/bin/activate && ${containerWorkspaceFolder}/buildscripts/poetry_sync.sh' >> ~/.zshrc;", + "createDataDir": "sudo mkdir -p /data/db && sudo chown -R $(whoami): /data/db", + "reportDockerServerPlatform": "echo \"\ncommon --bes_keywords=devcontainer:docker_server_platform=$(docker version --format '\"{{.Server.Platform.Name}}\"')\" >> ${containerEnv:HOME}/.bazelrc", + "reportDockerServerVersion": "echo \"\ncommon --bes_keywords=devcontainer:docker_server_version=$(docker version --format '\"{{.Server.Version}}\"')\" >> ${containerEnv:HOME}/.bazelrc", + "reportArch": "echo \"\ncommon --bes_keywords=devcontainer:arch=$(uname -i)\" >> ${containerEnv:HOME}/.bazelrc" +} +``` + +### From Workstation Feature + +The workstation feature's `postCreateCommand`: + +```bash +sudo chown -R $(whoami): ${containerWorkspaceFolder}/python3-venv && \ +sudo chown $(whoami): ${containerWorkspaceFolder}/.. && \ +bash /workspace-setup.sh +``` + +The `setup.sh` script then: + +1. Sets up Bash profile +2. Installs pipx +3. Installs poetry via pipx +4. Installs db-contrib-tool +5. Builds clangd configuration +6. Sets up GDB pretty printers +7. Creates Python virtual environment +8. Runs `poetry install` to install all dependencies + +## Environment Variables + +### Set in devcontainer.json + +```json +"containerEnv": { + "HOME": "/home/${localEnv:USER}" +} +``` + +### Set in Shell + +Added to `.bashrc` during setup: + +```bash +export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring +export PATH="$PATH:$HOME/.local/bin" +export HISTFILE=/commandhistory/.bash_history +export PROMPT_COMMAND='history -a' +``` + +### From Toolchain + +When you activate the toolchain environment: + +```bash +source /opt/mongodbtoolchain/revisions/*/activate +``` + +This sets: + +- `CC`, `CXX`: Compiler paths +- `PATH`: Toolchain binaries +- `LD_LIBRARY_PATH`: Toolchain libraries +- Python paths for GDB pretty printers + +## Lifecycle Summary + +**Build Time (Dockerfile):** + +1. Pull base image +2. Create user +3. Download and verify toolchain +4. Extract toolchain +5. Run toolchain install script +6. Add Bazel telemetry + +**Container Creation (Features + postCreateCommand):** + +1. Mount volumes +2. Install feature dependencies +3. Fix volume permissions +4. Setup Bash/Zsh +5. Install Python tools (pipx, poetry, db-contrib-tool) +6. Build clangd config +7. Setup GDB +8. Create Python venv +9. Install Poetry dependencies +10. Create MongoDB data directory +11. Report Docker info to Bazel + +**Runtime:** + +1. Shell automatically activates Python venv +2. Poetry keeps dependencies in sync +3. VS Code extensions provide IDE features +4. Bazel uses cached artifacts +5. Commands persist to history volume + +## Customization Points + +See [Advanced Usage](./advanced.md) for details on: + +- Adding your own tools to the Dockerfile +- Creating custom features +- Overriding VS Code settings +- Using different toolchain versions +- Configuring EngFlow remote execution + +--- + +**Next Steps:** + +- [Troubleshooting Guide](./troubleshooting.md) +- [Advanced Usage](./advanced.md) +- [FAQ](./faq.md) diff --git a/docs/devcontainer/faq.md b/docs/devcontainer/faq.md new file mode 100644 index 00000000000..b4b28e656aa --- /dev/null +++ b/docs/devcontainer/faq.md @@ -0,0 +1,502 @@ +# Dev Container FAQ + +Frequently asked questions about MongoDB development with dev containers. + +## General Questions + +### What is a dev container? + +A dev container (development container) is a Docker container configured specifically for development. It includes: + +- All build tools and dependencies +- IDE configuration and extensions +- Persistent storage for caches and settings +- Consistent environment across all developers + +Think of it as a portable, reproducible development environment that runs on any machine with Docker. + +[Learn more about dev containers →](https://containers.dev/) + +### Is this production-ready or still experimental? + +The MongoDB devcontainer is currently in **Beta**. This means: + +- Core functionality works well +- Most developers can use it for daily work +- Some edge cases may need refinement +- Active development and improvements ongoing + +Report issues to help improve it for everyone! + +## Setup and Installation + +### Do I need SSH keys to use devcontainers? + +**No, but SSH is recommended** for contributors who will be pushing code. + +**You can use:** + +- ✅ **SSH** (recommended): `git@github.com:mongodb/mongo.git` + - Pros: More secure, no password prompts, required for pushing code + - Requires: SSH keys configured with GitHub +- ✅ **HTTPS**: `https://github.com/mongodb/mongo.git` + - Pros: Works without SSH keys, simpler for read-only access + - Cons: May require password/token for push operations + +See the [Getting Started guide SSH setup section](./getting-started.md#4-configure-ssh-keys-recommended) for details. + +### How do SSH keys work with devcontainers? + +VS Code automatically forwards your SSH agent to the container, so you don't need to copy keys into the container. + +**Requirements:** + +1. SSH keys must be on your **host machine** (not in container) +2. SSH agent must be running with keys loaded +3. Keys should be in default location (`~/.ssh/`) + +**Verify on host before opening container:** + +```bash +# Check ssh-agent has your keys +ssh-add -l + +# Test GitHub connection +ssh -T git@github.com +``` + +**Inside the container**, Git commands will automatically use your host's SSH keys through agent forwarding. + +[Learn more about SSH agent forwarding →](https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials) + +### Why does git push ask for credentials in the container? + +This usually means SSH agent forwarding isn't working. + +**Fix:** + +```bash +# On HOST machine (outside container): +# Ensure ssh-agent is running and has your key +ssh-add -l + +# If empty, add your key +ssh-add ~/.ssh/id_ed25519 # or id_rsa + +# Rebuild container to pick up agent forwarding +# Command Palette → "Dev Containers: Rebuild Container" +``` + +### Which Docker provider should I use? + +**Recommended: Rancher Desktop** + +- Free and open source +- Easy to configure +- Good performance +- Works well with devcontainers + +**Alternatives:** + +- Docker Desktop: Popular, user-friendly, requires license for large companies +- OrbStack (macOS): Lightweight, fast, newer +- Docker Engine (Linux): Direct, no GUI overhead + +See [Getting Started](./getting-started.md#1-install-docker) for details. + +### Why does the setup take so long? + +First-time setup includes: + +1. Downloading base image (~2 GB) +2. Building custom container (~5-10 min) +3. Downloading toolchain (~3 GB) +4. Installing Python dependencies (~5-10 min) +5. Building clangd index (~5 min) + +**Total:** ~20-30 minutes depending on internet speed + +**Subsequent rebuilds** are much faster due to Docker layer caching. + +### Can I use this on Windows? + +**Yes!** Requirements: + +- Windows 10/11 +- WSL2 installed and configured +- Docker Desktop with WSL2 integration enabled + +**Important:** Clone repository in WSL2 filesystem (not `/mnt/c/`), not Windows filesystem, for best performance. + +### Can I use this on Apple Silicon (M1/M2/M3)? + +**Yes!** The devcontainer supports ARM64 architecture. Ensure: + +- Docker provider supports ARM64 (Rancher Desktop, Docker Desktop do) +- Base image has ARM64 variant (current MongoDB image does) +- Rosetta 2 is enabled if needed (Rancher Desktop setting) + +## Usage Questions + +### Where is my code stored? + +Your code lives in a **Docker volume**, not your local filesystem. + +- **Inside container**: `/workspaces/mongo` +- **On host**: Managed by Docker (see `docker volume inspect `) + +This is by design for performance, especially on macOS. + +### How do I access files from my host OS? + +**Option 1: Copy files out** + +```bash +docker cp :/workspaces/mongo/file.txt ~/Downloads/ +``` + +**Option 2: Download from VS Code** + +- Right-click file → Download... + +**Option 3: Use bind mount** (sacrifices performance) + +Open your existing local repository in VS Code and use "Dev Containers: Reopen in Container". This uses a bind mount which allows direct host filesystem access but is slower, especially on macOS. + +### Can I use my existing local clone? + +**Yes**, but not recommended for best performance. + +**Option A: Reopen in container** (bind mount - slower) + +1. Open your local repo in VS Code +2. Command Palette → "Dev Containers: Reopen in Container" + +**Option B: Clone into volume** (recommended - faster) + +1. Use "Clone Repository in Named Container Volume" +2. Delete local clone or keep for reference + +### How do I switch between branches? + +**Same as normal Git:** + +```bash +git checkout main +git checkout -b feature/new-feature +git switch other-branch +``` + +Everything works the same; Git is inside the container. + +### Can I run multiple containers simultaneously? + +**Yes!** Clone the repository multiple times with different volume names: + +1. Container 1: `mongo-main` (main branch) +2. Container 2: `mongo-feature` (feature branch) +3. Container 3: `mongo-review` (PR review) + +Each runs independently with its own cache and environment. + +### How do I update the devcontainer? + +**To get latest changes:** + +```bash +# Pull latest changes +git checkout main +git pull + +# Rebuild container +# Command Palette → "Dev Containers: Rebuild Container" +``` + +This rebuilds the container with any updates to Dockerfile, toolchain, or features. + +### Will my data persist after closing the container? + +**Yes!** Data in volumes persists: + +- ✅ Source code (in workspace volume) +- ✅ Bazel cache (in cache volume) +- ✅ Python venv (in venv volume) +- ✅ Shell history (in history volume) +- ✅ EngFlow credentials (in engflow_auth volume) + +**What doesn't persist:** + +- ❌ Processes (stopped on container stop) +- ❌ System packages installed with `apt-get` (unless in Dockerfile) +- ❌ Files in `/tmp` + +### What happens if I delete the container? + +**Volumes are preserved**, so you won't lose: + +- Your source code +- Build caches +- Python environment +- Credentials + +Just reopen the container and everything is back. + +## Development Questions + +### How do I build MongoDB? + +See [MongoDB Building Guide](../../building.md). + +### How do I debug code? + +See [Advanced Usage - Debugging Workflow](./advanced.md#debugging-workflow) + +### Why is my first build so slow? + +First build downloads and compiles everything: + +- Third-party dependencies +- MongoDB source +- Generates build files + +**First build:** 30-60 minutes +**Incremental builds:** 1-5 minutes + +**To speed up:** + +- Ensure cache volume is mounted +- Allocate more CPU/RAM to Docker + +### How do I format code? + +**Automatic (on save):** + +- C/C++: clang-format runs automatically +- Python: Ruff runs automatically +- JavaScript: Prettier runs automatically + +**Manual:** + +```bash +# Format all files +bazel run format +``` + +### How do I use clangd for IntelliSense? + +**It's automatic!** The devcontainer: + +1. Builds `compile_commands.json` during setup +2. Configures VS Code to use clangd +3. Disables Microsoft C++ extension + +**If not working:** + +```bash +# Rebuild compile database +bazel build compiledb --config=local + +# Restart clangd +# Command Palette → "clangd: Restart language server" +``` + +## Troubleshooting + +### My build is very slow on macOS + +**Check you're using a named volume:** + +```bash +# Inside container +df -h /workspaces/mongo +``` + +If you see a mount from `/Users/...`, you're using a bind mount. + +**Solution:** Clone in a named volume (see [Getting Started](./getting-started.md)). + +### Python packages are missing + +**Activate the virtual environment:** + +```bash +source python3-venv/bin/activate + +# Should show (python3-venv) in prompt +which python +# Should show: /workspaces/mongo/python3-venv/bin/python +``` + +**Reinstall packages:** + +```bash +poetry install --no-root --sync +``` + +### VS Code extensions aren't working + +**Reload window:** + +- Command Palette → "Developer: Reload Window" + +**Reinstall extension:** + +- Extensions panel → Click extension → Uninstall → Install + +**Check it's a container extension:** + +- Some extensions only work on host, not in containers +- Look for "Install in Dev Container" button + +### Bazel fails with toolchain errors + +**Verify toolchain:** + +```bash +ls -la /opt/mongodbtoolchain/revisions/ +gcc --version # Should show the MongoDB toolchain GCC version +``` + +**Rebuild container:** + +- Command Palette → "Dev Containers: Rebuild Container" + +### I can't connect to EngFlow + +**Check credentials:** + +```bash +ls -la ~/.config/engflow_auth/ +``` + +**Re-authenticate:** +Contact MongoDB team for authentication flow. + +**Build locally instead:** + +```bash +bazel build --config=local install-mongod +``` + +### The container won't start + +**Check Docker is running:** + +```bash +docker info +docker ps +``` + +**View logs:** + +- Command Palette → "Dev Containers: Show Container Log" +- Or: `docker logs ` + +**Rebuild from scratch:** + +- Command Palette → "Dev Containers: Rebuild Container Without Cache" + +## Performance and Resources + +### How much disk space do I need? + +Allocate as much disk space as you can comfortably spare. We recommend at least 60GB + +### How much RAM should I allocate to Docker? + +**Allocate as much as possible** while leaving enough for your host OS to function (~4-8 GB). + +More RAM = faster builds with more parallel jobs. MongoDB builds are resource-intensive and benefit greatly from additional memory. + +### How many CPU cores should I allocate? + +**Allocate as many cores as possible** while leaving a couple for your host OS (1-2 cores). + +Bazel parallelizes well; more cores = significantly faster builds. If you have 8+ cores available, MongoDB builds will complete much faster. + +### Can I reduce resource usage? + +**Yes**, with trade-offs in build speed: + +**Reduce Bazel parallelism:** + +```bash +bazel build --jobs=N # Replace N with fewer parallel jobs +``` + +**Limit memory:** + +```bash +bazel build --local_ram_resources=HOST_RAM*0.5 # Use only 50% of available RAM +``` + +**Clear cache periodically:** + +```bash +bazel clean # Clear build outputs +bazel clean --expunge # Clear everything (reclaim disk space) +``` + +> **Note:** Reducing resources will make builds slower. If possible, it's better to allocate more resources to Docker instead. + +### How do I monitor resource usage? + +```bash +docker stats # Live resource usage +``` + +**Inside container:** + +```bash +htop # If installed +top # Always available +df -h # Disk usage +``` + +## Advanced Topics + +### Can I customize the container? + +**Yes!** See [Advanced Usage](./advanced.md) for: + +- Using dotfiles in your containers +- Creating custom features +- Modifying VS Code settings + +### Can I run the container without VS Code? + +**Yes!** Use Docker directly: + +```bash +# Build image +docker build -t mongo-dev -f .devcontainer/Dockerfile . + +# Run container +docker run -it --rm \ + -v mongo-workspace:/workspaces/mongo \ + -v mongo-cache:/home/user/.cache \ + mongo-dev /bin/bash + +# Now you're in the container +cd /workspaces/mongo +bazel build install-mongod +``` + +But you lose VS Code integration, extensions, and convenience features. + +## Getting Help + +### Where can I find more information? + +- **Getting Started**: [getting-started.md](./getting-started.md) +- **Architecture Details**: [architecture.md](./architecture.md) +- **Troubleshooting**: [troubleshooting.md](./troubleshooting.md) +- **Advanced Topics**: [advanced.md](./advanced.md) +- **VS Code Docs**: [code.visualstudio.com/docs/devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) + +### Who do I contact for help? + +1. **Documentation**: Check this guide first +2. **Search Issues**: Jira issues +3. **Internal Teams**: #server-local-dev channel in Slack (for employees) +4. **File Bug**: Create Jira issue with details diff --git a/docs/devcontainer/getting-started.md b/docs/devcontainer/getting-started.md new file mode 100644 index 00000000000..fdc92f58fb8 --- /dev/null +++ b/docs/devcontainer/getting-started.md @@ -0,0 +1,469 @@ +# Getting Started with MongoDB Dev Containers + +This guide will walk you through setting up your MongoDB development environment using Dev Containers. + +## Prerequisites + +### 1. Install Docker + +Dev Containers require Docker to be installed and running on your system. Choose one of the following Docker providers: + +#### Option A: Rancher Desktop (Recommended) + +[Rancher Desktop](https://rancherdesktop.io/) is our recommended Docker provider for devcontainer development. + +**Installation:** + +1. Download and install Rancher Desktop from [rancherdesktop.io](https://rancherdesktop.io/) +2. On first launch, configure these settings: + - **Kubernetes**: Choose any option (not required for devcontainers) + - **Container Engine**: Select `dockerd (moby)` ⚠️ **Important!** + - **Configure Path**: Select "Automatic" + +**Recommended Settings:** +After installation, increase resources for better build performance: + +1. Open Rancher Desktop → Preferences → Virtual Machine +2. **Memory**: Allocate as much as your system allows (leave ~4-8 GB for your host OS) +3. **CPUs**: Allocate as many cores as possible (leave 1-2 for your host OS) +4. Apply changes and restart Rancher Desktop + +> **Tip:** More resources = faster builds. MongoDB builds benefit significantly from additional CPU cores and memory. + +#### Option B: Docker Desktop + +[Docker Desktop](https://www.docker.com/products/docker-desktop/) is a popular alternative. + +**Installation:** + +1. Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) +2. Install and start Docker Desktop +3. Go to Settings → Resources and allocate generously: + - **Memory**: Allocate as much as possible (leave ~4-8 GB for your host OS) + - **CPUs**: Allocate as many cores as possible (leave 1-2 for your host OS) + - **Disk**: Ensure plenty of space available (60+ GB recommended) + +#### Option C: OrbStack (macOS) + +[OrbStack](https://orbstack.dev/) is a lightweight, fast Docker alternative for macOS. + +**Installation:** + +1. Download from [orbstack.dev](https://orbstack.dev/) +2. Install and launch OrbStack +3. OrbStack automatically manages resources efficiently + +#### Option D: Docker Engine (Linux only) + +For Linux users, you can use Docker Engine directly. + +**Installation:** +Follow the official guide: [docs.docker.com/engine/install](https://docs.docker.com/engine/install/) + +### 2. Install Visual Studio Code + +Download and install VS Code from [code.visualstudio.com](https://code.visualstudio.com/) + +### 3. Install Dev Containers Extension + +1. Open VS Code +2. Go to Extensions (⌘/Ctrl+Shift+X) +3. Search for "Dev Containers" +4. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension by Microsoft + +### 4. Configure SSH Keys (Recommended) + +To clone the repository using SSH (recommended for contributors), you'll need SSH keys configured with GitHub. + +#### Check if you have SSH keys + +```bash +# Check for existing SSH keys +ls -la ~/.ssh/id_*.pub + +# If you see id_rsa.pub, id_ed25519.pub, or similar, you have keys +``` + +#### Generate SSH keys (if needed) + +If you don't have SSH keys, generate them: + +```bash +# Generate a new ED25519 key (recommended) +ssh-keygen -t ed25519 -C "your_email@example.com" + +# Or generate RSA key (if ED25519 not supported) +ssh-keygen -t rsa -b 4096 -C "your_email@example.com" + +# Press Enter to accept default location +# Enter a passphrase (recommended) or press Enter for no passphrase +``` + +#### Add SSH key to GitHub + +1. **Copy your public key:** + + ```bash + # For ED25519 + cat ~/.ssh/id_ed25519.pub + + # For RSA + cat ~/.ssh/id_rsa.pub + ``` + +2. **Add to GitHub:** + + - Go to [GitHub SSH Settings](https://github.com/settings/keys) + - Click "New SSH key" + - Paste your public key + - Give it a descriptive title (e.g., "Work Laptop") + - Click "Add SSH key" + +3. **Test your connection:** + ```bash + ssh -T git@github.com + # Should see: "Hi username! You've successfully authenticated..." + ``` + +#### SSH Agent (for keys with passphrases) + +If your SSH key has a passphrase, add it to the SSH agent: + +```bash +# Start ssh-agent (macOS/Linux) +eval "$(ssh-agent -s)" + +# Add your key to the agent +ssh-add ~/.ssh/id_ed25519 # or id_rsa + +# Verify key is loaded +ssh-add -l +``` + +**macOS users:** Add this to `~/.ssh/config` to automatically load keys: + +``` +Host * + AddKeysToAgent yes + UseKeychain yes + IdentityFile ~/.ssh/id_ed25519 +``` + +For passphrase-protected keys, also add to `~/.zshrc` or `~/.bashrc`: + +```bash +ssh-add --apple-use-keychain ~/.ssh/id_ed25519 2>/dev/null +``` + +**Windows users:** The ssh-agent service should start automatically. If not: + +```powershell +# In PowerShell (as Administrator) +Get-Service ssh-agent | Set-Service -StartupType Automatic +Start-Service ssh-agent +``` + +> **Note:** VS Code automatically forwards your SSH agent to the container, so your keys will be available inside the devcontainer. + +[Learn more about using SSH keys with GitHub →](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) + +## Setup Instructions + +### Step 1: Clone Repository in Named Container Volume + +For **optimal performance**, especially on macOS, clone the repository directly into a Docker volume rather than your local filesystem. This is crucial for Bazel performance. + +#### Why Named Volumes? + +- ✅ **Better I/O Performance**: Native filesystem speed inside container +- ✅ **Bazel Compatibility**: Avoids macOS filesystem case-sensitivity issues +- ✅ **Consistent Behavior**: Same experience across all platforms +- ✅ **Isolation**: Keeps container data separate from host + +#### Cloning Steps: + +1. **Open VS Code Command Palette** + + - macOS: `Cmd+Shift+P` + - Windows/Linux: `Ctrl+Shift+P` + +2. **Run Clone Command** + + - Type: `Dev Containers: Clone Repository in Named Container Volume...` + - Select it from the list + - [Learn more about improving performance with container volumes →](https://code.visualstudio.com/remote/advancedcontainers/improve-performance#_use-a-targeted-named-volume) + +3. **Enter Repository URL** + + ``` + git@github.com:mongodb/mongo.git + ``` + + Or use HTTPS: + + ``` + https://github.com/mongodb/mongo.git + ``` + + > **Tip**: SSH URLs are recommended if you have SSH keys configured + +4. **Choose Volume Name** + + - Enter a name like: `mongo-workspace` + - This creates a Docker volume with that name + - You can reference it later: `docker volume ls` + +5. **Wait for Initial Setup** + - VS Code will: + - Clone the repository to the volume + - Build the devcontainer image + - Start the container + - Install VS Code extensions + - Run post-creation commands + +### Step 2: Complete Git History (Recommended) + +The clone process may create a shallow clone. Fetch the complete history: + +```bash +git fetch --unshallow --all +``` + +This ensures: + +- Access to full repository history +- All branches are available +- Certain build targets work correctly (e.g., `bazel build install-dist`) + +### Step 3: Verify Your Setup + +Let's make sure everything is working correctly. + +#### 3.1 Check Toolchain Installation + +```bash +# Verify GCC version +gcc --version + +# Verify Python version +python3 --version +``` + +#### 3.2 Verify Python Virtual Environment + +The devcontainer automatically sets up a Python virtual environment: + +```bash +# Should already be activated (check for (python3-venv) in prompt) +which python +# Should show: /workspaces/mongo/python3-venv/bin/python + +# Check poetry is available +poetry --version +``` + +#### 3.3 Test Bazel Build + +Try building a target: + +```bash +bazel build install-mongod +``` + +This may take a while on first run but verifies: + +- Bazel is configured correctly +- Toolchain is working +- Build system is functional + +#### 3.4 Check VS Code Extensions + +The following extensions should be installed and active: + +- clangd (C++ IntelliSense) +- ESLint (JavaScript linting) +- Ruff (Python formatting) +- Bazel (Build system support) + +Check: View → Extensions and verify they're enabled. + +### Step 4: Understanding Your Environment + +#### Workspace Location + +Your code lives in a Docker volume, not your local filesystem. To access it: + +- **Inside Container**: `/workspaces/mongo` (default workspace folder) + +#### Persistent Volumes + +Several volumes persist data across container restarts: + +1. **`engflow_auth`** → `~/.config/engflow_auth` + + - EngFlow remote execution credentials + - Survives container rebuilds + +2. **`mongo-cache`** → `~/.cache` + + - Bazel cache + - Tool caches + - Significantly speeds up rebuilds + +3. **`mongo-python3-venv`** → `/workspaces/mongo/python3-venv` + + - Python virtual environment + - Poetry-managed dependencies + - Persists across container updates + +4. **`mongo-bashhistory`** → `/commandhistory` + - Terminal command history + - Available across sessions + +#### Data Directory + +MongoDB data directory is automatically created at `/data/db` with proper permissions. + +## Next Steps + +### Explore the Documentation + +- [Architecture Details](./architecture.md) - Learn how the devcontainer works +- [Advanced Usage](./advanced.md) - Customize and extend your setup +- [Troubleshooting](./troubleshooting.md) - Fix common issues + +## Common First-Time Issues + +### SSH Clone Fails + +**Problem**: Clone fails with "Permission denied (publickey)" or "git@github.com: Permission denied" + +**Solution**: + +```bash +# Test SSH connection from your HOST machine (before starting container) +ssh -T git@github.com + +# If this fails, your SSH keys aren't set up correctly +# Follow the SSH key setup instructions above + +# Check if ssh-agent has your key +ssh-add -l + +# If empty, add your key +ssh-add ~/.ssh/id_ed25519 # or id_rsa + +# If you see "Could not open a connection to your authentication agent" +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 +``` + +### SSH Works Locally But Not in Container + +**Problem**: SSH works on your host machine but fails inside the container + +**Cause**: SSH agent forwarding may not be working + +**Solution**: + +```bash +# On your HOST machine, ensure ssh-agent is running with your keys +ssh-add -l # Should list your keys + +# If not listed, add them +ssh-add ~/.ssh/id_ed25519 + +# In VS Code, rebuild the container +# Command Palette → "Dev Containers: Rebuild Container" +``` + +**VS Code SSH Agent Forwarding**: The Dev Containers extension automatically forwards your SSH agent, but this requires: + +- SSH agent running on host with keys loaded +- SSH key files in default location (`~/.ssh/`) + +[Learn more about sharing git credentials →](https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials) + +### Container Build Fails + +**Problem**: Docker build fails with "no space left on device" + +**Solution**: + +```bash +# Clean up Docker +docker system prune + +# Increase Docker disk space in Docker Desktop/Rancher Desktop settings +``` + +### Slow Performance on macOS + +**Problem**: Bazel builds are very slow + +**Solution**: + +- ✅ Ensure you cloned into a named volume (not bind mount) +- ✅ Allocate more CPU/Memory to Docker +- ✅ Use EngFlow remote execution (see [Advanced Usage](./advanced.md)) + +### Python Virtual Environment Not Activated + +**Problem**: Python commands not found or using wrong version + +**Solution**: + +```bash +# Manually activate +source /workspaces/mongo/python3-venv/bin/activate + +# Reinstall dependencies +poetry install --no-root --sync +``` + +### VS Code Extensions Not Working + +**Problem**: clangd, ESLint, or other extensions show errors + +**Solution**: + +```bash +# Rebuild compile_commands.json for clangd +bazel build compiledb --config=local + +# Restart VS Code window +# Cmd/Ctrl+Shift+P → "Developer: Reload Window" +``` + +## Alternative Setup: Local Clone + Reopen in Container + +If you prefer to clone locally first (not recommended for best performance): + +1. Clone the repository to your local machine: + + ```bash + git clone git@github.com:mongodb/mongo.git + cd mongo + ``` + +2. Open in VS Code: + + ```bash + code . + ``` + +3. Open Command Palette (`Cmd/Ctrl+Shift+P`) + +4. Run: `Dev Containers: Reopen in Container` + +⚠️ **Note**: This uses bind mounts and may have performance issues on macOS with Bazel. + +## Getting Help + +- **Questions**: See the [FAQ](./faq.md) +- **Issues**: Check [Troubleshooting Guide](./troubleshooting.md) +- **Bug Reports**: Open an issue in the MongoDB repository + +--- + +**Next**: [Learn about the Architecture →](./architecture.md) diff --git a/docs/devcontainer/troubleshooting.md b/docs/devcontainer/troubleshooting.md new file mode 100644 index 00000000000..0b69661ef77 --- /dev/null +++ b/docs/devcontainer/troubleshooting.md @@ -0,0 +1,1104 @@ +# Troubleshooting Dev Containers + +This guide covers common issues and their solutions when working with MongoDB dev containers. + +## Table of Contents + +- [Container Build Issues](#container-build-issues) +- [Performance Problems](#performance-problems) +- [VS Code Issues](#vs-code-issues) +- [Git and SSH Issues](#git-and-ssh-issues) +- [Build System Issues](#build-system-issues) +- [Python Environment Issues](#python-environment-issues) +- [Volume and Persistence Issues](#volume-and-persistence-issues) +- [Platform-Specific Issues](#platform-specific-issues) +- [Docker Provider Issues](#docker-provider-issues) +- [Debugging Tips](#debugging-tips) + +## Container Build Issues + +### Build Fails with "No Space Left on Device" + +**Symptoms:** + +``` +Error: failed to solve: write /var/lib/docker/...: no space left on device +``` + +**Solutions:** + +1. **Clean up Docker resources:** + + ```bash + # Remove unused containers, images, and volumes + docker system prune -a --volumes + + # Check disk usage + docker system df + ``` + +2. **Increase Docker disk allocation:** + + - **Docker Desktop/Rancher Desktop**: Settings → Resources → Disk + - Increase to at least 60 GB for comfortable MongoDB development + +3. **Remove old dev containers:** + + ```bash + # List all containers + docker ps -a + + # Remove specific container + docker rm + + # Remove all stopped containers + docker container prune + ``` + +### Build Fails with Toolchain Download Error + +**Symptoms:** + +``` +Error: curl: (22) The requested URL returned error: 404 +Error: Failed to download toolchain +``` + +**Solutions:** + +1. **Check internet connection**: Ensure you can access S3: + + ```bash + curl -I https://s3.amazonaws.com/boxes.10gen.com/ + ``` + +2. **Verify toolchain URL:** + + ```bash + # Check what's configured + cat .devcontainer/toolchain_config.env + + # Try downloading manually to test + curl -I "$(grep TOOLCHAIN_URL .devcontainer/toolchain_config.env | cut -d'"' -f2)" + ``` + +3. **If toolchain URL is broken**, report it to the MongoDB team. This is a devcontainer configuration issue that needs to be fixed upstream. + +### Build Fails with Checksum Mismatch + +**Symptoms:** + +``` +Error: SHA256 checksum mismatch +Expected: abc123... +Got: def456... +``` + +**This typically indicates the toolchain was updated but the config file wasn't.** + +**Solutions:** + +1. **Pull latest changes** from the repository (the maintainers may have already fixed this): + + ```bash + git pull + # Then rebuild container + ``` + +2. **Clear Docker cache and rebuild:** + + ```bash + # Command Palette → "Dev Containers: Rebuild Container Without Cache" + ``` + +3. **If problem persists**, this is likely a devcontainer configuration issue - report it to the MongoDB team. + +### Container Fails to Start + +**Symptoms:** + +- VS Code shows "Container failed to start" +- No error message visible + +**Solutions:** + +1. **Check Docker logs:** + + ```bash + # Find container ID + docker ps -a + + # View logs + docker logs + ``` + +2. **Rebuild container:** + + - Command Palette → "Dev Containers: Rebuild Container" + - Or: "Dev Containers: Rebuild Container Without Cache" + +3. **Check Docker daemon status:** + ```bash + docker info + docker version + ``` + +## Performance Problems + +### Slow Build Times + +**Symptoms:** + +- Bazel builds taking 30+ minutes for incremental changes +- File operations feel sluggish + +**Solutions:** + +1. **Verify you're using a named volume (not bind mount):** + + ```bash + # Inside container + df -h /workspaces/mongo + + # Should NOT show a mount from host filesystem + # Should be part of container's internal filesystem + ``` + + If using bind mount, migrate to named volume: + + - Clone repository in new named volume + - See [Getting Started](./getting-started.md#step-1-clone-repository-in-named-container-volume) + +2. **Increase Docker resources:** + + - **CPUs**: 6+ cores recommended + - **Memory**: 16 GB recommended + - **Swap**: 2-4 GB + +3. **Check cache volume is mounted:** + + ```bash + # Inside container + ls -la ~/.cache/bazel + + # Should have bazel cache directory + ``` + +4. **Verify no antivirus scanning Docker:** + - Exclude Docker Desktop directory from antivirus + - Exclude devcontainer volumes + +### Slow File Operations on macOS + +**Symptoms:** + +- `git status` takes 5+ seconds +- File save is delayed +- Terminal autocomplete is slow + +**Root Cause:** +Bind mounts on macOS use osxfs which has high latency for filesystem operations. + +**Solution:** +✅ **Use named volumes instead of bind mounts** (see Getting Started guide) + +### High CPU Usage + +**Symptoms:** + +- Docker process using 100%+ CPU +- System becomes unresponsive + +**Solutions:** + +1. **Check for runaway processes:** + + ```bash + # Inside container + top + htop # If available + ``` + +2. **Check for file watcher issues:** + ```bash + # Limit file watchers (Linux) + echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf + sudo sysctl -p + ``` + +## VS Code Issues + +For additional VS Code-specific troubleshooting, see: + +- [VS Code Dev Containers FAQ](https://code.visualstudio.com/docs/devcontainers/faq) +- [VS Code Dev Containers Tips and Tricks](https://code.visualstudio.com/docs/devcontainers/tips-and-tricks) + +### Extensions Not Installing + +**Symptoms:** + +- Recommended extensions don't install automatically +- Extension list is empty + +**Solutions:** + +1. **Manually install extensions:** + + - View → Extensions + - Search for each recommended extension + - Click Install in Container + +2. **Check extension compatibility:** + + - Some extensions don't support containers + - Look for "This extension is enabled globally" message + +3. **Reinstall extensions:** + ```bash + # Command Palette + > Developer: Reinstall Extension... + ``` + +### clangd Not Working + +**Symptoms:** + +- No C++ IntelliSense +- "clangd: Server not running" error +- Red squiggles everywhere + +**Solutions:** + +1. **Generate compile_commands.json:** + + ```bash + bazel build compiledb --config=local + + # Verify it exists + ls -lh compile_commands.json + ``` + +2. **Check clangd path:** + + ```bash + # Verify the wrapper script exists + ls -l buildscripts/clangd_vscode.sh + + # Test it + ./buildscripts/clangd_vscode.sh --version + ``` + +3. **Restart clangd:** + + - Command Palette → "clangd: Restart language server" + +4. **Check clangd output:** + + - Output → clangd (dropdown) + - Look for errors + +5. **Clear clangd cache:** + ```bash + rm -rf ~/.cache/clangd + ``` + +### Python Extension Not Finding Interpreter + +**Symptoms:** + +- "Select Python Interpreter" notification +- Python imports not recognized +- Linting/formatting not working + +**Solutions:** + +1. **Verify venv exists:** + + ```bash + ls -la python3-venv/bin/python + source python3-venv/bin/activate + which python + ``` + +2. **Select interpreter in VS Code:** + + - Command Palette → "Python: Select Interpreter" + - Choose `python3-venv/bin/python` + +3. **Rebuild venv:** + + ```bash + rm -rf python3-venv + /opt/mongodbtoolchain/v5/bin/python3 -m venv python3-venv + source python3-venv/bin/activate + poetry install --no-root --sync + ``` + +4. **Check settings.json:** + ```json + { + "python.defaultInterpreterPath": "python3-venv/bin/python" + } + ``` + +### Format on Save Not Working + +**Symptoms:** + +- Files don't format when saved +- Manual format works + +**Solutions:** + +1. **Check settings:** + + ```json + { + "editor.formatOnSave": true, + "[cpp]": { + "editor.defaultFormatter": "xaver.clang-format", + "editor.formatOnSave": true + } + } + ``` + +2. **Verify formatter is installed:** + + - clang-format: Check extension is active + - Ruff: Check extension is active + - Prettier: Verify path in settings + +3. **Test formatter manually:** + - Right-click → Format Document + - Check for errors in Output panel + +## Git and SSH Issues + +### SSH Clone Fails: Permission Denied + +**Symptoms:** + +``` +git@github.com: Permission denied (publickey). +fatal: Could not read from remote repository. +``` + +**Solutions:** + +1. **Verify SSH keys exist on host:** + + ```bash + # On your HOST machine (not in container) + ls -la ~/.ssh/id_*.pub + + # Should see id_ed25519.pub, id_rsa.pub, or similar + ``` + +2. **Test SSH connection to GitHub:** + + ```bash + # On HOST machine + ssh -T git@github.com + + # Should see: "Hi username! You've successfully authenticated..." + # If this fails, your SSH key isn't added to GitHub + ``` + +3. **Add SSH key to GitHub:** + + ```bash + # Copy your public key + cat ~/.ssh/id_ed25519.pub # or id_rsa.pub + + # Go to https://github.com/settings/keys + # Click "New SSH key" and paste + ``` + +4. **Ensure ssh-agent has your key:** + + ```bash + # On HOST machine + ssh-add -l + + # If empty or shows "Could not open connection" + eval "$(ssh-agent -s)" + ssh-add ~/.ssh/id_ed25519 # or id_rsa + ``` + +See [Getting Started - SSH Setup](./getting-started.md#4-configure-ssh-keys-recommended) for detailed instructions. + +### SSH Works on Host But Not in Container + +**Symptoms:** + +- Can clone/push from host machine +- Same operations fail inside devcontainer +- "Permission denied" or asks for password + +**Root Cause:** +SSH agent forwarding isn't working properly. + +**Solutions:** + +1. **Verify agent forwarding requirements:** + + ```bash + # On HOST machine (before opening container) + # SSH agent must be running + echo $SSH_AUTH_SOCK + # Should show a path, not empty + + # Agent must have keys loaded + ssh-add -l + # Should list your SSH keys + ``` + +2. **Add keys to agent if missing:** + + ```bash + # On HOST machine + ssh-add ~/.ssh/id_ed25519 # or id_rsa + + # Verify + ssh-add -l + ``` + +3. **Restart VS Code and rebuild container:** + + - Close VS Code completely + - Restart VS Code + - Command Palette → "Dev Containers: Rebuild Container" + +4. **Check SSH config (macOS):** + + ```bash + # On HOST machine + # Add to ~/.ssh/config + Host * + AddKeysToAgent yes + UseKeychain yes + IdentityFile ~/.ssh/id_ed25519 + ``` + +5. **Start ssh-agent automatically (Linux):** + + ```bash + # Add to ~/.bashrc or ~/.zshrc on HOST + if [ -z "$SSH_AUTH_SOCK" ]; then + eval "$(ssh-agent -s)" + ssh-add ~/.ssh/id_ed25519 + fi + ``` + +6. **Windows: Ensure ssh-agent service is running:** + + ```powershell + # In PowerShell as Administrator (on HOST) + Get-Service ssh-agent | Set-Service -StartupType Automatic + Start-Service ssh-agent + + # Then add your key + ssh-add $env:USERPROFILE\.ssh\id_ed25519 + ``` + +### Git Push Asks for Username/Password + +**Symptoms:** + +``` +Username for 'https://github.com': +Password for 'https://user@github.com': +``` + +**Causes:** + +1. Repository was cloned with HTTPS instead of SSH +2. SSH agent forwarding not working + +**Solutions:** + +**Option 1: Switch to SSH** (recommended): + +```bash +# Check current remote URL +git remote -v + +# If using HTTPS, switch to SSH +git remote set-url origin + +# Verify +git remote -v +``` + +**Option 2: Use Personal Access Token** (for HTTPS): + +```bash +# Generate token at https://github.com/settings/tokens +# Use token as password when prompted + +# Or configure credential helper +git config --global credential.helper store +# Next time you enter credentials, they'll be saved +``` + +**Option 3: Fix SSH agent forwarding**: +See "SSH Works on Host But Not in Container" section above. + +### Multiple SSH Keys (Personal + Work) + +**Problem:** Have multiple GitHub accounts or SSH keys + +**Solution:** Use SSH config to manage multiple keys: + +```bash +# On HOST machine, edit ~/.ssh/config +Host github.com-work + HostName github.com + User git + IdentityFile ~/.ssh/id_ed25519_work + +Host github.com-personal + HostName github.com + User git + IdentityFile ~/.ssh/id_ed25519_personal + +# Add both keys to agent +ssh-add ~/.ssh/id_ed25519_work +ssh-add ~/.ssh/id_ed25519_personal + +# Clone using specific host alias +git clone git@github.com-work: +``` + +### Cannot Sign Commits with GPG + +**Symptoms:** + +``` +error: gpg failed to sign the data +fatal: failed to write commit object +``` + +**Solution:** + +GPG signing requires additional setup in devcontainers. + +**Use SSH signing** (GitHub now supports this): + +```bash +# Configure git to use SSH for signing +git config --global gpg.format ssh +git config --global user.signingkey ~/.ssh/id_ed25519.pub +git config --global commit.gpgsign true +``` + +## Build System Issues + +### Bazel Fails with "Server terminated abruptly" + +**Symptoms:** + +``` +ERROR: Bazel server terminated abruptly +``` + +**Solutions:** + +1. **Clean Bazel cache:** + + ```bash + bazel clean --expunge + ``` + +2. **Check disk space:** + + ```bash + df -h + ``` + +3. **Restart container:** + - Command Palette → "Dev Containers: Rebuild Container" + +### Bazel Build Fails with Toolchain Errors + +**Symptoms:** + +``` +ERROR: No matching toolchains found +ERROR: Cannot find compiler +``` + +**Solutions:** + +1. **Verify toolchain installation:** + + ```bash + ls -la /opt/mongodbtoolchain/revisions/ + + # Check compiler + /opt/mongodbtoolchain/v5/bin/gcc --version + ``` + +2. **Source toolchain environment:** + + ```bash + source /opt/mongodbtoolchain/revisions/*/activate + ``` + +3. **Rebuild container** to reinstall toolchain + +### EngFlow Authentication Fails + +**Symptoms:** + +``` +ERROR: Failed to authenticate with EngFlow +ERROR: Build Event Service upload failed +``` + +**Solutions:** + +1. **Check if credentials exist:** + + ```bash + ls -la ~/.config/engflow_auth/ + ``` + +2. **Re-authenticate with EngFlow:** + + ```bash + rm -r ~/.config/engflow_auth/* + bazel run engflow_auth + ``` + +3. **Build without EngFlow:** + ```bash + bazel build --config=local install-mongod + ``` + +## Python Environment Issues + +### Poetry Install Fails + +**Symptoms:** + +``` +ERROR: Failed to install packages +KeyringError: ... +``` + +**Solutions:** + +1. **Set keyring backend:** + + ```bash + export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring + poetry install --no-root --sync + ``` + +2. **Clear Poetry cache:** + + ```bash + poetry cache clear --all pypi + poetry install --no-root --sync + ``` + +3. **Verify Poetry version:** + ```bash + poetry --version + # Should be version specified in poetry_requirements.txt + ``` + +### Virtual Environment Not Activating + +**Symptoms:** + +- `(python3-venv)` not in prompt +- `which python` shows system Python + +**Solutions:** + +1. **Manually activate:** + + ```bash + source python3-venv/bin/activate + ``` + +2. **Check shell config:** + + ```bash + cat ~/.bashrc | grep python3-venv + cat ~/.zshrc | grep python3-venv + ``` + +3. **Re-source config:** + ```bash + source ~/.bashrc # or ~/.zshrc + ``` + +### Import Errors in Python Scripts + +**Symptoms:** + +``` +ModuleNotFoundError: No module named 'pymongo' +``` + +**Solutions:** + +1. **Ensure venv is activated:** + + ```bash + which python + # Should show: /workspaces/mongo/python3-venv/bin/python + ``` + +2. **Reinstall dependencies:** + + ```bash + source python3-venv/bin/activate + poetry install --no-root --sync + ``` + +3. **Check Poetry lock file:** + ```bash + poetry check + poetry lock --check + ``` + +## Volume and Persistence Issues + +### Data Lost After Container Restart + +**Symptoms:** + +- Bazel cache gone +- History cleared +- Python venv empty + +**Root Cause:** +Volumes not mounting correctly + +**Solutions:** + +1. **Check volumes are mounted:** + + ```bash + docker inspect | grep -A 10 Mounts + ``` + +2. **Verify volumes exist:** + + ```bash + docker volume ls | grep mongo + ``` + +3. **Check devcontainer.json mounts:** + ```json + "mounts": [ + { + "source": "mongo-cache", + "target": "/home/youruser/.cache", + "type": "volume" + } + ] + ``` + +### Cannot Access Files from Host + +**Symptoms:** + +- Can't open files in host OS +- Need to copy files out of container + +**Solution:** + +Files in named volumes are in Docker's VM, not directly accessible. + +**To access:** + +```bash +# Copy file from container to host +docker cp :/workspaces/mongo/file.txt ~/Downloads/ + +# Or use VS Code +# Right-click file → Download... +``` + +**To edit with external tools:** +Use bind mounts instead of named volumes (but sacrifices performance). + +### Volume Fills Up Disk + +**Symptoms:** + +```bash +docker system df +# Shows huge SIZE for volumes +``` + +**Solutions:** + +1. **Clean Bazel cache:** + + ```bash + # Inside container + bazel clean --expunge + ``` + +2. **Remove old volumes:** + + ```bash + # List volumes + docker volume ls + + # Remove specific volume if needed (WARNING: loses data!) + docker volume rm old-cache-volume + ``` + +3. **Limit Bazel cache size:** + ```bash + # Add to ~/.bazelrc + echo "build --disk_cache=~/.cache/bazel --disk_cache_size=10G" >> ~/.bazelrc + ``` + +## Platform-Specific Issues + +### macOS: "Docker Desktop Is Not Running" + +**Solutions:** + +1. **Start Docker Desktop/Rancher Desktop:** + + - Check menu bar for Docker icon + - Launch the application + +2. **Reset Docker:** + + - Rancher Desktop → Troubleshooting → Reset Kubernetes + - Docker Desktop → Troubleshoot → Reset to factory defaults + +3. **Check Docker context:** + ```bash + docker context ls + docker context use default + ``` + +### macOS: M1/M2 ARM Issues + +**Symptoms:** + +- "exec format error" +- Build fails with architecture mismatch + +**Solutions:** + +1. **Verify base image supports ARM:** + + ```bash + docker pull quay.io/mongodb/bazel-remote-execution:ubuntu24-... + docker inspect --format='{{.Architecture}}' + ``` + +2. **Use platform flag if needed:** + + ```dockerfile + FROM --platform=linux/amd64 + ``` + +3. **Check Rosetta 2 is enabled** (Rancher Desktop) + +### Windows: WSL2 Integration Issues + +**Symptoms:** + +- Container won't start on Windows +- File permission errors + +**Solutions:** + +1. **Enable WSL2 integration:** + + - Docker Desktop → Settings → Resources → WSL Integration + - Enable integration for your WSL distro + +2. **Use WSL2 terminal:** + + - Open Ubuntu (or other WSL distro) + - Clone and work from WSL filesystem, not `/mnt/c/` + +3. **Check WSL version:** + ```bash + wsl --list --verbose + # Should show VERSION 2 + ``` + +### Linux: Permission Denied Errors + +**Symptoms:** + +``` +permission denied while trying to connect to Docker daemon +``` + +**Solutions:** + +1. **Add user to docker group:** + + ```bash + sudo usermod -aG docker $USER + newgrp docker # Or logout/login + ``` + +2. **Check Docker socket permissions:** + ```bash + ls -l /var/run/docker.sock + sudo chmod 666 /var/run/docker.sock # Temporary + ``` + +## Docker Provider Issues + +### Rancher Desktop: Container Engine Not dockerd + +**Symptoms:** + +- Cannot build devcontainer +- Unexpected behavior + +**Solution:** + +- Rancher Desktop → Preferences → Container Engine +- Select "dockerd (moby)" +- Restart Rancher Desktop + +### Docker Desktop: Resource Limits Too Low + +**Symptoms:** + +- Slow builds +- Out of memory errors + +**Solution:** +Go to Docker Desktop → Settings → Resources and allocate generously: + +- **CPUs**: Allocate as many as possible (leave 1-2 for host OS) +- **Memory**: Allocate as much as possible (leave ~4-8 GB for host OS) +- **Swap**: Optional but can help (2-4 GB if you have disk space) +- **Disk**: Ensure plenty available (60+ GB recommended) + +> **Note:** MongoDB builds are resource-intensive. More resources = significantly faster builds. + +### OrbStack: Features Not Working + +**Symptoms:** + +- Docker-outside-of-docker doesn't work +- Volume mounts fail + +**Solution:** +OrbStack has some limitations with devcontainer features. Try: + +1. Update to latest OrbStack version +2. Check OrbStack documentation for devcontainer compatibility +3. Consider switching to Rancher Desktop for full feature support + +## Debugging Tips + +### Enable Verbose Logging + +**VS Code Dev Container logs:** + +1. Command Palette → "Dev Containers: Show Container Log" +2. Check for errors during build/start + +**Docker logs:** + +```bash +# Container logs +docker logs + +# Follow logs in real-time +docker logs -f +``` + +**Bazel verbose:** + +```bash +bazel build --verbose_failures --sandbox_debug install-mongod +``` + +### Inspect Running Container + +```bash +# Get container ID +docker ps + +# Exec into container +docker exec -it /bin/bash + +# Check processes +docker exec ps aux + +# Check environment +docker exec env +``` + +### Check Resource Usage + +```bash +# Inside container +df -h # Disk usage +free -h # Memory +top # CPU/Memory by process + +# From host +docker stats # Live resource usage +``` + +### Rebuild from Scratch + +Sometimes the best fix is a clean rebuild: + +```bash +# Stop and remove container +docker stop +docker rm + +# Rebuild without cache +# Command Palette → "Dev Containers: Rebuild Container Without Cache" +``` + +### Test Outside Devcontainer + +To isolate whether an issue is devcontainer-specific: + +```bash +# Clone locally +git clone git@github.com:mongodb/mongo.git +cd mongo + +# Try building without devcontainer +# (Requires local toolchain setup) +``` + +## Getting More Help + +If your issue isn't covered here: + +1. **Check VS Code Docs**: [code.visualstudio.com/docs/devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) +2. **Search Issues**: MongoDB GitHub repository issues +3. **Ask the Team**: MongoDB developers Slack/chat +4. **File a Bug**: Include: + - Error messages + - Container logs + - Steps to reproduce + - OS and Docker version + - devcontainer.json and Dockerfile (if modified) + +--- + +**See Also:** + +- [Architecture](./architecture.md) - Understand how things work +- [Advanced Usage](./advanced.md) - Customize your setup +- [FAQ](./faq.md) - Common questions