# 实例创建流程

> 为新项目创建 WorkPod 开发容器的标准步骤。

---

## 前置条件

- Docker 已安装并运行
- 基础镜像已构建：`docker images \| grep workpod-alpine`

---

## 标准流程（3 步）

### Step 1: 创建实例目录

```bash
cd E:/wk-lab/workpod
mkdir -p instances/{name}
cp instances/.template/docker-compose.yml instances/{name}/
```

### Step 2: 编辑 compose 文件

打开 `instances/{name}/docker-compose.yml`，修改占位符：

| 占位符 | 改为 | 示例 |
|--------|------|------|
| `{name}` | 实例名 | `suke` |
| `{SSH_PORT}` | SSH 端口 | `2211` |
| `{WEB_PORT}` | Web 端口 | `7711` |
| `{PROJECT_PATH}` | 项目路径 | `E:/wk-suke` |

按需取消注释：
- **Java 项目** → 取消注释 JDK/Maven volume 和 JAVA_HOME/MAVEN_HOME env
- **home 持久化** → 确保 `../../data/home/{name}:/root` 已配置

### Step 3: 注册并启动

编辑 `instances/registry.yaml`，在 `local:` 下添加新条目：

```yaml
  - name: ws-{name}-dev
    display: {中文名}
    type: project
    project: {name}
    project_path: E:/wk-{name}
    image: ws-{name}-dev:latest
    ssh_port: {SSH_PORT}
    web_port: {WEB_PORT}
    network: workpod-{name}-network
    status: starting
    compose: instances/{name}/docker-compose.yml
```

启动：

```bash
cd instances/{name} && docker compose up -d --build
```

验证：

```bash
docker ps --filter name=ws-{name}
# 应看到端口映射正确
```

更新状态：`registry.yaml` 中 `status: starting` → `running`

---

## 可选：自定义镜像

如果项目需要额外工具（如 JDK），创建 `instances/{name}/Dockerfile`：

```dockerfile
FROM workpod-alpine:latest

LABEL org.opencontainers.image.title="ws-{name}-dev" \
      org.opencontainers.image.description="{描述}"

EXPOSE 22 7681

ENTRYPOINT ["/entrypoint.sh"]
```

compose 中添加 build 配置：

```yaml
    build:
      context: ../../
      dockerfile: instances/{name}/Dockerfile
    image: ws-{name}-dev:latest
```

---

## 完整示例：创建 suke 实例

```bash
# 1. 创建目录 + 复制模板
mkdir -p instances/suke
cp instances/.template/docker-compose.yml instances/suke/

# 2. 替换占位符（手动或 sed）
#    {name} → suke, {SSH_PORT} → 2211, {WEB_PORT} → 7711, {PROJECT_PATH} → E:/wk-suke

# 3. 注册到 registry.yaml（添加 local 条目）

# 4. 启动
cd instances/suke && docker compose up -d --build

# 5. 验证
docker ps --filter name=ws-suke
# curl -s http://localhost:7711 | head -5   # ttyd 可访问
```