headscale-tailscale-replacement/README.md

# 🏥 PharmQ Headscale Network - Live Production

pharmq.kr 도메인을 사용하는 Headscale VPN 네트워크 구축 완료

## 🚀 클라이언트 자동 등록

### 한 줄 설치 (권장)
```bash
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/register-client-pharmq-live.sh | bash
```

### 다운로드 후 설치
```bash
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/register-client-pharmq-live.sh -o register-client.sh
chmod +x register-client.sh
./register-client.sh
```

### 📋 스크립트 파일 직접 다운로드
- [register-client-pharmq-live.sh](./register-client-pharmq-live.sh) - 클라이언트 자동 등록 스크립트

## 🌐 서비스 주소

### 메인 서비스
- **Headscale 서버**: http://head.pharmq.kr:8070
- **관리자 대시보드**: http://head.pharmq.kr:5001

### 개발/테스트 (내부용)
- **Headscale**: http://192.168.0.100:8070
- **farmq-admin**: http://192.168.0.100:5001

## 📊 네트워크 정보

- **네트워크 대역**: 100.64.0.0/10
- **IPv6 대역**: fd7a:115c:a1e0::/48
- **Magic DNS**: headscale.local
- **기본 사용자**: default

## 🔧 관리자 도구

### farmq-admin 웹 GUI
- 사용자 관리
- 머신/노드 관리
- 실시간 네트워크 모니터링
- Headscale CLI API 래퍼

### 주요 기능
- ✅ Docker 기반 Headscale 서버
- ✅ 웹 기반 관리 인터페이스
- ✅ 자동 클라이언트 등록 스크립트
- ✅ 1년 유효 재사용 가능 preauth key
- ✅ Magic DNS 지원

## 📋 클라이언트 등록 과정

1. **스크립트 실행**: 위 curl 명령어 실행
2. **Tailscale 자동 설치**: 시스템에 맞게 설치
3. **Headscale 서버 연결**: head.pharmq.kr 연결
4. **자동 인증**: preauth key로 즉시 승인
5. **네트워크 참여**: Tailscale IP 할당 완료

## 🛠️ 기술 스택

- **Headscale**: v0.26.1 (Docker)
- **farmq-admin**: Flask + SQLAlchemy
- **Database**: SQLite3
- **Frontend**: HTML/CSS/JavaScript
- **Network**: Tailscale protocol

## 📁 파일 구조
```
headscale-setup/
├── docker-compose.yml    # Docker Compose 설정
├── .env                  # 환경변수 (복사 필요)
├── .env.example          # 환경변수 템플릿
├── start.sh             # 자동 설치 스크립트
├── README.md            # 이 문서
├── .gitignore           # Git 제외 파일
├── config/
│   └── config.yaml      # Headscale 설정
├── data/                # 데이터베이스 및 키 파일 (자동 생성)
└── run/                 # 런타임 파일 (자동 생성)
```

## 🚀 Git Repository
- **저장소**: https://git.0bin.in/thug0bin/headscale-tailscale-replacement
- **관리자**: 시골약사 (thug0bin@gmail.com)

## 🚀 빠른 시작

### 1. 환경변수 설정
```bash
# .env.example을 .env로 복사
cp .env.example .env
```

### 2. 자동 설치 (권장)
```bash
# 실행 권한 부여 및 실행
chmod +x ./start.sh
./start.sh
```

### 3. 수동 설치
```bash
# 1. Headscale 시작
docker-compose up -d headscale

# 2. API 키 생성
docker-compose exec headscale headscale apikeys create

# 3. .env 파일에 API 키 입력 (HEADSCALE_API_KEY 값 수정)
vi .env

# 4. Headplane 시작
docker-compose up -d headplane
```

## 📋 접속 정보
- **Headscale API**: http://localhost:8070
- **Headplane UI**: http://localhost:3000

## 👤 사용자 관리

### 사용자 생성
```bash
docker-compose exec headscale headscale users create myuser
```

### Pre-auth 키 생성
```bash
docker-compose exec headscale headscale preauthkeys create --user myuser --reusable --expiration 24h
```

## 📱 클라이언트 연결

### Linux/macOS
```bash
# Tailscale 클라이언트 설치 후
tailscale up --login-server=http://localhost:8080
```

### Windows
```cmd
tailscale up --login-server=http://localhost:8080
```

## 🔧 유용한 명령어

### 상태 확인
```bash
docker-compose ps
docker-compose logs -f
```

### 노드 목록 확인
```bash
docker-compose exec headscale headscale nodes list
```

### 사용자 목록 확인
```bash
docker-compose exec headscale headscale users list
```

## 🛠️ 트러블슈팅

### 컨테이너 재시작
```bash
docker-compose restart
```

### 로그 확인
```bash
docker-compose logs headscale
docker-compose logs headplane
```

### 완전 초기화
```bash
docker-compose down
sudo rm -rf data/*
docker-compose up -d
```

## 🔄 Git 관리
필요시 수동으로 Git 커밋을 진행하세요:

```bash
# 현재 상태 확인
git status

# 변경사항 커밋
git add .
git commit -m "Update: 설명"
git push origin main
```

## ⚡ 새 서버 원클릭 등록

새로운 리눅스 서버를 팜큐 네트워크에 **한 번의 명령**으로 등록:

### 빠른 설치 (권장)
```bash
# 일반 사용자 계정
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/quick-install.sh | sudo bash

# root 계정 (Proxmox 등)
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/quick-install.sh | bash
```

### 기존 Tailscale 연결이 있는 경우 (강제 재등록)
```bash
# 일반 사용자
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/quick-install.sh | sudo bash -s -- --force

# root 계정
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/quick-install.sh | bash -s -- --force
```

### 지원 OS
- Ubuntu, Debian, CentOS, RHEL, Rocky Linux, Fedora, Arch Linux
- 자동 Tailscale 설치 + Headscale 등록
- 방화벽 자동 설정 + 연결 검증

**30초 만에 팜큐 네트워크 연결 완료!** 🎉

## 🪟 Windows 원클릭 등록

Windows PC에서 **한 번의 복사 붙여넣기**로 팜큐 네트워크 연결:

### 기본 설치 (권장) - 인코딩 문제 해결됨
```powershell
# 관리자 PowerShell에서 복사 붙여넣기 (English version - 한글 깨짐 해결)
iex ((New-Object System.Net.WebClient).DownloadString('https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/farmq-install-en.ps1'))
```

### 기존 Tailscale 있는 경우 (강제 재등록)  
```powershell
# 기존 연결을 자동으로 해제하고 재등록 (English version)
$Force = $true; iex ((New-Object System.Net.WebClient).DownloadString('https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/farmq-install-en.ps1'))
```

### 한글 버전 (인코딩 문제 발생 가능)
```powershell
# 한글이 깨져 보일 수 있음 - 위 English 버전 권장
iex ((New-Object System.Net.WebClient).DownloadString('https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/farmq-install.ps1'))
```

### 실행 방법
1. **Windows 키 + X** → **"Windows PowerShell(관리자)"** 클릭
2. 위 명령어 **복사 → 붙여넣기 → Enter**
3. 자동 설치 진행 (2-3분)
4. 팜큐 네트워크 연결 완료! 🎉

### Windows 자동 처리 기능
- ✅ **Tailscale 자동 다운로드** 및 설치
- ✅ **관리자 권한** 자동 확인
- ✅ **기존 연결 스마트 처리** (Linux와 동일)
- ✅ **Windows Defender 방화벽** 자동 설정
- ✅ **네트워크 연결 테스트** 및 확인

## 💻 개발 환경 설정 (code-server)

팜큐 네트워크에 연결된 서버에서 **웹 기반 VS Code 개발 환경**을 빠르게 구축:

### 한 줄 설치 (권장)
```bash
# 기본 포트 8080으로 설치
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/docs/code-server.sh | bash

# 포트 지정 설치 (예: 8443)
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/docs/code-server.sh | PORT=8443 bash
```

### 무인 설치 (비밀번호 환경변수 설정)
```bash
# 비밀번호를 환경변수로 전달
curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/live/pharmq-headscale-production/docs/code-server.sh | PASSWORD="your-secure-password" SKIP_CONFIRM=1 bash
```

### 자동 설치 기능
- ✅ **code-server 자동 설치** (미설치 시)
- ✅ **설정 파일 자동 생성** 및 구성
- ✅ **기존 프로세스 정리** (중복 실행 방지)
- ✅ **0.0.0.0 바인딩** (외부 접속 가능)
- ✅ **nohup 백그라운드 실행** (세션 종료 후에도 유지)

### 설치 후 접속
```bash
# 브라우저에서 접속
http://<서버IP>:8080

# 로그 확인
tail -f ~/code-server.log
```

### 보안 권장사항
- 🔒 **역프록시 사용**: Caddy 또는 Nginx로 HTTPS 설정
- 🔒 **강력한 비밀번호**: 복잡한 비밀번호 사용
- 🔒 **방화벽 설정**: 필요한 IP만 접근 허용
- 🔒 **VPN 접속**: 팜큐 네트워크 내부에서만 접속