SERVER-113246: Add separate doc around devcontainer customization (#43613)
GitOrigin-RevId: f79032fd535184ed6f36a1b8fd16c4f5bb9c765a
This commit is contained in:
Eric Lavigne
MongoDB Bot
parent
040814f025
commit
ba32b22187
@ -15,6 +15,13 @@ This is the comprehensive guide for developing MongoDB using Dev Containers. Cho
|
||||
- First-time configuration
|
||||
- Verifying your setup
|
||||
|
||||
### 🎨 [Customization](./customization.md)
|
||||
|
||||
**Personal customizations without modifying the devcontainer setup**
|
||||
|
||||
- Persistent dotfiles
|
||||
- Always-installed features
|
||||
|
||||
### 🏗️ [Architecture & Technical Details](./architecture.md)
|
||||
|
||||
**Understand how the devcontainer works under the hood**
|
||||
@ -38,14 +45,12 @@ This is the comprehensive guide for developing MongoDB using Dev Containers. Cho
|
||||
|
||||
### 💡 [Advanced Usage](./advanced.md)
|
||||
|
||||
**Power user features and customization**
|
||||
**Power user workflows and complex scenarios**
|
||||
|
||||
- Customizing your devcontainer
|
||||
- Working with multiple containers
|
||||
- Remote execution with EngFlow
|
||||
- Custom toolchain versions
|
||||
- Integration with CI/CD
|
||||
- Extending with additional features
|
||||
- Backup and migration strategies
|
||||
- Development workflows and debugging
|
||||
- EngFlow telemetry integration
|
||||
|
||||
### ❓ [FAQ](./faq.md)
|
||||
|
||||
|
||||
@ -1,27 +1,15 @@
|
||||
# Advanced Dev Container Usage
|
||||
|
||||
This guide covers advanced topics for power users who want to customize and extend their devcontainer setup.
|
||||
This guide covers advanced workflows and power user features for managing multiple containers, backups, and complex development scenarios.
|
||||
|
||||
**Looking to customize your devcontainer?** See the [Customization Guide](./customization.md) for dotfiles, VS Code settings, extensions, and performance tuning.
|
||||
|
||||
## 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
|
||||
@ -60,176 +48,6 @@ 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
|
||||
@ -331,6 +149,7 @@ du -sh /opt/mongodbtoolchain/*
|
||||
|
||||
**See Also:**
|
||||
|
||||
- [Customization](./customization.md) - Personalize your devcontainer
|
||||
- [Architecture](./architecture.md) - How it all works
|
||||
- [Troubleshooting](./troubleshooting.md) - Fix issues
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
|
||||
111
docs/devcontainer/customization.md
Normal file
111
docs/devcontainer/customization.md
Normal file
@ -0,0 +1,111 @@
|
||||
# Customizing Your Dev Container
|
||||
|
||||
This guide covers personal customizations you can make to your MongoDB devcontainer **without modifying the repository's devcontainer configuration**. These are user-level settings that only affect your development environment.
|
||||
|
||||
**Want to modify the devcontainer setup for everyone?** See [Contributing Customizations](#contributing-customizations) at the bottom.
|
||||
|
||||
**For general VS Code settings** (themes, fonts, keybindings), see the [VS Code documentation](https://code.visualstudio.com/docs/getstarted/settings).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Persistent Dotfiles](#persistent-dotfiles)
|
||||
- [Always-Installed Features](#always-installed-features)
|
||||
- [Contributing Customizations](#contributing-customizations)
|
||||
|
||||
## Persistent Dotfiles
|
||||
|
||||
VS Code supports automatically cloning and applying your dotfiles when creating a devcontainer.
|
||||
|
||||
[Learn more about personalizing with dotfiles →](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories)
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Create a dotfiles repository (e.g., `github.com/yourusername/dotfiles`)
|
||||
2. Add your configuration files (`.bashrc`, `.gitconfig`, `.vimrc`, etc.)
|
||||
3. Configure VS Code to use your dotfiles:
|
||||
|
||||
```json
|
||||
// In your user settings.json
|
||||
{
|
||||
"dotfiles.repository": "yourusername/dotfiles",
|
||||
"dotfiles.targetPath": "~/dotfiles",
|
||||
"dotfiles.installCommand": "install.sh"
|
||||
}
|
||||
```
|
||||
|
||||
**Example dotfiles structure:**
|
||||
|
||||
```
|
||||
dotfiles/
|
||||
├── .bashrc
|
||||
├── .gitconfig
|
||||
├── .vimrc
|
||||
├── .bash_aliases
|
||||
└── install.sh
|
||||
```
|
||||
|
||||
**Example `install.sh`:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
ln -sf ~/dotfiles/.bashrc ~/.bashrc
|
||||
ln -sf ~/dotfiles/.gitconfig ~/.gitconfig
|
||||
ln -sf ~/dotfiles/.vimrc ~/.vimrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
## Always-Installed Features
|
||||
|
||||
You can configure VS Code to always install certain features in all your devcontainers.
|
||||
|
||||
[Learn more about always-installed features →](https://code.visualstudio.com/docs/devcontainers/containers#_always-installed-features)
|
||||
|
||||
```json
|
||||
// In your user settings.json
|
||||
{
|
||||
"dev.containers.defaultFeatures": {
|
||||
"ghcr.io/devcontainers/features/git:1": {},
|
||||
"ghcr.io/devcontainers/features/github-cli:1": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This applies to all devcontainers you work with, not just MongoDB.
|
||||
|
||||
**Browse available features:** [https://containers.dev/features](https://containers.dev/features)
|
||||
|
||||
## Contributing Customizations
|
||||
|
||||
The customizations above are all user-level and don't require changes to the repository. If you want to modify the devcontainer setup itself to benefit all MongoDB developers, you'll need to submit a PR.
|
||||
|
||||
**Examples of repository-level customizations:**
|
||||
|
||||
- Adding new devcontainer features (tools, languages, etc.)
|
||||
- Configuring default port forwarding
|
||||
- Adding environment variables for all developers
|
||||
- Setting up bind mounts to host directories
|
||||
- Modifying container lifecycle hooks
|
||||
- Improving build performance or caching
|
||||
|
||||
**How to contribute:**
|
||||
|
||||
1. Make your changes to `.devcontainer/devcontainer.json` or related files
|
||||
2. Test thoroughly - rebuild your container and verify everything works
|
||||
3. Document your changes clearly in your PR description
|
||||
4. Update relevant documentation (like this guide)
|
||||
5. Submit a PR to the main repository
|
||||
|
||||
**Related documentation:**
|
||||
|
||||
- [Architecture Guide](./architecture.md) - Understand the devcontainer setup before modifying it
|
||||
- [VS Code devcontainer.json reference](https://code.visualstudio.com/docs/devcontainers/containers#_devcontainerjson-reference)
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
|
||||
- [Getting Started](./getting-started.md) - Initial setup
|
||||
- [Architecture](./architecture.md) - How devcontainers work
|
||||
- [Advanced Usage](./advanced.md) - Multiple containers, backups, workflows
|
||||
- [Troubleshooting](./troubleshooting.md) - Fix issues
|
||||
- [VS Code Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers) - General VS Code features
|
||||
Loading…
Reference in New Issue
Block a user