mirror of https://github.com/mongodb/mongo
SERVER-111809: Add more detailed documentation for dev containers (#42380)
GitOrigin-RevId: 7735060dbb806d0a7dbf51fb32bfc3fd2c7248d1
This commit is contained in:
Eric Lavigne
MongoDB Bot
parent
fef8ec2e64
commit
0ea88c017e
|
|
@ -56,6 +56,9 @@ USER $USERNAME
|
||||||
ENV USER=${USERNAME}
|
ENV USER=${USERNAME}
|
||||||
RUN /opt/mongodbtoolchain/revisions/*/scripts/install.sh; echo "Toolchain installation complete"
|
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
|
# Bazel telemetry
|
||||||
RUN echo "common --bes_keywords=devcontainer:use=true" >> "$HOME/.bazelrc" && \
|
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:image=$BASE_IMAGE" >> "$HOME/.bazelrc" && \
|
||||||
|
|
|
||||||
|
|
@ -19,7 +19,7 @@
|
||||||
"type": "volume"
|
"type": "volume"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"source": "projectname-bashhistory",
|
"source": "mongo-bashhistory",
|
||||||
"target": "/commandhistory",
|
"target": "/commandhistory",
|
||||||
"type": "volume"
|
"type": "volume"
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -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/**/change_streams.md @10gen/query-execution-change-streams @svc-auto-approve-bot
|
||||||
/docs/**/cpp_style.md @10gen/server-programmability @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-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/**/exception_architecture.md @10gen/server-programmability @svc-auto-approve-bot
|
||||||
/docs/**/golden_data_test_framework.md @10gen/query-optimization @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
|
/docs/**/idl.md @10gen/server-programmability @svc-auto-approve-bot
|
||||||
|
|
|
||||||
|
|
@ -12,6 +12,9 @@ filters:
|
||||||
- "devcontainer-setup.md":
|
- "devcontainer-setup.md":
|
||||||
approvers:
|
approvers:
|
||||||
- 10gen/devprod-correctness
|
- 10gen/devprod-correctness
|
||||||
|
- "devcontainer/**":
|
||||||
|
approvers:
|
||||||
|
- 10gen/devprod-correctness
|
||||||
- "exception_architecture.md":
|
- "exception_architecture.md":
|
||||||
approvers:
|
approvers:
|
||||||
- 10gen/server-programmability
|
- 10gen/server-programmability
|
||||||
|
|
|
||||||
|
|
@ -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
|
- 📖 [**Getting Started Guide**](./devcontainer/getting-started.md) - Step-by-step setup instructions
|
||||||
|
- 🏗️ [**Architecture & Technical Details**](./devcontainer/architecture.md) - How everything works under the hood
|
||||||
### Install Docker
|
- 🔧 [**Troubleshooting Guide**](./devcontainer/troubleshooting.md) - Solutions to common issues
|
||||||
|
- 💡 [**Advanced Usage**](./devcontainer/advanced.md) - Customization and power user features
|
||||||
Devcontainers requires Docker to be installed and running on your system, some examples of docker providers are:
|
- ❓ [**FAQ**](./devcontainer/faq.md) - Frequently asked questions
|
||||||
|
|
||||||
- [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)
|
|
||||||
|
|
|
||||||
|
|
@ -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)
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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)
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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)
|
||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue