Skip to content

Commit cd80b3d

Browse files
author
mujing
committed
docs: update project docs and add tmux support
1 parent 949b5a7 commit cd80b3d

5 files changed

Lines changed: 350 additions & 237 deletions

File tree

‎AGENTS.md‎

Lines changed: 129 additions & 231 deletions
Original file line numberDiff line numberDiff line change
@@ -1,243 +1,141 @@
1-
# IDE Code Server - 项目上下文
1+
# AGENTS.md - IDE Code Server
22

3-
## 项目概述
3+
## Purpose
4+
This file helps any incoming agent understand this repository quickly and make safe, consistent changes.
45

5-
这是一个基于 `codercom/code-server` 构建的综合性开发环境 Docker 镜像项目，预配置了多种编程语言运行时和中国大陆镜像加速。目标是为开发者提供一个开箱即用的云端 IDE 环境。
6+
## Project Snapshot
7+
- Project type: Docker image for a cloud IDE based on `codercom/code-server:latest`
8+
- Primary goal: deliver an out-of-the-box development environment with common languages/tools and China-mainland mirrors
9+
- Default runtime user: `coder` (passwordless `sudo`, `su` explicitly blocked)
10+
- Entrypoint: custom `/entrypoint.sh` that runs home initialization before starting `code-server`
611

7-
### 核心特性
8-
9-
- **基础镜像**: `codercom/code-server:latest`
10-
- **用户权限**: `coder` 用户，支持无密码 sudo（已禁用 su 命令）
11-
- **多语言支持**: Go、Python 3.13、Node.js 22 LTS、JDK 21、Ruby 3.4.1
12-
- **开发工具**: git、curl、wget、vim、dnsutils (nslookup)、yq、kubectl、gopls、delve、golangci-lint、uv、conda、pnpm、yarn、Maven、Rails
13-
- **镜像加速**: 所有语言包管理器均配置中国大陆镜像源
14-
15-
## 项目结构
16-
17-
```
12+
## Repository Layout
13+
```text
1814
ide-code-server/
19-
├── Dockerfile # 主构建文件（多层单阶段构建）
20-
├── README.md # 使用文档
21-
├── .dockerignore # Docker 构建排除文件
15+
├── Dockerfile
16+
├── README.md
17+
├── AGENTS.md
18+
├── scripts/
19+
│ └── init-home.sh
2220
├── .github/
2321
│ └── workflows/
24-
│ └── build-and-push.yml # CI/CD 多架构构建流程
22+
│ └── build-and-push.yml
2523
└── docs/
26-
└── plans/ # 设计与规划文档
27-
├── 2026-03-02-ide-code-server-design.md
28-
└── 2026-03-02-ide-code-server.md
24+
└── plans/
2925
```
3026

31-
## 构建与部署
32-
33-
### 本地构建
34-
27+
## What the Image Installs
28+
29+
### Language runtimes
30+
- Go `1.24.0`
31+
- Python `3.13` (Miniforge/conda)
32+
- Node.js `22` LTS
33+
- JDK `21` (Temurin)
34+
- Maven `3.9.11`
35+
- Ruby `3.4.4` via `rbenv`
36+
37+
### Core tools
38+
- System: `git`, `curl`, `wget`, `vim`, `tmux`, `dnsutils`, `yq`, `kubectl`, `sudo`
39+
- Go tools: `gopls`, `dlv`, `golangci-lint`, `goimports`
40+
- Python tools: `uv`, `conda`
41+
- Node tools: `pnpm`, `yarn`, `@iflow-ai/iflow-cli`, `@anthropic-ai/claude-code`
42+
- Ruby tools: `bundler`, `rails`
43+
44+
## Dockerfile Design (Layered for Cache Efficiency)
45+
| Layer | Main content |
46+
|---|---|
47+
| 1 | Base system tools |
48+
| 2 | User permissions/sudo policy |
49+
| 3 | Go + Go dev tools |
50+
| 4 | Python + uv + conda |
51+
| 5 | Node.js + package managers/CLIs |
52+
| 6 | JDK + Maven |
53+
| 7 | Ruby + rbenv + Rails |
54+
| 8 | Home templates, PATH/bootstrap, entrypoint, mount-friendly defaults |
55+
56+
The layering order is intentional. Keep low-churn dependencies in earlier layers.
57+
58+
## Startup and Mount Behavior (Critical)
59+
- `ENTRYPOINT` runs `/opt/dev-configs/init-home.sh` on every container start.
60+
- This is required because users often bind-mount `/home/coder` or its subdirectories.
61+
- `scripts/init-home.sh` ensures required directories/config files exist.
62+
- It also protects Ruby shell initialization compatibility:
63+
- Creates `~/.rbenv -> /opt/rbenv` symlink if missing.
64+
- Migrates legacy `.bashrc` entries from `/home/coder/.rbenv` to `/opt/rbenv`.
65+
66+
If you modify shell bootstrap behavior, update both:
67+
- Docker template generation in `Dockerfile` (`/opt/dev-configs/bashrc-append.sh`)
68+
- Runtime reconciliation logic in `scripts/init-home.sh`
69+
70+
## Mirror/Registry Configuration
71+
| Ecosystem | Mirror/Registry |
72+
|---|---|
73+
| Go | `https://goproxy.cn` |
74+
| pip/uv | `https://pypi.tuna.tsinghua.edu.cn/simple` |
75+
| npm/pnpm/yarn | `https://registry.npmmirror.com` |
76+
| Maven | Aliyun public repository mirror |
77+
| RubyGems | `https://gems.ruby-china.com/` |
78+
79+
## CI/CD Pipeline Summary
80+
Workflow: `.github/workflows/build-and-push.yml`
81+
82+
- Triggers:
83+
- Push to `master`
84+
- Manual dispatch
85+
- Build strategy:
86+
- Matrix build on `linux/amd64` and `linux/arm64`
87+
- Push per-platform images by digest
88+
- Merge job creates a multi-arch manifest
89+
- Tags:
90+
- `latest` (default branch only)
91+
- short SHA
92+
- date tag (`YYYYMMDD`)
93+
- Registry:
94+
- GHCR (`ghcr.io/<owner>/<repo>`, forced lowercase in workflow)
95+
- Post-merge test job validates:
96+
- default user
97+
- major tool availability in `bash -i` (simulates VS Code terminal)
98+
- sudo policy and mirror config
99+
100+
## Agent Change Guide
101+
102+
### If you add/remove a tool
103+
1. Update `Dockerfile`.
104+
2. Update human docs: `README.md`.
105+
3. Update this file (`AGENTS.md`) so future agents stay aligned.
106+
4. Check CI tool-access test section in `.github/workflows/build-and-push.yml` and add/update relevant assertions.
107+
108+
### If you change language versions
109+
1. Update version/env lines in `Dockerfile`.
110+
2. Update version tables in `README.md` and `AGENTS.md`.
111+
3. Watch for path/version-coupled shell settings (example: Ruby gem bin path in `.bashrc` template).
112+
113+
### If you change mount/bootstrap logic
114+
1. Keep `Dockerfile` templates and `scripts/init-home.sh` in sync.
115+
2. Preserve compatibility with existing mounted home directories.
116+
3. Avoid assumptions that `/home/coder` contents are fresh.
117+
118+
## Local Validation Checklist
119+
Use these when Docker is available:
35120
```bash
36-
# 构建镜像
37-
docker build -t ide-code-server .
38-
39-
# 本地运行（最小配置）
40-
docker run -d \
41-
--name ide-code-server \
42-
-p 8080:8080 \
43-
-v $(pwd)/project:/home/coder/project \
44-
-v $(pwd)/code-server:/home/coder/.local/share/code-server \
45-
-e PASSWORD=yourpassword \
46-
ide-code-server:latest
121+
docker build -t ide-code-server:test .
122+
docker run --rm -it ide-code-server:test bash -i -c "whoami"
123+
docker run --rm -it ide-code-server:test bash -i -c "ruby -v && rails -v && tmux -V"
124+
docker run --rm -it ide-code-server:test bash -i -c "go version && python3 --version && node --version && java -version"
47125
```
48126

49-
### CI/CD 流程
50-
51-
项目使用 GitHub Actions 实现自动化构建和发布：
52-
53-
- **触发条件**: 推送到 `master` 分支 或手动触发
54-
- **构建平台**: `linux/amd64`, `linux/arm64`（并行构建）
55-
- **镜像仓库**: GitHub Container Registry (`ghcr.io`)
56-
- **标签策略**:
57-
- `latest` - 最新版本（仅 master 分支）
58-
- `sha-xxxxxx` - 短提交哈希
59-
- `YYYYMMDD` - 日期标签
60-
61-
### 多架构构建策略
62-
63-
使用 matrix 策略实现并行多平台构建：
64-
1. 各平台独立构建并推送 digest
65-
2. 合并阶段创建多架构 manifest
66-
3. 最终镜像支持 `linux/amd64` 和 `linux/arm64`
67-
68-
## Dockerfile 分层结构
69-
70-
Dockerfile 采用精心设计的分层结构以优化缓存效率：
71-
72-
| 层 | 内容 | 缓存优化考虑 |
73-
|---|------|-------------|
74-
| Layer 1 | 系统工具 (git, curl, wget, vim, dnsutils, yq, kubectl) | 变更频率最低 |
75-
| Layer 2 | 用户权限配置 (sudo) | 基础配置 |
76-
| Layer 3 | Go 1.24.0 + gopls + delve + golangci-lint | 独立语言环境 |
77-
| Layer 4 | Python 3.13 + uv + Miniforge (conda) | 独立语言环境 |
78-
| Layer 5 | Node.js 22 LTS + npm/pnpm/yarn | 独立语言环境 |
79-
| Layer 6 | JDK 21 (Temurin) + Maven 3.9.11 | 独立语言环境 |
80-
| Layer 7 | Ruby 3.4.1 (rbenv) + Rails | 独立语言环境 |
81-
| Layer 8 | 目录结构 + 镜像配置文件 | 变更频率最高 |
82-
83-
## 镜像源配置
84-
85-
所有包管理器均已配置中国大陆镜像加速：
86-
87-
| 语言/工具 | 镜像源 | 配置位置 |
88-
|----------|--------|----------|
89-
| Go | goproxy.cn | 环境变量 `GOPROXY` |
90-
| Python (pip/uv) | pypi.tuna.tsinghua.edu.cn | `~/.config/pip/pip.conf`, 环境变量 `UV_INDEX_URL` |
91-
| conda | conda-forge (默认) | Miniforge 默认配置 |
92-
| Node.js (npm/pnpm/yarn) | npmmirror | `~/.npmrc` |
93-
| Maven | 阿里云 | `~/.m2/settings.xml` |
94-
| Ruby (gem) | Ruby China | `~/.gemrc` |
95-
96-
## 容器内目录结构
97-
98-
```
99-
/home/coder/
100-
├── project/ # 工作区（主要挂载点）
101-
├── .local/share/code-server/ # VS Code 扩展和用户数据
102-
├── .local/share/pnpm/ # pnpm 包存储
103-
├── .m2/
104-
│ ├── settings.xml # Maven 配置
105-
│ └── repository/ # Maven 本地仓库
106-
├── .npm/ # npm 缓存
107-
├── .npmrc # npm 配置
108-
├── .gemrc # gem 配置
109-
├── .config/pip/pip.conf # pip 配置
110-
├── .cache/
111-
│ ├── uv/ # uv 缓存
112-
│ └── pip/ # pip 缓存
113-
├── go/ # Go GOPATH（用户安装的包）
114-
└── .rbenv/ # Ruby 版本管理
115-
```
116-
117-
## 外部挂载支持
118-
119-
为提升开发体验，以下目录支持外部挂载以实现数据持久化：
120-
121-
| 容器路径 | 用途 | 挂载优势 |
122-
|----------|------|----------|
123-
| `/home/coder/project` | 工作区 | 代码持久化 |
124-
| `/home/coder/.local/share/code-server` | VS Code 数据 | 扩展和设置持久化 |
125-
| `/home/coder/.npm` | npm 缓存 | 避免重复下载 |
126-
| `/home/coder/.local/share/pnpm` | pnpm 存储 | 共享包存储 |
127-
| `/home/coder/go` | Go 包 | 持久化 go install 的包 |
128-
| `/home/coder/.cache/uv` | uv 缓存 | Python 包缓存 |
129-
| `/home/coder/.cache/pip` | pip 缓存 | pip 包缓存 |
130-
| `/home/coder/.m2/repository` | Maven 仓库 | Java 依赖缓存 |
131-
132-
### 推荐挂载配置
133-
134-
```bash
135-
docker run -d \
136-
--name ide-code-server \
137-
-p 8080:8080 \
138-
-v $(pwd)/project:/home/coder/project \
139-
-v $(pwd)/code-server:/home/coder/.local/share/code-server \
140-
-v $(pwd)/npm:/home/coder/.npm \
141-
-v $(pwd)/go:/home/coder/go \
142-
-e PASSWORD=yourpassword \
143-
ghcr.io/fjiayang/ide-code-server:latest
144-
```
145-
146-
## 开发约定
147-
148-
### Dockerfile 编写规范
149-
150-
1. **分层原则**: 按变更频率从低到高排列层，优化构建缓存
151-
2. **清理缓存**: 每个 `apt-get` 或 `curl` 安装后清理缓存文件
152-
3. **架构支持**: 使用 `$(dpkg --print-architecture)` 动态检测架构
153-
4. **用户切换**: 在 Dockerfile 末尾切换回 `coder` 用户
154-
155-
### Git 提交规范
156-
157-
使用 Conventional Commits 格式：
158-
159-
- `feat:` 新功能
160-
- `fix:` Bug 修复
161-
- `docs:` 文档更新
162-
- `chore:` 杂项（构建配置等）
163-
164-
### CI/CD 注意事项
165-
166-
- 镜像名称必须小写（GHCR 要求）
167-
- 使用 `visudo -c` 验证 sudoers 配置语法
168-
- 多架构构建需要矩阵策略和 manifest 合并
169-
170-
### Git 工作流
171-
172-
项目使用以下 Git 工作流程：
173-
174-
#### 分支策略
175-
176-
- `master` - 主分支，受保护，通过 PR 合并
177-
- 功能开发：直接在 `master` 分支提交或创建 feature 分支
178-
179-
#### 日常开发流程
180-
181-
```bash
182-
# 1. 拉取最新代码
183-
git pull origin master
184-
185-
# 2. 查看当前状态
186-
git status
187-
188-
# 3. 添加修改的文件
189-
git add <files>
190-
# 或添加所有更改
191-
git add -A
192-
193-
# 4. 提交（使用 Conventional Commits 格式）
194-
git commit -m "feat: 添加 vim 和 dnsutils 工具"
195-
git commit -m "fix: 修复 ruby 命令找不到的问题"
196-
git commit -m "docs: 更新文档"
197-
198-
# 5. 推送到远程
199-
git push origin master
200-
```
201-
202-
#### 提交类型规范
203-
204-
| 类型 | 说明 | 示例 |
205-
|-----|------|------|
206-
| `feat` | 新功能 | `feat: 添加 vim 编辑器支持` |
207-
| `fix` | Bug 修复 | `fix: 修复容器内 ruby 命令无法识别` |
208-
| `docs` | 文档更新 | `docs: 更新 README 工具列表` |
209-
| `chore` | 构建/工具变更 | `chore: 升级 Go 版本到 1.24` |
210-
| `refactor` | 代码重构 | `refactor: 优化 Dockerfile 分层结构` |
211-
| `test` | 测试相关 | `test: 添加构建验证测试` |
212-
213-
#### CI/CD 自动触发
214-
215-
- 推送到 `master` 分支自动触发构建
216-
- 构建成功后自动推送到 `ghcr.io`
217-
- 生成 `latest`、`sha-xxxxxx`、`YYYYMMDD` 三种标签
218-
219-
## 快速参考命令
220-
221-
```bash
222-
# 查看镜像构建历史
223-
docker history ide-code-server:latest
224-
225-
# 进入容器调试
226-
docker run -it --rm ide-code-server:latest bash
227-
228-
# 查看多架构镜像信息
229-
docker buildx imagetools inspect ghcr.io/fjiayang/ide-code-server:latest
230-
231-
# 本地构建特定平台
232-
docker buildx build --platform linux/amd64 -t ide-code-server:amd64 .
233-
234-
# 手动触发 CI 构建
235-
gh workflow run build-and-push.yml
236-
```
237-
238-
## 相关链接
239-
240-
- [code-server 官方文档](https://coder.com/docs/code-server/latest)
241-
- [Eclipse Temurin JDK](https://adoptium.net/)
242-
- [Miniforge (conda-forge)](https://github.com/conda-forge/miniforge)
243-
- [uv Python 包管理器](https://docs.astral.sh/uv/)
127+
## Git and Commit Conventions
128+
- Conventional Commits are preferred:
129+
- `feat:`
130+
- `fix:`
131+
- `docs:`
132+
- `chore:`
133+
- `refactor:`
134+
- `test:`
135+
- Main integration branch is `master`.
136+
137+
## Key Risk Areas
138+
- Shell startup regressions (especially VS Code integrated terminal behavior)
139+
- PATH order changes that hide installed tools
140+
- Volume-mount edge cases under `/home/coder`
141+
- Multi-arch build breaks caused by architecture-specific binary URLs

0 commit comments

Comments
 (0)