mirror
/
mongo
mirror of https://github.com/mongodb/mongo
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SERVER-111809: Add more detailed documentation for dev containers (#42380) 

GitOrigin-RevId: 7735060dbb806d0a7dbf51fb32bfc3fd2c7248d1
This commit is contained in:
Eric Lavigne 2025-10-09 12:27:05 -06:00 committed by MongoDB Bot
parent fef8ec2e64
commit 0ea88c017e
11 changed files with 3104 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.devcontainer/Dockerfile
View File

@ -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" && \

2
.devcontainer/devcontainer.json
View File

@ -19,7 +19,7 @@
"type": "volume"
},
{
"source": "projectname-bashhistory",
"source": "mongo-bashhistory",
"target": "/commandhistory",
"type": "volume"
}

1
.github/CODEOWNERS vendored
View File

@ -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

3
docs/OWNERS.yml
View File

@ -12,6 +12,9 @@ filters:
- "devcontainer-setup.md":
approvers:
- 10gen/devprod-correctness
- "devcontainer/**":
approvers:
- 10gen/devprod-correctness
- "exception_architecture.md":
approvers:
- 10gen/server-programmability

92
docs/devcontainer-setup.md
View File

@ -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

114
docs/devcontainer/README.md Normal file
View File

@ -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)

336
docs/devcontainer/advanced.md Normal file
View File

@ -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=<image_tag>
common --bes_keywords=devcontainer:docker_server_platform=<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 <image_id>
# 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 <container_name> /bin/bash
# Copy compile_commands.json to host (for external IDE)
docker cp <container_id>:/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

563
docs/devcontainer/architecture.md Normal file
View File

@ -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<br/>- engflow<br/>- cache<br/>- venv<br/>- history"]
BaseImage["Base Image<br/>(Bazel RBE Ubuntu)"]
Toolchain["MongoDB Toolchain<br/>(GCC, Clang, etc.)"]
Features["Features<br/>- workstation<br/>- git<br/>- bazel<br/>- docker"]
PostCreate["Post-Create Commands<br/>- setup poetry<br/>- setup venv<br/>- 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-<version>
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="<sha256 checksum>"
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="<sha256 checksum>"
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)

502
docs/devcontainer/faq.md Normal file
View File

@ -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 <volume_name>`)
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 <container_id>:/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 <container_id>`
**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

469
docs/devcontainer/getting-started.md Normal file
View File

@ -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)

1104
docs/devcontainer/troubleshooting.md Normal file
View File

File diff suppressed because it is too large Load Diff