12 KiB

Raw Blame History

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 →

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

SSH keys must be on your host machine (not in container)
SSH agent must be running with keys loaded
Keys should be in default location (~/.ssh/)

Verify on host before opening container:

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

Why does git push ask for credentials in the container?

This usually means SSH agent forwarding isn't working.

Fix:

# 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 for details.

Why does the setup take so long?

First-time setup includes:

Downloading base image (~2 GB)
Building custom container (~5-10 min)
Downloading toolchain (~3 GB)
Installing Python dependencies (~5-10 min)
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

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)

Open your local repo in VS Code
Command Palette → "Dev Containers: Reopen in Container"

Option B: Clone into volume (recommended - faster)

Use "Clone Repository in Named Container Volume"
Delete local clone or keep for reference

How do I switch between branches?

Same as normal Git:

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:

Container 1: mongo-main (main branch)
Container 2: mongo-feature (feature branch)
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:

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

How do I debug code?

See Advanced Usage - 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:

# Format all files
bazel run format

How do I use clangd for IntelliSense?

It's automatic! The devcontainer:

Builds compile_commands.json during setup
Configures VS Code to use clangd
Disables Microsoft C++ extension

If not working:

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

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

Python packages are missing

Activate the virtual environment:

source python3-venv/bin/activate

# Should show (python3-venv) in prompt
which python
# Should show: /workspaces/mongo/python3-venv/bin/python

Reinstall packages:

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:

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:

ls -la ~/.config/engflow_auth/

Re-authenticate: Contact MongoDB team for authentication flow.

Build locally instead:

bazel build --config=local install-mongod

The container won't start

Check Docker is running:

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:

bazel build --jobs=N  # Replace N with fewer parallel jobs

Limit memory:

bazel build --local_ram_resources=HOST_RAM*0.5  # Use only 50% of available RAM

Clear cache periodically:

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?

docker stats  # Live resource usage

Inside container:

htop   # If installed
top    # Always available
df -h  # Disk usage

Advanced Topics

Can I customize the container?

Yes! See Advanced Usage 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:

# 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
Architecture Details: architecture.md
Troubleshooting: troubleshooting.md
Advanced Topics: advanced.md
VS Code Docs: code.visualstudio.com/docs/devcontainers

Who do I contact for help?

Documentation: Check this guide first
Search Issues: Jira issues
Internal Teams: #server-local-dev channel in Slack (for employees)
File Bug: Create Jira issue with details

12 KiB Raw Blame History