Skip to content

Commit 3a5c9a5

Browse files
cosmelabcosmelab
committed
Fix Codespaces: track devcontainer and use root user
1 parent 2190b4f commit 3a5c9a5

3 files changed

Lines changed: 221 additions & 1 deletion

File tree

‎.devcontainer/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Dev Container Configuration
2+
3+
This directory contains configuration for **VS Code Dev Containers** and **GitHub Codespaces**.
4+
5+
## What is This?
6+
7+
Dev Containers and Codespaces let you open this project **inside** the Docker container, so:
8+
- Your VS Code terminal runs directly in the container
9+
- No need to type `docker run` commands
10+
- All tools (BioPython, MAFFT, IQ-TREE) are immediately available
11+
- One-click setup
12+
13+
## Who Should Use This?
14+
15+
**For Beginners:**
16+
- Stick with the regular workflow (running `./tutorial.sh` and `./run-analysis.sh`)
17+
- You don't need Dev Containers or Codespaces to complete the assignment
18+
- **GitHub Codespaces** is great if you don't want to install Docker locally
19+
20+
**For Advanced Users:**
21+
- If you want to explore the container internals
22+
- If you want to modify Python scripts and test them immediately
23+
- If you're comfortable with Docker concepts
24+
25+
## Option 1: GitHub Codespaces (Easiest)
26+
27+
**Best for:** Students who don't want to install Docker, or want to work from any computer.
28+
29+
1. **Open in Codespaces:**
30+
- Go to your GitHub repository page
31+
- Click the green "Code" button
32+
- Select "Codespaces" tab
33+
- Click "Create codespace on main"
34+
- Wait ~1-2 minutes for setup
35+
36+
2. **Start working:**
37+
- Terminal is ready in the browser-based VS Code
38+
- Run: `./tutorial.sh` (no Docker installation needed!)
39+
- Run: `./run-analysis.sh` for the main analysis
40+
41+
3. **View HTML Reports:**
42+
43+
You have **three options** to view the HTML reports generated in `results/`:
44+
45+
**Option A: Live Server (Easiest)**
46+
- Right-click any `.html` file in the `results/` folder
47+
- Select "Open with Live Server"
48+
- Report opens in a new browser tab automatically
49+
50+
**Option B: Python HTTP Server**
51+
```bash
52+
# Start a web server in the results directory
53+
python -m http.server 8000 -d results/
54+
```
55+
- Click the notification to open port 8000 in browser
56+
- Or go to "Ports" tab and click the globe icon next to port 8000
57+
- Navigate to the HTML file you want to view
58+
59+
**Option C: Download and View Locally**
60+
- Right-click any file in `results/` folder
61+
- Select "Download"
62+
- Open the downloaded HTML file in your browser
63+
64+
4. **Stop/Resume Codespace:**
65+
- Codespaces auto-stop after 30 min of inactivity (saves your free hours)
66+
- Resume anytime from github.com (your work is saved)
67+
- Free tier: 60 hours/month for students
68+
69+
5. **Submit your work:**
70+
```bash
71+
git add answers.json results/
72+
git commit -m "Complete assignment"
73+
git push
74+
```
75+
76+
## Option 2: Local Dev Containers
77+
78+
**Best for:** Advanced users who want full control and faster performance.
79+
80+
1. **Install Dev Containers extension** (you should already have it from ENTM201L):
81+
- Extension ID: `ms-vscode-remote.remote-containers`
82+
- Install from VS Code Extensions marketplace
83+
84+
2. **Open this project in VS Code:**
85+
```bash
86+
code .
87+
```
88+
89+
3. **Reopen in Container:**
90+
- Click the green button in bottom-left corner of VS Code
91+
- Select "Reopen in Container"
92+
- Wait for container to start (~30 seconds first time)
93+
94+
4. **Start working:**
95+
- Terminal is now inside the container
96+
- Just run: `./tutorial.sh` (no `docker run` needed!)
97+
98+
## What's Included?
99+
100+
Both Codespaces and local Dev Containers provide:
101+
102+
- Python 3.10 environment
103+
- BioPython for sequence analysis
104+
- MAFFT for alignment
105+
- IQ-TREE for phylogenetics
106+
- All dependencies pre-installed
107+
- VS Code extensions:
108+
- Python language support
109+
- Live Server for viewing HTML reports
110+
- Markdown tools
111+
- Docker support (local only)
112+
113+
## Troubleshooting
114+
115+
### GitHub Codespaces Issues
116+
117+
**Can't see HTML reports:**
118+
- Use Live Server: Right-click .html file → "Open with Live Server"
119+
- Or use Python server: `python -m http.server 8000 -d results/`
120+
- Check the "Ports" tab to see forwarded ports
121+
- If all else fails, download the HTML file and open locally
122+
123+
**Codespace is slow:**
124+
- Free tier uses 2-core machines (slower than local)
125+
- Consider upgrading to 4-core if you have GitHub Pro/Student benefits
126+
- Or switch to local Dev Container for better performance
127+
128+
**Running out of free hours:**
129+
- Free tier: 60 hours/month
130+
- Stop your Codespace when not using it (auto-stops after 30 min)
131+
- Use local Dev Containers if you need unlimited time
132+
133+
**Can't push to GitHub:**
134+
- Make sure you're authenticated with GitHub
135+
- Use the integrated Source Control tab in VS Code
136+
- Or run: `gh auth login` if using GitHub CLI
137+
138+
### Local Dev Container Issues
139+
140+
**Container won't start:**
141+
- Make sure Docker Desktop is running
142+
- Try "Rebuild Container" from Command Palette (Cmd/Ctrl+Shift+P)
143+
144+
**Extensions not working:**
145+
- They install automatically on first launch
146+
- If missing, reload VS Code window
147+
148+
**Want to go back to normal mode:**
149+
- Click green button in bottom-left
150+
- Select "Reopen Folder Locally"
151+
152+
## Regular Workflow vs. Codespaces
153+
154+
**Important:** The regular workflow scripts (`./tutorial.sh` and `./run-analysis.sh`) work the same in both environments:
155+
156+
- **On your local computer:** Scripts use `docker run` automatically
157+
- **In Codespaces/Dev Containers:** Scripts run directly (already inside container)
158+
- No special `-cs` suffix scripts are needed - the same scripts work everywhere!
159+
160+
The pipeline automatically detects the environment and adjusts accordingly.
161+
162+
## More Info
163+
164+
- [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces)
165+
- [VS Code Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers)
166+
- [ENTM201L CLI Tools Setup](https://cosmelab.github.io/entm201l-fall2025/setup/cli-tools.html)

‎.devcontainer/devcontainer.json‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
{
2+
"name": "DNA Barcoding Analysis",
3+
"image": "cosmelab/dna-barcoding-analysis:latest",
4+
5+
"workspaceFolder": "/workspace",
6+
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
7+
8+
"customizations": {
9+
"vscode": {
10+
"extensions": [
11+
"ms-python.python",
12+
"ms-python.vscode-pylance",
13+
"ms-azuretools.vscode-docker",
14+
"yzhang.markdown-all-in-one",
15+
"DavidAnson.vscode-markdownlint",
16+
"ms-vscode.live-server"
17+
],
18+
"settings": {
19+
"python.defaultInterpreterPath": "/opt/conda/bin/python",
20+
"python.linting.enabled": true,
21+
"python.linting.pylintEnabled": false,
22+
"python.formatting.provider": "black",
23+
"terminal.integrated.shell.linux": "/bin/bash",
24+
"files.watcherExclude": {
25+
"**/results/**": true
26+
}
27+
}
28+
}
29+
},
30+
31+
"forwardPorts": [8000],
32+
33+
"portsAttributes": {
34+
"8000": {
35+
"label": "HTML Report Server",
36+
"onAutoForward": "notify"
37+
}
38+
},
39+
40+
"postCreateCommand": "echo '🧬 DNA Barcoding container ready! Run ./tutorial.sh to get started.'",
41+
42+
"postStartCommand": "echo '\n=== GitHub Codespaces Quick Start ===\n1. Run: ./tutorial.sh (to learn with test data)\n2. Run: ./run-analysis.sh (to analyze class sequences)\n3. View HTML reports:\n - Right-click any .html file in results/ → Open with Live Server\n - Or run: python -m http.server 8000 -d results/\n - Then open forwarded port 8000 in browser\n4. Answer questions: python3 answer_assignment.py\n5. Submit: git add . && git commit -m \"Complete assignment\" && git push\n'",
43+
44+
"remoteUser": "root",
45+
46+
"mounts": [
47+
"source=${localWorkspaceFolder}/results,target=/workspace/results,type=bind"
48+
],
49+
50+
"features": {
51+
"ghcr.io/devcontainers/features/git:1": {}
52+
}
53+
}

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,11 @@ architecture.md
1414
github_classroom.md
1515
tracking/
1616
.tracking/
17-
.devcontainer/
1817
docs/student_ux_demo.md
1918
student_data_raw/
2019

20+
# Note: .devcontainer/ MUST be tracked - Codespaces needs it!
21+
2122
# Note: container/ is kept in git for GitHub Actions auto-build
2223
# Students don't need to interact with it
2324

0 commit comments

Comments
 (0)