headscale-tailscale-replacement/QUICK_INSTALL_GUIDE.md

# 🚀 팜큐 Headscale 원클릭 설치 가이드

새로운 리눅스 서버를 팜큐 네트워크에 **한 번의 명령**으로 등록하는 방법입니다.

## 🎯 원클릭 설치 명령어

### 방법 1: curl 사용 (권장)
```bash
# 일반 사용자 계정에서
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

# root 계정에서 (Proxmox, Docker 컨테이너 등)
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | bash
```

### 방법 2: wget 사용
```bash
# 일반 사용자 계정에서
wget -qO- https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

# root 계정에서
wget -qO- https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | bash
```

### 방법 3: 스크립트 다운로드 후 실행
```bash
wget https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh
chmod +x quick-install.sh
sudo ./quick-install.sh
```

### 방법 4: 기존 Tailscale 연결이 있는 경우 (강제 재등록)
```bash
# 일반 사용자 계정에서
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash -s -- --force

# root 계정에서 (Proxmox 등)
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | bash -s -- --force
```

### 방법 5: 스크립트 옵션 확인
```bash
# 사용 가능한 옵션 보기
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | bash -s -- --help
```

## ✨ 자동으로 수행되는 작업

### 1. 🔍 시스템 분석
- 운영체제 자동 감지 (Ubuntu, Debian, CentOS, RHEL, Rocky, Fedora, Arch)
- 시스템 요구사항 확인
- 네트워크 연결 상태 점검

### 2. 📦 Tailscale 설치
- **Ubuntu/Debian**: APT 리포지토리 추가 및 설치
- **CentOS/RHEL/Rocky**: YUM/DNF 리포지토리 추가 및 설치
- **Fedora**: DNF 패키지 관리자로 설치
- **Arch Linux**: Pacman으로 설치
- **기타 배포판**: Universal Binary 직접 다운로드

### 3. 🔧 서비스 설정
- systemd 서비스 자동 등록
- tailscaled 데몬 시작 및 활성화
- 서비스 상태 확인 및 오류 처리

### 4. 🌐 Headscale 등록
- Pre-auth Key를 사용한 자동 등록
- 팜큐 Headscale 서버 (`https://head.0bin.in`)에 연결
- DNS 및 라우팅 설정 자동 적용

### 5. 🔒 방화벽 설정
- UFW (Ubuntu/Debian) 자동 설정
- firewalld (CentOS/RHEL/Fedora) 자동 설정
- Tailscale 포트 (41641/UDP) 자동 허용

### 6. ✅ 연결 검증
- IP 주소 할당 확인
- 네트워크 연결 테스트
- 다른 노드와의 통신 확인

## 🖥️ 지원하는 운영체제

| OS | 버전 | 설치 방법 | 상태 |
|---|---|---|---|
| **Ubuntu** | 18.04+ | APT Repository | ✅ |
| **Debian** | 10+ | APT Repository | ✅ |
| **CentOS** | 7, 8, 9 | YUM/DNF Repository | ✅ |
| **RHEL** | 7, 8, 9 | YUM/DNF Repository | ✅ |
| **Rocky Linux** | 8, 9 | DNF Repository | ✅ |
| **AlmaLinux** | 8, 9 | DNF Repository | ✅ |
| **Fedora** | 35+ | DNF Package | ✅ |
| **Arch Linux** | Rolling | Pacman Package | ✅ |
| **기타 배포판** | - | Universal Binary | ⚠️ |

## 📋 설치 예시 출력

```bash
$ curl -fsSL https://git.0bin.in/.../quick-install.sh | sudo bash

============================================
팜큐(FARMQ) Headscale 원클릭 설치
============================================

📋 감지된 OS: ubuntu 22.04 (jammy)

🔧 시스템 요구사항 확인 중...
✅ 시스템 요구사항 확인 완료

🔧 Tailscale 클라이언트 설치 중...
📋 Ubuntu/Debian용 Tailscale 설치 중...
✅ Tailscale 설치 완료
📋 설치된 버전: 1.52.1

🔧 Tailscale 서비스 시작 중...
✅ Tailscaled 서비스가 실행 중입니다.

🔧 Headscale 서버에 등록 중...
📋 Headscale 서버: https://head.0bin.in
📋 Pre-auth Key: 8b3df41d***************
🔧 등록 명령 실행 중...
✅ Headscale 등록 성공!

🔧 방화벽 설정 확인 중...
📋 UFW 방화벽 감지됨
📋 Tailscale 트래픽 허용 중...
✅ 방화벽 설정 완료

🔧 연결 상태 확인 중...
✅ Headscale 네트워크 연결 완료!
📋 할당된 IPv4: 100.64.0.5
📋 할당된 IPv6: fd7a:115c:a1e0::5

🔧 네트워크 연결 테스트 중...
✅ 팜큐 네트워크(100.64.0.0/10) 연결 정상!

============================================
팜큐 Headscale 설치 완료!
============================================

🎉 설치가 성공적으로 완료되었습니다!

📋 시스템 정보:
   호스트명: pharmacy-server-01
   Tailscale IP: 100.64.0.5
   OS: ubuntu 22.04
   Headscale 서버: https://head.0bin.in

🔧 유용한 명령어:
   tailscale status       # 연결 상태 확인
   tailscale ip          # 할당된 IP 확인
   tailscale ping <node> # 다른 노드와 연결 테스트
   tailscale logout      # 네트워크에서 해제

🌐 팜큐 관리자 페이지:
   http://192.168.0.151:5002
   http://192.168.0.151:5002/vms (VM 관리)

============================================
설치 완료 - 팜큐 네트워크를 사용할 수 있습니다!
============================================
```

## 🔧 설치 후 확인 명령어

### 연결 상태 확인
```bash
tailscale status
```

### 할당된 IP 주소 확인
```bash
tailscale ip
```

### 네트워크 테스트
```bash
# 다른 노드로 ping 테스트
tailscale ping 100.64.0.1

# 또는 노드명으로 테스트
tailscale ping desktop-emjd1dc
```

### 서비스 상태 확인
```bash
systemctl status tailscaled
journalctl -u tailscaled -f  # 실시간 로그
```

## 🚨 문제해결

### 1. 설치 중 권한 오류
```bash
# 해결방법: sudo 권한으로 실행
sudo curl -fsSL https://git.0bin.in/.../quick-install.sh | sudo bash
```

### 2. 네트워크 연결 실패
```bash
# 방화벽 상태 확인
sudo ufw status
sudo firewall-cmd --list-all

# 수동 포트 허용
sudo ufw allow 41641/udp
sudo firewall-cmd --add-port=41641/udp --permanent
```

### 3. Pre-auth Key 만료
```bash
# 새로운 키 생성이 필요한 경우
# Headscale 서버에서 실행:
docker exec headscale headscale preauthkeys create --user 1 --expiration 7d --reusable
```

### 4. 수동 등록 필요시
```bash
# 자동 등록 실패 시 수동 실행
tailscale up --login-server="https://head.0bin.in" --authkey="YOUR_KEY_HERE"
```

## 📊 현재 네트워크 정보

- **Headscale 서버**: https://head.0bin.in
- **Flask 관리 페이지**: http://192.168.0.151:5002
- **네트워크 대역**: 100.64.0.0/10
- **Pre-auth Key 유효기간**: 7일 (재사용 가능)

## 🔄 기존 서버 업데이트

이미 등록된 서버에서 스크립트를 다시 실행하면:
1. 기존 연결 감지
2. 사용자 확인 후 재등록 옵션 제공
3. 또는 기존 연결 유지

## 📞 지원

문제가 발생하면 다음 정보와 함께 연락주세요:

1. **OS 정보**: `cat /etc/os-release`
2. **Tailscale 버전**: `tailscale version`
3. **오류 로그**: `journalctl -u tailscaled --no-pager`
4. **네트워크 상태**: `tailscale status`

---

**🎯 목표**: 새로운 서버를 30초 만에 팜큐 네트워크에 연결!