Skip to content

docs(i18n): English chapter content quality pass (system-building 01–07) #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
haksungjang merged 1 commit into from
Jun 5, 2026
Merged

docs(i18n): English chapter content quality pass (system-building 01–07) #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 57 additions & 57 deletions website/i18n/en/docusaurus-plugin-content-docs/current/01-setup/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,34 +7,34 @@ checklist:
self_study_time: 30 minutes to 1 hour
---

# environmental preparation:Install tools needed for practice
# Environment setup: Install the tools needed for the exercises

## 1. What we do in this chapter

Install and validate the tools you will use in all exercises in this kit.
Install and verify the tools you will use across all exercises in this kit.

- Only after this step is completed can the agent be executed later.
- This chapter itself does not directly meet the checklist items of ISO/IEC 5230 or ISO/IEC 18974
- However, without this step, all subsequent exercises are impossible, so it must be completed.
- You can only run the agents in later chapters once this step is complete.
- This chapter itself does not directly satisfy any ISO/IEC 5230 or ISO/IEC 18974 checklist item.
- However, none of the later exercises are possible without it, so it must be completed.

## 2. List of tools needed
## 2. Tools you will need

| tools | Use | Installation required | Version Requirements |
| -------------- | --------------------------------------------- | ------------------------------- | -------------------- |
| Docker Desktop | All hands-on tools(Dependency-Track, etc.)Run | Required | 24.x and above |
| Git | Repository Management and Version Management | Required | 2.x and above |
| Claude Code | AI-based practice assistance,run agent | Required | Latest version |
| Node.js | Build Docusaurus Documentation Site | select(Document site if needed) | v18 LTS or later |
| Tool | Use | Installation | Version requirement |
| -------------- | ------------------------------------------------ | ----------------------------------------- | ------------------- |
| Docker Desktop | Runs all hands-on tools (Dependency-Track, etc.) | Required | 24.x or later |
| Git | Repository and version management | Required | 2.x or later |
| Claude Code | AI-assisted practice; runs the agents | Required | Latest version |
| Node.js | Builds the Docusaurus documentation site | Optional (only if you need the docs site) | v18 LTS or later |

## 3. Installation instructions(By OS)
## 3. Installation instructions (by OS)

### macOS

```bash
# Docker Desktop
# https://www.docker.com/products/docker-desktop download from
# Download from https://www.docker.com/products/docker-desktop

# Git (Homebrew Use)
# Git (via Homebrew)
brew install git

# Claude Code
Expand All @@ -49,7 +49,7 @@ brew install node
We recommend using WSL2. When installing Docker Desktop, you must enable the WSL2 backend.

```powershell
# Docker Desktop: https://www.docker.com/products/docker-desktop download from
# Docker Desktop: download from https://www.docker.com/products/docker-desktop
# WSL2 must be enabled

# Git for Windows: https://git-scm.com/download/win
Expand Down Expand Up @@ -77,9 +77,9 @@ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
```

## 4. Set of installation confirmation commands
## 4. Installation verification script

Run the script below to check whether all required tools are installed properly.
Run the script below to check whether all required tools are installed correctly.

```bash
#!/bin/bash
Expand All @@ -98,26 +98,26 @@ echo -n "Node.js (optional): "
node --version 2>/dev/null || echo "⚪ not installed (optional)"

echo ""
echo "Proceed to the next step when all required tools are installed."
echo "Proceed to the next step once all required tools are installed."
```

## 5. Clone the repository and first run it
## 5. Clone the repository and run it for the first time

If you're just starting out:
If you are just starting out:

```bash
# clone repository
# Clone the repository
git clone https://github.com/trustedoss/trustedoss.github.io.git
cd trustedoss.github.io

# output create directory if missing
# Create the output directory if it is missing
mkdir -p output

# Claude Code run
# Run Claude Code
claude
```

If you have already cloned:
If you have already cloned it:

```bash
cd trustedoss.github.io
Expand All @@ -127,65 +127,65 @@ claude

## 6. What to do after running Claude Code for the first time

When Claude Code runs:
When Claude Code starts:

1. **Type “Where do I start?”** → Automatically guides you to the next step after analyzing the current status
2. If this is your first run, the `output/` folder is empty, so you will be guided to the `02-organization-designer` agent.
3. Claude Code automatically reads `CLAUDE.md` to understand project context.
1. **Type "Where do I start?"** → It analyzes your current status and automatically guides you to the next step.
2. On your first run, the `output/` folder is empty, so it will direct you to the `02-organization-designer` agent.
3. Claude Code automatically reads `CLAUDE.md` to understand the project context.

> Claude Code also reads `CLAUDE.md` in each chapter folder to get context for that step.
> Claude Code also reads the `CLAUDE.md` in each chapter folder to pick up the context for that step.

## 7. Troubleshooting

### When Docker Desktop does not run
### When Docker Desktop won't start

- **macOS**:System Preferences > Privacy & Security > Click Allow
- **Windows**:Requires Hyper-V and WSL2 activation
- **Linux**:`sudo systemctl start docker` Run and retry
- **macOS**: Go to System Preferences > Privacy & Security and click Allow.
- **Windows**: Requires Hyper-V and WSL2 to be enabled.
- **Linux**: Run `sudo systemctl start docker` and retry.

### Claude Code When you can't log in
### When you can't log in to Claude Code

- Run `claude login` to authenticate with your Anthropic account.
- If the browser does not open automatically, copy the URL displayed in the terminal and access it manually.
- If the browser does not open automatically, copy the URL shown in the terminal and open it manually.

### git clone permission error

- Clone via HTTPS: `git clone https://github.com/trustedoss/trustedoss.github.io.git`
- In case of GitHub authentication error:`git config --global credential.helper store` Run and retry
- Clone over HTTPS: `git clone https://github.com/trustedoss/trustedoss.github.io.git`
- If you hit a GitHub authentication error, run `git config --global credential.helper store` and retry.

### When your Node.js version is too low(Below v18)
### When your Node.js version is too old (below v18)

- Recommended to use nvm: `nvm install --lts && nvm use --lts`
- We recommend using nvm: `nvm install --lts && nvm use --lts`

## 8. Self-study

:::info Self-study mode(Approximately 30 minutes to 1 hour)
The time required will vary depending on the tool installation situation.
:::info Self-study mode (about 30 minutes to 1 hour)
The time required varies depending on your tool installation situation.
:::

1. Check out the list of tools you need
2. Install each tool(If not installed)
3. Run the installation verification script
4. Clone the repository and create `output/`
5. After running `claude` “Where do I start?” input
1. Review the list of tools you need.
2. Install each tool (if not already installed).
3. Run the installation verification script.
4. Clone the repository and create `output/`.
5. After running `claude`, type "Where do I start?"

## 9. Completion Confirmation Checklist
## 9. Completion checklist

- [ ] `docker --version` Normal output
- [ ] `git --version` Normal output
- [ ] `claude --version` Normal output
- [ ] Repository clone complete(or already exists)
- [ ] `docker --version` outputs normally
- [ ] `git --version` outputs normally
- [ ] `claude --version` outputs normally
- [ ] Repository clone complete (or already exists)
- [ ] `output/` directory exists
- [ ] Check normal operation after executing `claude`
- [ ] Confirmed normal operation after running `claude`

## 10. Next steps

Once the environment preparation is complete, proceed to the organization design phase.
Once your environment is ready, proceed to the organization design phase.

[organizational structure:Designating open source personnel and defining roles](../02-organization/index.md)Read the chapter first and then run the agent,You can run the agent right away.
Read the [Organizational structure: Designating open source personnel and defining roles](../02-organization/index.md) chapter first, then run the agent — or you can run the agent right away.

:::tip Check before execution
Terminate the current Claude session first(`/exit` or `Ctrl+C`)After doing it,Run the command below in a new terminal.
:::tip Check before running
First terminate the current Claude session (`/exit` or `Ctrl+C`), then run the command below in a new terminal.
:::

```bash
Expand Down
Loading
Loading