headscale-tailscale-replacement/README.md

🚀 Headscale + Headplane Docker Setup

Tailscale을 완전히 대체하는 자체 호스팅 솔루션

📁 파일 구조

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. 환경변수 설정

# .env.example을 .env로 복사
cp .env.example .env

2. 자동 설치 (권장)

# 실행 권한 부여 및 실행
chmod +x ./start.sh
./start.sh

3. 수동 설치

# 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

👤 사용자 관리

사용자 생성

docker-compose exec headscale headscale users create myuser

Pre-auth 키 생성

docker-compose exec headscale headscale preauthkeys create --user myuser --reusable --expiration 24h

📱 클라이언트 연결

Linux/macOS

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

Windows

tailscale up --login-server=http://localhost:8080

🔧 유용한 명령어

상태 확인

docker-compose ps
docker-compose logs -f

노드 목록 확인

docker-compose exec headscale headscale nodes list

사용자 목록 확인

docker-compose exec headscale headscale users list

🛠️ 트러블슈팅

컨테이너 재시작

docker-compose restart

로그 확인

docker-compose logs headscale
docker-compose logs headplane

완전 초기화

docker-compose down
sudo rm -rf data/*
docker-compose up -d

🔄 Git 관리

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

# 현재 상태 확인
git status

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

⚡ 새 서버 원클릭 등록

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

빠른 설치 (권장)

curl -fsSL https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

또는 wget 사용

wget -qO- https://git.0bin.in/thug0bin/headscale-tailscale-replacement/raw/branch/feature/working-headscale-setup/quick-install.sh | sudo bash

지원 OS

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

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