tailscale-custom/DEPLOYMENT.md

📦 Hướng Dẫn Triển Khai Tailscale Custom Admin Panel

🚀 Triển Khai Nhanh (Quick Start)

1. Tạo File .env

# Production deployment
cat > .env << 'EOF'
HEADSCALE_API_KEY=<generated-api-key-from-headscale>
ADMIN_PASSWORD=<strong-password-min-12-chars>
TLS_CERT_FILE=/certs/cert.pem
TLS_KEY_FILE=/certs/key.pem
TLS_CERT_DIR=./certs
EOF

2. Tạo Certificates (Self-signed)

mkdir -p certs
cd certs

# Self-signed certificate (tự ký)
openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem \
  -out cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"

cd ..

3. Khởi Động với Docker Compose

# Load environment variables
export HEADSCALE_API_KEY="your-api-key"
export ADMIN_PASSWORD="YourStrongPassword123!"

# Start services
docker compose up -d

# Kiểm tra logs
docker compose logs -f headscale-admin

4. Truy Cập Admin Panel

https://localhost:9080
Username: admin
Password: YourStrongPassword123!

---

🔐 Biến Môi Trường (Environment Variables)

Bắt Buộc (Required)

Biến	Mô Tả	Ví Dụ
ADMIN_PASSWORD	Mật khẩu admin (min 12 chars)	SecurePass2024!
HEADSCALE_API_KEY	API key từ Headscale	ts_prd_...

Tùy Chọn (Optional)

Biến	Mặc Định	Mô Tả
HEADSCALE_URL	http://headscale:8080	URL Headscale server
LISTEN_ADDR	:9080	Port admin panel
DATA_DIR	/data	Thư mục lưu users.json
TLS_CERT_FILE	(none)	Đường dẫn certificate
TLS_KEY_FILE	(none)	Đường dẫn private key

---

📋 Danh Sách Kiểm Tra Triển Khai (Pre-Deployment Checklist)

• HEADSCALE_API_KEY được cấu hình

  # Lấy từ Headscale
  headscale apikey create
  

• ADMIN_PASSWORD được đặt mạnh (min 12 chars, mixed case, numbers, symbols)

  # Tạo mật khẩu mạnh
  openssl rand -base64 16
  

• TLS Certificates được tạo

  ls -la certs/cert.pem certs/key.pem
  

• Docker image được build lại

  docker compose build --no-cache
  

• Ports khả dụng

  netstat -ln | grep 9080  # Không output = port free
  

• .env file có permissions chính xác

  chmod 600 .env
  

---

✅ Kiểm Tra Sau Triển Khai (Post-Deployment Verification)

1. Kiểm Tra Dịch Vụ Hoạt Động

# Kiểm tra containers
docker compose ps
# Nên thấy: headscale ✓, headscale-admin ✓

# Kiểm tra logs
docker compose logs headscale-admin | tail -20
# Nên thấy: "Headscale Web Admin starting on :9080"

2. Kiểm Tra HTTPS

# Test TLS connection
openssl s_client -connect localhost:9080 -showcerts
# Hoặc
curl -v --insecure https://localhost:9080/
# Nên thấy: TLS Handshake success

3. Kiểm Tra Đăng Nhập

# Attempt login
curl -X POST https://localhost:9080/api/auth/login \
  --insecure \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YOUR_PASSWORD"}'

# Nên nhận về token

4. Kiểm Tra Rate Limiting

#!/bin/bash
# Thử 6 lần đăng nhập sai liên tiếp
for i in {1..6}; do
  echo "Attempt $i:"
  curl -s -X POST https://localhost:9080/api/auth/login \
    --insecure \
    -H "Content-Type: application/json" \
    -d '{"username":"admin","password":"wrongpassword"}' | jq '.error'
done

# Kết quả mong đợi:
# Attempts 1-5: "invalid credentials"
# Attempt 6: "account temporarily locked..."

---

🔄 Nâng Cấp & Rollback

Cập Nhật Code

# Pull latest changes
git pull origin main

# Rebuild docker image
docker compose down
docker compose build --no-cache

# Start with new code
docker compose up -d

# Verify
docker compose logs headscale-admin

Rollback (Quay Lại Phiên Bản Trước)

# Restore from git
git checkout HEAD~1
docker compose down
docker compose build --no-cache
docker compose up -d

Backup Data

# Backup users.json
docker compose exec headscale-admin \
  cp /data/users.json /data/users.json.backup

# Restore
docker compose exec headscale-admin \
  cp /data/users.json.backup /data/users.json

---

🛡️ Bảo Mật Tối Ưu (Security Hardening)

Sử Dụng Let's Encrypt Certificates

# Install Certbot
apt-get install certbot python3-certbot-dns-<your-provider>

# Get certificate
certbot certonly --dns-<provider> -d vpn.softs.business

# Update docker-compose.yml
export TLS_CERT_FILE="/etc/letsencrypt/live/vpn.softs.business/fullchain.pem"
export TLS_KEY_FILE="/etc/letsencrypt/live/vpn.softs.business/privkey.pem"

# Restart
docker compose down
docker compose up -d

Firewall Configuration

# UFW (Ubuntu)
ufw allow 9080/tcp
ufw allow 9080/udp

# iptables
iptables -A INPUT -p tcp --dport 9080 -j ACCEPT

Nginx Reverse Proxy

server {
    listen 443 ssl;
    server_name vpn.softs.business;

    ssl_certificate /etc/letsencrypt/live/vpn.softs.business/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.softs.business/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass https://localhost:9080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

📊 Monitoring

Kiểm Tra CPU/Memory Usage

docker stats headscale-admin

Xem Logs Real-time

docker compose logs -f headscale-admin

Kiểm Tra Disk Space

docker exec headscale-admin du -sh /data

---

🆘 Khắc Phục Sự Cố (Troubleshooting)

Problem: "ADMIN_PASSWORD is required"

Giải pháp: Đặt biến môi trường

export ADMIN_PASSWORD="YourPassword"
docker compose up -d

Problem: "TLS: certificate required"

Giải pháp: Tạo certificates

./create-certs.sh
docker compose restart headscale-admin

Problem: "Connection refused" (9080)

Giải pháp: Kiểm tra port

netstat -ln | grep 9080
docker compose logs headscale-admin

Problem: "Invalid username/password"

Giải pháp: Reset password

# Xóa users.json để reset admin account
docker exec headscale-admin rm /data/users.json
docker compose restart headscale-admin

---

📞 Support

Gặp vấn đề? Hãy kiểm tra:

1. Logs: docker compose logs headscale-admin
2. Environment variables: docker compose config
3. Certificates: openssl x509 -in certs/cert.pem -text
4. Security fixes: Xem SECURITY_FIXES.md

---

Phiên Bản: 1.0
Cập Nhật Lần Cuối: 2026-04-22
Status: ✅ Production Ready