<!-- canonical: https://docs.axelabs.ai/partner/macmini-prep -->
<!-- source: content/partner/macmini-prep.mdx -->

---
title: macmini 사전 준비
description: 배포 D-7 까지 귀사 IT 가 macmini 측에서 완료할 6 단계 (Tailscale 합류 + SSH key 회신 + 절전 disable).
---

# macmini 사전 준비

신규 배포 D-day 의 최소 1 주일 전 (D-7) 까지 **귀사 IT 담당자** 가 macmini 측에서 완료해야 하는 6 단계. 모두 합쳐 ~30 분.

이 단계가 끝나야 운영자가 `axe onboard {customer} --apply` 로 push deploy 가능합니다.

## 사전 확인

| 항목 | 권장 |
|---|---|
| 하드웨어 | Apple Silicon (M2 / M3 / M4), 16GB+ RAM, 512GB+ SSD |
| macOS | Sonoma 14.x 또는 Sequoia 15.x |
| 네트워크 | 유선 이더넷 권장 (Wi-Fi 가능하나 backup 시 불안정) |
| 전원 | 항시 켜진 상태로 운영 (UPS 권장) |
| 위치 | 회사 IT 룸 (또는 동등) — 직원 데스크 X |

## 1. macOS 초기 설정 (5분)

1. macmini 부팅 → 마법사 진행 (회사 Apple ID 권장, 개인 계정 X)
2. 컴퓨터 이름 = `{customer}-macmini` (예: `realchoice-macmini`) — 시스템 설정 → 일반 → 정보 → 이름
3. 사용자명 = `{customer}` (예: `realchoice`) — 운영자가 SSH 시 사용. 다른 이름 가능하나 운영자에게 회신 필요
4. 회사 메일로 활성화 (개인 메일 X)
5. macOS 최신 업데이트 적용 → 자동 업데이트 **OFF** (배포 후 사전 협의 없이 update 시 다운타임 위험)

## 2. 절전 / 자동 잠금 OFF (3분)

시스템 설정 → 잠금 화면:

| 항목 | 값 |
|---|---|
| 비활성 시간 후 디스플레이 끄기 | **사용 안 함** |
| 비활성 시간 후 잠금 시작 | **사용 안 함** |
| 자동으로 로그아웃 | **사용 안 함** |

시스템 설정 → 에너지:

| 항목 | 값 |
|---|---|
| 디스플레이가 꺼져 있을 때 컴퓨터 자동 잠자기 방지 | **켬** |
| 전원이 차단되었다가 들어오면 자동 시동 | **켬** |
| 네트워크 접근 시 깨우기 | **켬** |

> ⚠️ macmini 가 sleep 에 들어가면 운영자 측 새벽 backup 이 실패합니다. 위 설정 누락 = 함정 1 위.

## 3. Tailscale 가입 + macmini 합류 (10분)

Tailscale 은 운영자가 macmini 에 push deploy 하기 위한 mesh VPN. 공개 IP / 포트 오픈 불필요.

### 3-1. Tailscale 계정 생성

[https://tailscale.com/start](https://tailscale.com/start) → 회사 메일 (`it@{customer}.com` 등) 로 가입. SSO 가능 (Google / Microsoft).

요금: 운영자 측 tailnet 에 합류하므로 귀사 측 별도 결제 X (운영자 부담).

### 3-2. macmini 에 Tailscale 설치

```bash
# Tailscale macOS app (App Store 또는 직접)
brew install --cask tailscale
# 또는 https://tailscale.com/download/macos 에서 .pkg 다운로드
```

설치 후 메뉴바 Tailscale 아이콘 → **Log in** → 위 가입한 계정으로 로그인.

### 3-3. 운영자 tailnet 합류

귀사 계정만으로는 운영자가 접근 못 함. 다음 둘 중 하나:

**A. tailnet share (권장)** — 운영자가 보낸 share link 수락
- 운영자 (`ai@axellc.com`) 에게 macmini 의 Tailscale email 알림
- 운영자가 share invite 발송 → 메일 수락 → 운영자 tailnet 에서 `{customer}-macmini` 가 보임

**B. 별도 tailnet + ACL** — Tailscale Business plan 필요 시
- 운영자에게 사전 협의

### 3-4. Tailscale IP 회신

```bash
tailscale ip -4
# 예: 100.114.161.51
```

이 IP 를 운영자에게 회신 (안전 채널 불필요 — Tailscale IP 는 ACL 로 보호).

## 4. SSH 활성화 + 운영자 key 등록 (5분)

### 4-1. SSH 활성화

시스템 설정 → 일반 → 공유 → **원격 로그인 (SSH)** = **켬**, 접근 = "모든 사용자" 또는 `{customer}` 사용자

### 4-2. 운영자 public key 받기

운영자가 자신의 public key (예: `ssh-ed25519 AAAAC3... ai@axellc.com`) 를 평문 메일로 전송합니다 (public key 는 비밀 X). 한 줄.

### 4-3. authorized_keys 등록

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo 'ssh-ed25519 AAAA...받은 운영자 키 한 줄 그대로... ai@axellc.com' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

### 4-4. SSH 테스트 (운영자가 실행)

운영자 측에서 `ssh {customer}@{customer}-macmini.tail<...>.ts.net 'whoami'` 가 `{customer}` 를 출력하면 성공. 귀사 측은 회신만 기다리면 됨.

> 💡 SSH 키쌍은 ed25519 권장 (RSA 보다 짧고 안전). 비밀번호 인증은 사용하지 않습니다 — key only.

## 5. Docker Desktop 설치 (5분)

운영자 측 push 후 macmini 에서 docker compose 가 실행됩니다.

```bash
brew install --cask docker
```

또는 [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/) 에서 Apple Silicon .dmg.

설치 후:
1. Docker Desktop 실행 → 마법사 (기본 설정 OK)
2. Resources → Memory 8GB+ 할당 (16GB RAM 기준; frame + blueprint + hive + vault 4 stack)
3. Settings → General → **"Start Docker Desktop when you sign in to your computer"** = ON

`docker ps` 가 빈 결과를 출력하면 정상.

## 6. Bitwarden CLI 설치 (3분)

운영자 측 `axe deploy ...` 자동화가 customer-side wrapper 를 통해 bw CLI 로 secret 을 조달합니다.

```bash
# Node.js 가 없으면 먼저 설치
brew install node

# bw CLI 표준 버전 = 2025.7.0 (반드시 이 버전)
npm install -g @bitwarden/cli@2025.7.0
bw --version    # 2025.7.0 확인
```

★ **`2025.7.0` 버전 pin 필수** — 최신 (`2026.4+`) 은 Vaultwarden Timshel SSO user 와 호환 깨짐 (`TypeError: toWrappedAccountCryptographicState`). 운영 표준은 2025.7.0 통일 ([D-ops-28](/ops/decisions), [상세](/architecture/secrets#bw-cli-표준-버전--202570-d-ops-28)).

설치 후 별도 로그인 불필요 — D-day 의 `bw-bootstrap.sh` 가 interactive 로 server URL + 계정 setup.

## 7. 기본 점검 회신

다음 한 줄을 운영자에게 회신:

```
{customer}-macmini 준비 완료
- macOS: 15.x.x
- Tailscale IP: 100.114.161.51
- SSH 사용자: {customer}
- Docker: 4.34.0 (running)
- bw CLI: 2025.7.0
- 절전: 비활성화됨
```

회신 즉시 운영자가 SSH probe 로 검증 → D-day 작업 가능 상태로 전환.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 절전 / 자동 잠금 비활성화 누락 | 새벽 backup / 모니터링 실패 | §2 모든 항목 OFF |
| 자동 macOS 업데이트 ON | 사전 협의 없이 reboot → 다운타임 | §1 OFF |
| 컴퓨터 이름이 `{customer}-macmini` 아님 | 운영자 측 customers.yaml 의 `tailscale_host` 불일치 | §1 step 2 |
| Tailscale 가입은 했으나 share invite 미수락 | 운영자가 macmini 못 봄 | §3-3 |
| SSH 활성화는 했으나 authorized_keys 등록 누락 | key auth 실패 | §4-3 |
| `authorized_keys` 의 권한이 644 | sshd 가 무시 (StrictModes) | `chmod 600` |
| Docker Desktop 미실행 (설치만 함) | `docker ps` 명령 실패 | 메뉴바에 docker 고래 아이콘 보이는지 확인 |
| bw CLI `2026.4+` 설치 | D-day `bw-bootstrap.sh` 가 `TypeError: toWrappedAccountCryptographicState` 로 crash | `npm install -g @bitwarden/cli@2025.7.0` 재설치 (§6) — 운영 표준 |
| 회사 방화벽이 Tailscale UDP 차단 | mesh 연결 안 됨 | Tailscale 41641/udp outbound 허용 — [공식 문서](https://tailscale.com/kb/1082/firewall-ports/) |

## 다음 단계

macmini 준비가 끝나면:
- [Microsoft Entra ID 앱 등록 (Option A — CLI 1 줄)](/partner/registration#option-a--cli-1-줄-권장)
- [DNS / 도메인 준비](/partner/domain-prep)
- [운영자에게 넘길 값](/partner/handoff)
- [배포 협의](/partner/deploy)