Skip to content

Commit c0a1cfd

Browse files
simonkurtz-MSFTsimonkurtz-MSFT
committed
Add README
1 parent 68797bd commit c0a1cfd

File tree

1 file changed

+222
-0
lines changed

1 file changed

+222
-0
lines changed

‎.devcontainer/README.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# APIM Samples Dev Container Setup
2+
3+
This directory contains the optimized dev container configuration for the Azure API Management (APIM) Samples project. The setup is designed for fast startup times through prebuild optimization while maintaining a robust development environment.
4+
5+
## 📋 Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Files in this Directory](#files-in-this-directory)
9+
- [Setup Stages](#setup-stages)
10+
- [Optimization Strategy](#optimization-strategy)
11+
- [Jupyter Kernel Configuration](#jupyter-kernel-configuration)
12+
- [Troubleshooting](#troubleshooting)
13+
- [Performance Notes](#performance-notes)
14+
15+
## 🎯 Overview
16+
17+
The dev container uses a **three-stage optimization approach** to minimize startup time:
18+
19+
1. **Build Stage** (Dockerfile): Base system setup and Azure CLI configuration
20+
2. **Prebuild Stage** (devcontainer.json): Heavy installations and environment setup
21+
3. **Runtime Stage** (post-start-setup.sh): Fast verification and user guidance
22+
23+
This approach ensures that time-consuming operations happen during container prebuild rather than every startup.
24+
25+
## 📁 Files in this Directory
26+
27+
### Core Configuration Files
28+
29+
| File | Purpose | Stage |
30+
|------|---------|-------|
31+
| `devcontainer.json` | Main dev container configuration | All |
32+
| `Dockerfile` | Container image definition | Build |
33+
| `post-start-setup.sh` | Runtime verification script | Runtime |
34+
| `README.md` | This documentation | - |
35+
36+
### Configuration Details
37+
38+
#### `devcontainer.json`
39+
- **Features**: Azure CLI, common utilities, Git, Docker-in-Docker
40+
- **Extensions**: Python, Jupyter, Bicep, GitHub Copilot, and more
41+
- **Lifecycle Commands**: Optimized three-stage setup
42+
- **Port Forwarding**: Common development ports (3000, 5000, 8000, 8080)
43+
44+
#### `Dockerfile`
45+
- **Base Image**: Microsoft's Python 3.12 dev container
46+
- **System Dependencies**: Essential packages and tools
47+
- **Azure CLI Setup**: Extensions and configuration for Codespaces
48+
- **Virtual Environment**: Auto-activation configuration
49+
50+
#### `post-start-setup.sh`
51+
- **Environment Verification**: Quick checks and status reporting
52+
- **Fallback Installation**: Safety net for missing components
53+
- **User Guidance**: Next steps and helpful information
54+
55+
## 🚀 Setup Stages
56+
57+
### Stage 1: Container Build (Dockerfile)
58+
**When it runs**: During initial container build
59+
**What it does**:
60+
- Installs Python 3.12 and system dependencies
61+
- Configures Azure CLI for Codespaces (device code authentication)
62+
- Installs Azure CLI extensions (`containerapp`, `front-door`)
63+
- Sets up shell auto-activation for virtual environment
64+
65+
### Stage 2: Content Update (devcontainer.json)
66+
**When it runs**: During prebuild when content changes
67+
**What it does**:
68+
- Creates Python virtual environment
69+
- Installs all Python packages from `requirements.txt`
70+
- Generates environment configuration (`.env` file)
71+
- Registers Jupyter kernel
72+
- Configures Azure CLI settings
73+
74+
### Stage 3: Runtime Verification (post-start-setup.sh)
75+
**When it runs**: Every time the container starts
76+
**What it does**:
77+
- Verifies environment setup (< 10 seconds)
78+
- Provides status reporting and user guidance
79+
- Performs fallback installation if needed
80+
- Displays next steps for the user
81+
82+
## ⚡ Optimization Strategy
83+
84+
### What Moved to Prebuild
85+
- ✅ Python package installation
86+
- ✅ Virtual environment creation
87+
- ✅ Azure CLI extension installation
88+
- ✅ Jupyter kernel registration
89+
- ✅ Environment file generation
90+
91+
### What Stays in Runtime
92+
- ✅ Environment verification
93+
- ✅ Status reporting and user guidance
94+
- ✅ Fallback installation (safety net)
95+
- ✅ Performance timing and completion messages
96+
97+
### Performance Benefits
98+
- **Faster Startup**: Most heavy operations happen during prebuild
99+
- **Better UX**: Users see verification instead of installation progress
100+
- **Reliability**: Fallback mechanisms ensure robustness
101+
- **Transparency**: Clear status reporting throughout
102+
103+
## 🔧 Jupyter Kernel Configuration
104+
105+
The dev container is configured with a custom Jupyter kernel for optimal Python development experience:
106+
107+
- **Kernel Name**: `apim-samples`
108+
- **Display Name**: "APIM Samples Python 3.12"
109+
- **Python Path**: `/workspaces/Apim-Samples/.venv/bin/python`
110+
111+
### Kernel Registration Details
112+
The kernel is automatically registered during the prebuild stage using:
113+
```bash
114+
python -m ipykernel install --user --name=apim-samples --display-name="APIM Samples Python 3.12"
115+
```
116+
117+
### VS Code Kernel Configuration
118+
The `devcontainer.json` includes specific Jupyter settings to ensure proper kernel selection:
119+
120+
```jsonc
121+
"jupyter.kernels.excludePythonEnvironments": [
122+
// Excludes system Python environments
123+
],
124+
"jupyter.kernels.trusted": [
125+
"/workspaces/Apim-Samples/.venv/bin/python"
126+
]
127+
```
128+
129+
For more details on kernel configuration in VS Code, see: [VS Code Issue #130946](https://github.com/microsoft/vscode/issues/130946#issuecomment-1899389049)
130+
131+
## 🛠️ Troubleshooting
132+
133+
### Common Issues and Solutions
134+
135+
#### Virtual Environment Not Found
136+
**Symptom**: Error about missing virtual environment
137+
**Solution**: The virtual environment should be created during prebuild. If missing:
138+
```bash
139+
python3.12 -m venv /workspaces/Apim-Samples/.venv
140+
source /workspaces/Apim-Samples/.venv/bin/activate
141+
pip install -r requirements.txt
142+
```
143+
144+
#### Azure CLI Extensions Missing
145+
**Symptom**: Commands fail with extension not found
146+
**Solution**: Extensions should install during prebuild. If missing:
147+
```bash
148+
az extension add --name containerapp
149+
az extension add --name front-door
150+
```
151+
152+
#### Jupyter Kernel Not Available
153+
**Symptom**: Kernel not visible in VS Code
154+
**Solution**: Re-register the kernel:
155+
```bash
156+
python -m ipykernel install --user --name=apim-samples --display-name="APIM Samples Python 3.12"
157+
```
158+
159+
#### Environment Variables Not Set
160+
**Symptom**: Import errors or path issues
161+
**Solution**: Regenerate the `.env` file:
162+
```bash
163+
python setup/setup_python_path.py --generate-env
164+
```
165+
166+
### Debug Commands
167+
Useful commands for troubleshooting:
168+
169+
```bash
170+
# Check Python environment
171+
which python
172+
python --version
173+
pip list
174+
175+
# Check virtual environment
176+
echo $VIRTUAL_ENV
177+
source /workspaces/Apim-Samples/.venv/bin/activate
178+
179+
# Check Azure CLI
180+
az --version
181+
az extension list
182+
183+
# Check Jupyter kernels
184+
jupyter kernelspec list
185+
186+
# Verify environment file
187+
cat .env
188+
```
189+
190+
## 📊 Performance Notes
191+
192+
### Typical Timing
193+
- **First Build**: ~5-10 minutes (includes all prebuild operations)
194+
- **Subsequent Startups**: ~10-30 seconds (verification only)
195+
- **Content Updates**: ~2-5 minutes (package updates during prebuild)
196+
197+
### Monitoring Setup Progress
198+
The post-start script provides real-time feedback:
199+
- **Terminal Output**: Keep the initial terminal open to see progress
200+
- **Status Messages**: Clear indicators for each verification step
201+
- **Error Handling**: Detailed messages for any issues encountered
202+
203+
### Best Practices
204+
1. **Keep Initial Terminal Open**: Shows verification progress and status
205+
2. **Wait for Completion**: Let the verification finish before starting work
206+
3. **Check Status Messages**: Review any warnings or errors reported
207+
4. **Use Fallback Commands**: If something fails, the script provides guidance
208+
209+
---
210+
211+
## 🤝 Contributing
212+
213+
When modifying the dev container setup:
214+
215+
1. **Test Thoroughly**: Verify changes work in both fresh and existing containers
216+
2. **Update Documentation**: Keep this README current with any changes
217+
3. **Consider Performance**: Evaluate whether new operations belong in prebuild or runtime
218+
4. **Maintain Fallbacks**: Ensure robust error handling and recovery options
219+
220+
---
221+
222+
*This dev container configuration is optimized for Azure API Management samples development with fast startup times and comprehensive tooling support.*

0 commit comments

Comments
 (0)