docs/devcontainer/faq.md
Frequently asked questions about MongoDB development with dev containers.
A dev container (development container) is a Docker container configured specifically for development. It includes:
Think of it as a portable, reproducible development environment that runs on any machine with Docker.
Learn more about dev containers →
The MongoDB devcontainer is currently in Beta. This means:
Report issues to help improve it for everyone!
No, but SSH is recommended for contributors who will be pushing code.
You can use:
[email protected]:10gen/mongo.git
https://github.com/mongodb/mongo.git
See the Getting Started guide SSH setup section for details.
VS Code automatically forwards your SSH agent to the container, so you don't need to copy keys into the container.
Requirements:
~/.ssh/)Verify on host before opening container:
# Check ssh-agent has your keys
ssh-add -l
# Test GitHub connection
ssh -T [email protected]
Inside the container, Git commands will automatically use your host's SSH keys through agent forwarding.
Learn more about SSH agent forwarding →
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"
Recommended: Rancher Desktop
Alternatives:
See Getting Started for details.
First-time setup includes:
Total: ~20-30 minutes depending on internet speed
Subsequent rebuilds are much faster due to Docker layer caching.
Yes! Requirements:
Important: Clone repository in WSL2 filesystem (not /mnt/c/), not Windows filesystem, for best performance.
Yes! The devcontainer supports ARM64 architecture. Ensure:
Your code lives in a Docker volume, not your local filesystem.
/workspaces/mongodocker volume inspect <volume_name>)This is by design for performance, especially on macOS.
Option 1: Copy files out
docker cp <container_id>:/workspaces/mongo/file.txt ~/Downloads/
Option 2: Download from VS Code
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.
Yes, but not recommended for best performance.
Option A: Reopen in container (bind mount - slower)
Option B: Clone into volume (recommended - faster)
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.
Yes! Clone the repository multiple times with different volume names:
mongo-main (main branch)mongo-feature (feature branch)mongo-review (PR review)Each runs independently with its own cache and environment.
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.
Yes! Data in volumes persists:
What doesn't persist:
apt-get (unless in Dockerfile)/tmpVolumes are preserved, so you won't lose:
Just reopen the container and everything is back.
See Advanced Usage - Debugging Workflow
First build downloads and compiles everything:
First build: 30-60 minutes
Incremental builds: 1-5 minutes
To speed up:
Automatic (on save):
Manual:
# Format all files
bazel run format
It's automatic! The devcontainer:
compile_commands.json during setupIf not working:
# Rebuild compile database
bazel build compiledb --config=local
# Restart clangd
# Command Palette → "clangd: Restart language server"
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).
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
Reload window:
Reinstall extension:
Check it's a container extension:
Verify toolchain:
ls -la /opt/mongodbtoolchain/revisions/
gcc --version # Should show the MongoDB toolchain GCC version
Rebuild container:
Check credentials:
ls -la ~/.config/engflow_auth/
Re-authenticate: Contact MongoDB team for authentication flow.
Build locally instead:
bazel build --config=local install-mongod
Check Docker is running:
docker info
docker ps
View logs:
docker logs <container_id>Rebuild from scratch:
Allocate as much disk space as you can comfortably spare. We recommend at least 60GB
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.
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.
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.
docker stats # Live resource usage
Inside container:
htop # If installed
top # Always available
df -h # Disk usage
Yes! See Advanced Usage for:
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.