Skip to content

Commit 9893545

Browse files
author
박성모
committed
docs(manual): expand 2.5단계 Docker daemon check with output → state mapping
The original '데몬 켜졌는지 확인' block listed 4 commands but didn't explain what each output means → users see 'CONTAINER ID IMAGE' or '29.4.0' or a 30-line dump and don't know which state they're in. Restructure into three tiers: 🥇 한 줄 진단 — output → state table (✓ daemon up / ✗ daemon down) 🥈 자세히 보기 — three commands, each with inline output interpretation (server-version / docker ps / docker info | head) covering: empty output, error message, header-only, header+rows, Cannot connect, permission denied 🥉 자주 보는 에러 메시지 — 5-row table mapping each error string to its real cause (app off vs starting vs hanging vs uninstalled vs permission) and the precise fix ✗ daemon down 복구 — 4-step ladder (verify app installed → open → wait for whale → re-check) Also rewrite '데몬 켜기' table to add a 'when to use' column and a 'after pressing — what to expect' 3-step flow with explicit timing expectations (30s Apple Silicon / 60-90s Intel / 2min+ = hang) and the auto-start ON/OFF rows so users see how to keep it from auto-launching when they don't want it.
1 parent 76fd515 commit 9893545

1 file changed

Lines changed: 69 additions & 19 deletions

File tree

docs/GUIDE-MANUAL-INSTALL.md

Lines changed: 69 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -630,38 +630,88 @@ docker info # Server: ... 가 보이면 데몬 정상
630630
631631
#### 데몬(서버) 켜기
632632

633-
| 방법 | 명령 / 동작 |
634-
|---|---|
635-
| 🖱 **앱으로 켜기** (가장 쉬움) | Applications → **Docker.app** 더블클릭, 또는 Spotlight (`⌘ Space` → "docker") |
636-
|**터미널에서 켜기** | `open -a Docker` |
637-
| 🔄 **부팅 시 자동 켜기** (기본 ON) | GUI: Docker Desktop 설정 → General → "Start Docker Desktop when you sign in" — CLI 는 아래 섬션 참고 |
633+
| 방법 | 명령 / 동작 | 언제 쓰나 |
634+
|---|---|---|
635+
| 🖱 **앱 더블클릭** (가장 쉬움) | Applications → **Docker.app** 더블클릭 (또는 Spotlight `⌘ Space` → "docker") | GUI 익숙 / 한 번만 켤 때 |
636+
|**터미널에서 켜기** | `open -a Docker` | 스크립트·SSH·자동화에서 |
637+
| 🔄 **부팅 시 자동 켜기** | Settings → General → "Start Docker Desktop when you sign in" ✓ | 매번 켜기 귀찮을 때 (기본 ON) |
638+
|**부팅 시 자동 꺼두기** | 위 체크 해제 | 평소 Docker 안 쓰는데 메모리 절약하고 싶을 때 |
639+
640+
**켜진 뒤 흐름** (3단계):
638641

639-
켜진 후 **메뉴바의 🐳 고래 아이콘이 움직임을 멈출 때까지** 30~60초 대기 → 그제서야 `docker` 명령이 동작합니다.
642+
1. 메뉴바 🐳 **고래 아이콘이 등장** → 시동 시작
643+
2. 30~60초 동안 고래가 움직임 (=내부 VM 부팅 중)
644+
3. **고래가 멈추면** → 그제서야 `docker` 명령이 동작합니다. 안 멈췄는데 명령 치면 `Cannot connect to the Docker daemon` 정상.
645+
646+
> **얼마나 기다려야?** Apple Silicon 30초, 인텔 Mac/처음 설치 직후 60~90초. 2분 넘게 움직이면 hang — 메뉴바 🐳 클릭 → Restart.
640647
641648
#### 데몬(서버) 켜졌는지 확인
642649

650+
> 🎯 **핵심**: Docker 는 *데몬(서버)**CLI(클라이언트)* 가 분리되어 있어서, **CLI 명령은 데몬이 꺼져 있어도 일부 동작합니다**. 헷갈리지 않으려면 아래 "한 줄 진단"을 쓰세요.
651+
652+
##### 🥇 한 줄 진단 (가장 확실)
653+
643654
```bash
644-
# 가장 확실한 한 줄
645655
if docker info >/dev/null 2>&1; then echo "✓ daemon up"; else echo "✗ daemon down"; fi
656+
```
657+
658+
| 출력 | 의미 | 다음에 할 일 |
659+
|---|---|---|
660+
| `✓ daemon up` | 데몬 기동 완료, 명령 다 됨 | 그대로 진행 |
661+
| `✗ daemon down` | 앱 자체가 꺼져 있거나 시동 중 | `open -a Docker` 후 30~60초 대기, 다시 확인 |
646662

647-
# 버전만 짧게
648-
docker info --format '{{.ServerVersion}}' # 예: 29.4.0
663+
##### 🥈 자세히 보기
664+
665+
```bash
666+
# 1) 서버 버전만 짧게
667+
docker info --format '{{.ServerVersion}}'
668+
# ── 결과 해석 ────────────────────────────
669+
# 29.4.0 → ✓ 데몬 ON
670+
# (빈 줄) → 표시할 게 없음 (드물지만 에러)
671+
# "Cannot connect to..." 등 에러 → ✗ 데몬 OFF
649672

650-
# 전체 정보 보기
651-
docker info | head -30 # "Server:" 섬션이 아래쪽에 나와야 OK
652-
docker ps # 표 헤더 (CONTAINER ID IMAGE ...) 나오면 OK
673+
# 2) 컨테이너 목록 (살아 있는 것만)
674+
docker ps
675+
# ── 결과 해석 ────────────────────────────
676+
# CONTAINER ID IMAGE COMMAND ... → ✓ 데몬 ON, 표 헤더만 = 컨테이너 0개
677+
# (헤더 + 행) → ✓ 데몬 ON, OpenClaw 등 실행 중
678+
# "Cannot connect to the Docker daemon" → ✗ 데몬 OFF
679+
# "permission denied while trying ..." → 데몬 ON 인데 권한 문제 (드뭄, macOS Desktop 에선 거의 안 봄)
680+
681+
# 3) 전체 시스템 정보
682+
docker info | head -30
683+
# ── 결과 해석 ────────────────────────────
684+
# "Client:" 섹션 다음 "Server:" 섹션이 같이 나옴 → ✓ 데몬 ON
685+
# "Client:" 섹션만 + 끝에 "ERROR: Cannot connect" → ✗ 데몬 OFF
653686
```
654687

655-
> ⚠️ `docker info | head -5`**Client 섹션만** 출력해서 데몬이 껌져 있어도 동일하게 보입니다. **`Server:` 줄을 확인**하거나 위의 한 줄짜리 방법을 쓰세요.
688+
> ⚠️ `docker info | head -5` 만 보지 마세요 — **Client 섹션만** 잘려서 데몬이 꺼져 있어도 정상처럼 보입니다. **`Server:` 줄이 보여야** 진짜 켜진 것입니다.
689+
690+
##### 🥉 자주 보는 에러 메시지와 정확한 의미
691+
692+
| 에러 메시지 | 진짜 의미 | 해결 |
693+
|---|---|---|
694+
| `Cannot connect to the Docker daemon at unix:///var/run/docker.sock` | 앱이 꺼졌거나 아직 시동 중 | `open -a Docker` → 메뉴바 🐳 멈출 때까지 30~60초 → 다시 확인 |
695+
| `Is the docker daemon running?` | 위와 같음 | 위와 같음 |
696+
| `request returned 500 Internal Server Error` | 데몬이 켜졌지만 일시 오류 / hang | "재시작" 절 참고 (`osascript ... quit; sleep 5; open -a Docker`) |
697+
| `docker: command not found` | Docker Desktop **자체가 미설치** | [2단계](#2단계--docker-desktop-직접-다운로드) 진행 |
698+
| `permission denied while trying to connect to ... docker.sock` | 권한 문제 (보통 Linux. macOS Desktop 에선 거의 발생 X) | Docker Desktop 재시작 / 재설치 |
699+
700+
##### ✗ daemon down 이 나왔을 때 — 단계별 복구
656701

657-
**✗ daemon down 이 나오면 → Docker 앱이 안 켜져 있는 것입니다:**
658702
```bash
659-
open -a Docker # 앱 실행
660-
# 메뉴바 🐳 가 움직임을 멈출 때까지 30~60초 대기
661-
# 그 뒤 위 확인 명령 다시 치기 → ✓ daemon up 이 나와야 OK
662-
```
703+
# ❶ 앱이 깔려 있는지 확인
704+
ls /Applications/Docker.app >/dev/null 2>&1 && echo "✓ 앱 설치됨" || echo "✗ 앱 미설치 → 2단계 진행"
705+
706+
# ❷ 앱 켜기
707+
open -a Docker
663708

664-
`Cannot connect to the Docker daemon` 가 나오면 → 아직 시동 중. 잠시 기다리거나 메뉴바 고래 아이콘을 클릭해 상태 확인.
709+
# ❸ 메뉴바 🐳 고래가 움직임을 멈출 때까지 대기 (30~60초)
710+
# 움직이는 동안은 시동 중 — 명령 쳐도 'Cannot connect' 가 정상
711+
712+
# ❹ 다시 확인
713+
docker info >/dev/null 2>&1 && echo "✓ daemon up" || echo "아직 시동 중 — 30초 더 기다려보세요"
714+
```
665715

666716
#### Docker 켜기 / 끄기 / 항상 켜기 / 완전 죽이기 — 한눈에
667717

0 commit comments

Comments
 (0)