12 KiB

Raw Blame History

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 is our recommended Docker provider for devcontainer development.

Installation:

Download and install Rancher Desktop from rancherdesktop.io
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:

Open Rancher Desktop → Preferences → Virtual Machine
Memory: Allocate as much as your system allows (leave ~4-8 GB for your host OS)
CPUs: Allocate as many cores as possible (leave 1-2 for your host OS)
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 is a popular alternative.

Installation:

Download from docker.com/products/docker-desktop
Install and start Docker Desktop
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 is a lightweight, fast Docker alternative for macOS.

Installation:

Download from orbstack.dev
Install and launch OrbStack
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

2. Install Visual Studio Code

Download and install VS Code from code.visualstudio.com

3. Install Dev Containers Extension

Open VS Code
Go to Extensions (⌘/Ctrl+Shift+X)
Search for "Dev Containers"
Install the Dev 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

# 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:

# 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

Copy your public key:

# For ED25519
cat ~/.ssh/id_ed25519.pub

# For RSA
cat ~/.ssh/id_rsa.pub

Add to GitHub:
- Go to GitHub SSH Settings
- Click "New SSH key"
- Paste your public key
- Give it a descriptive title (e.g., "Work Laptop")
- Click "Add SSH key"

Test your connection:

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:

# 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:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519 2>/dev/null

Windows users: The ssh-agent service should start automatically. If not:

# 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 →

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:

Open VS Code Command Palette
- macOS: Cmd+Shift+P
- Windows/Linux: Ctrl+Shift+P
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 →
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
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
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:

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

# 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:

# 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:

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:

engflow_auth → ~/.config/engflow_auth
- EngFlow remote execution credentials
- Survives container rebuilds
mongo-cache → ~/.cache
- Bazel cache
- Tool caches
- Significantly speeds up rebuilds
mongo-python3-venv → /workspaces/mongo/python3-venv
- Python virtual environment
- Poetry-managed dependencies
- Persists across container updates
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 - Learn how the devcontainer works
Advanced Usage - Customize and extend your setup
Troubleshooting - Fix common issues

Common First-Time Issues

SSH Clone Fails

Problem: Clone fails with "Permission denied (publickey)" or "git@github.com: Permission denied"

Solution:

# 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:

# 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 →

Container Build Fails

Problem: Docker build fails with "no space left on device"

Solution:

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

Python Virtual Environment Not Activated

Problem: Python commands not found or using wrong version

Solution:

# 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:

# 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):

Clone the repository to your local machine:

git clone git@github.com:mongodb/mongo.git
cd mongo

Open in VS Code:
```
code .
```
Open Command Palette (Cmd/Ctrl+Shift+P)
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
Issues: Check Troubleshooting Guide
Bug Reports: Open an issue in the MongoDB repository

Next: Learn about the Architecture →

12 KiB Raw Blame History

Getting Started with MongoDB Dev Containers

Prerequisites

1. Install Docker

Option A: Rancher Desktop (Recommended)

Option B: Docker Desktop

Option C: OrbStack (macOS)

Option D: Docker Engine (Linux only)

2. Install Visual Studio Code

3. Install Dev Containers Extension

4. Configure SSH Keys (Recommended)

Check if you have SSH keys

Generate SSH keys (if needed)

Add SSH key to GitHub

SSH Agent (for keys with passphrases)

Setup Instructions

Step 1: Clone Repository in Named Container Volume

Why Named Volumes?

Cloning Steps:

Step 2: Complete Git History (Recommended)

Step 3: Verify Your Setup

3.1 Check Toolchain Installation

3.2 Verify Python Virtual Environment

3.3 Test Bazel Build

3.4 Check VS Code Extensions

Step 4: Understanding Your Environment

Workspace Location

Persistent Volumes

Data Directory

Next Steps

Explore the Documentation

Common First-Time Issues

SSH Clone Fails

SSH Works Locally But Not in Container

Container Build Fails

Slow Performance on macOS

Python Virtual Environment Not Activated

VS Code Extensions Not Working

Alternative Setup: Local Clone + Reopen in Container

Getting Help

12 KiB

Raw Blame History