Ringkasan
Artikel ini membahas proses setup auto-deploy untuk aplikasi Django yang berada di server privat (Tailscale) menggunakan GitHub Webhook dan Cloudflare Tunnel. Server tidak memiliki IP publik, sehingga Cloudflare Tunnel digunakan sebagai jembatan antara GitHub dan server internal.
Topik yang dibahas: 1. Arsitektur auto-deploy dengan Cloudflare Tunnel 2. Webhook listener berbasis Python stdlib 3. Deploy script untuk Django + Tailwind CSS 4. Konfigurasi Cloudflare Tunnel (remote managed) 5. Troubleshooting yang dihadapi selama proses setup
1. Masalah: Server tanpa IP Publik
Sebagian besar tutorial auto-deploy mengasumsikan server memiliki IP publik. Namun dalam kasus ini, server Codenest berada di belakang Tailscale — sebuah jaringan privat yang hanya bisa diakses dari perangkat yang terdaftar.
Artinya, GitHub tidak bisa mengirim webhook langsung ke server. Diperlukan sebuah jembatan yang bisa diakses dari internet namun tetap meneruskan traffic ke server internal.
Solusinya: Cloudflare Tunnel.
Cloudflare Tunnel sudah digunakan untuk melayani traffic codenest.id (website utama). Tunnel yang sama bisa digunakan untuk meneruskan traffic webhook ke port terpisah di server yang sama.
2. Arsitektur
Berikut flow auto-deploy yang diimplementasikan:
┌──────────┐ POST /webhook ┌──────────────────┐
│ GitHub │ ──────────────────► │ Cloudflare │
│ (push) │ │ Edge Network │
└──────────┘ └────────┬─────────┘
│
│ Cloudflare Tunnel
│ (via QUIC protocol)
▼
┌──────────────────┐
│ webhook. │
│ codenest.id │
└────────┬─────────┘
│
│ localhost:9000
▼
┌──────────────────┐
│ Webhook │
│ Listener │
│ (Python) │
└────────┬─────────┘
│
│ verify HMAC signature
│ run deploy.sh
▼
┌──────────────────┐
│ deploy.sh │
│ │
│ git pull │
│ pip install │
│ npm install │
│ npm run build │
│ collectstatic │
│ migrate │
│ pm2 restart │
└──────────────────┘
Kenapa Cloudflare Tunnel?
Cloudflare Tunnel memiliki beberapa keunggulan untuk skenario ini:
- Tidak perlu buka port — Tunnel menginisiate koneksi keluar dari server ke Cloudflare, sehingga firewall tidak perlu dikonfigurasi.
- Sudah terpasang — Tunnel
codenest-djangosudah berjalan untuk melayani website utama. - Gratis — Tidak memerlukan plan berbayar.
- SSL otomatis — HTTPS diurus oleh Cloudflare.
Kenapa bukan opsi lain?
Alternatif yang sempat dipertimbangkan:
- Cron job — Pull otomatis tiap X menit. Kelemahannya: delay antara push dan deploy, tidak real-time.
- GitHub Actions + SSH — GitHub trigger SSH ke server. Kelemahannya: butuh SSH key di GitHub Secrets, lebih kompleks.
- Tailscale Funnel — Expose port via Tailscale. Kelemahannya: masih perlu setup tambahan, belum familiar.
GitHub Webhook + Cloudflare Tunnel dipilih karena paling real-time dan memanfaatkan infrastruktur yang sudah ada.
3. Webhook Listener
Webhook listener adalah komponen utama yang menerima POST request dari GitHub, memverifikasi keaslian request, dan menjalankan deploy script.
Kenapa Python?
Webhook listener ditulis menggunakan Python standard library (http.server + hmac). Tidak ada dependensi tambahan yang perlu di-install. Alasannya:
- Server sudah punya Python (Django app)
- Tidak perlu
pip installpackage tambahan - Cukup ringan untuk satu endpoint saja
Kode Lengkap
#!/usr/bin/env python3
"""
GitHub Webhook listener for auto-deploy.
Listens on port 9000, verifies HMAC-SHA256 signature, runs deploy.sh.
"""
import hashlib
import hmac
import json
import os
import subprocess
import sys
from datetime import datetime
from http.server import HTTPServer, BaseHTTPRequestHandler
from pathlib import Path
HOST = "0.0.0.0"
PORT = 9000
WEBHOOK_PATH = "/webhook"
DEPLOY_SCRIPT = Path(__file__).parent / "deploy.sh"
def log(msg):
ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
print(f"[{ts}] {msg}", flush=True)
def get_webhook_secret():
secret = os.environ.get("WEBHOOK_SECRET", "")
if not secret:
env_file = Path(__file__).parent / ".env"
if env_file.exists():
for line in env_file.read_text().splitlines():
if line.startswith("WEBHOOK_SECRET="):
secret = line.split("=", 1)[1].strip().strip('"').strip("'")
break
if not secret:
log("WARNING: WEBHOOK_SECRET not set! Rejecting all requests.")
return secret
def verify_signature(payload_body, signature_header, secret):
if not signature_header or not secret:
return False
expected = "sha256=" + hmac.new(
secret.encode(), payload_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)
class WebhookHandler(BaseHTTPRequestHandler):
def do_POST(self):
if self.path != WEBHOOK_PATH:
self.send_response(404)
self.end_headers()
return
content_length = int(self.headers.get("Content-Length", 0))
if content_length == 0:
self.send_response(400)
self.end_headers()
return
body = self.rfile.read(content_length)
signature = self.headers.get("X-Hub-Signature-256", "")
event = self.headers.get("X-GitHub-Event", "unknown")
secret = get_webhook_secret()
# Verify HMAC-SHA256 signature dari GitHub
if not verify_signature(body, signature, secret):
log("REJECTED: Invalid or missing webhook signature")
self.send_response(403)
self.end_headers()
self.wfile.write(b"Invalid signature")
return
# Handle ping event (saat webhook pertama kali ditambahkan)
if event == "ping":
log("Received ping event")
self.send_response(200)
self.end_headers()
self.wfile.write(b"Pong")
return
# Ignore selain push event
if event != "push":
log(f"Ignored event: {event}")
self.send_response(200)
self.end_headers()
self.wfile.write(b"Ignored")
return
# Parse payload
try:
payload = json.loads(body)
branch = payload.get("ref", "")
repo = payload.get("repository", {}).get("full_name", "")
pusher = payload.get("pusher", {}).get("name", "unknown")
except json.JSONDecodeError:
payload = {}
branch = ""
repo = ""
pusher = "unknown"
log(f"Push to {repo} by {pusher} (branch: {branch})")
# Hanya deploy jika push ke branch main
if branch != "refs/heads/main":
log(f"Ignored push to non-main branch: {branch}")
self.send_response(200)
self.end_headers()
self.wfile.write(b"Ignored non-main branch")
return
# Jalankan deploy script
log("Running deploy...")
try:
result = subprocess.run(
["/bin/bash", str(DEPLOY_SCRIPT)],
capture_output=True,
text=True,
timeout=300,
)
if result.returncode == 0:
log("Deploy succeeded!")
self.send_response(200)
self.end_headers()
self.wfile.write(b"Deploy OK")
else:
log(f"Deploy failed: {result.stderr[-500:]}")
self.send_response(500)
self.end_headers()
self.wfile.write(b"Deploy failed")
except subprocess.TimeoutExpired:
log("Deploy timed out (5 min)")
self.send_response(500)
self.end_headers()
self.wfile.write(b"Deploy timeout")
except Exception as e:
log(f"Deploy error: {e}")
self.send_response(500)
self.end_headers()
self.wfile.write(b"Deploy error")
def do_GET(self):
if self.path == "/health":
self.send_response(200)
self.end_headers()
self.wfile.write(b"OK")
else:
self.send_response(404)
self.end_headers()
def log_message(self, format, *args):
log(f"{self.client_address[0]} - {format % args}")
def main():
secret = get_webhook_secret()
if secret:
log(f"Webhook secret loaded ({len(secret)} chars)")
else:
log("WARNING: Running without webhook secret verification!")
server = HTTPServer((HOST, PORT), WebhookHandler)
log(f"Webhook listener started on {HOST}:{PORT}")
log(f"Webhook URL: http://your-server:{PORT}{WEBHOOK_PATH}")
log(f"Health check: http://your-server:{PORT}/health")
try:
server.serve_forever()
except KeyboardInterrupt:
log("Shutting down...")
server.shutdown()
if __name__ == "__main__":
main()
Penjelasan Alur
-
Menerima request POST — Listener hanya menerima request di path
/webhook. Request lain akan mendapat 404. -
Verifikasi HMAC-SHA256 — GitHub mengirim signature di header
X-Hub-Signature-256. Listener menghitung ulang signature menggunakanWEBHOOK_SECRETdan membandingkan denganhmac.compare_digest()(timing-safe comparison). -
Handle ping event — Saat webhook pertama kali ditambahkan di GitHub, GitHub mengirim ping event. Listener membalas "Pong".
-
Filter branch — Hanya push ke
refs/heads/mainyang di-deploy. Push ke branch lain di-ignore. -
Jalankan deploy.sh — Deploy script dijalankan via
subprocess.run()dengan timeout 5 menit. Output di-capture untuk logging. -
Health check endpoint —
GET /healthmengembalikan "OK" untuk monitoring.
Running via PM2
# Generate webhook secret
echo "WEBHOOK_SECRET=$(python3 -c 'import secrets; print(secrets.token_hex(32))')" >> /var/Django/.env
# Jalankan via PM2
pm2 start webhook_listener.py --name webhook --interpreter python3
pm2 save
4. Deploy Script
Deploy script menjalankan serangkaian langkah post-pull untuk memastikan aplikasi dalam keadaan terbaru.
#!/bin/bash
set -euo pipefail
cd /var/Django
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Deploy started..."
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Pulling latest code..."
git pull origin main
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Installing Python dependencies..."
source venv/bin/activate
pip install -r requirements.txt -q
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Installing npm dependencies..."
npm install
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Building Tailwind CSS..."
npm run build
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Collecting static files..."
python manage.py collectstatic --noinput
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Running migrations..."
python manage.py migrate --noinput
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Restarting Gunicorn..."
pm2 restart codenest
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Deploy completed!"
Penjelasan Setiap Step
| Step | Command | Kenapa |
|---|---|---|
| 1 | git pull origin main |
Ambil kode terbaru dari GitHub |
| 2 | pip install -r requirements.txt |
Install/update Python dependencies |
| 3 | npm install |
Install Node.js dependencies (termasuk Tailwind CLI) |
| 4 | npm run build |
Compile Tailwind CSS → output CSS yang sudah di-minify |
| 5 | collectstatic |
Kumpulkan semua static files ke folder staticfiles/ |
| 6 | migrate |
Jalankan database migration yang belum dijalankan |
| 7 | pm2 restart codenest |
Restart Gunicorn agar kode baru aktif |
Kenapa npm install harus ada?
Tailwind CSS dijalankan sebagai CLI tool (@tailwindcss/cli). Tool ini diinstal sebagai devDependency di package.json. Tanpa npm install, command npm run build akan gagal karena binary-nya belum ada.
Pertama kali kami menjalankan deploy tanpa npm install, error yang muncul:
Error: Can't resolve 'tailwindcss' in '/var/Django/static/css'
5. Konfigurasi Cloudflare Tunnel
Remote Managed vs Local Config
Cloudflare Tunnel memiliki dua mode konfigurasi:
- Remote Managed — Konfigurasi disimpan di Cloudflare Dashboard. Lebih mudah dikelola tapi tidak bisa diedit dari command line.
- Local Config — Konfigurasi disimpan di file
config.ymldi server. Bisa diedit manual.
Kami menggunakan Remote Managed karena lebih praktis. Artinya, editing file config.yml di server tidak akan berpengaruh — konfigurasi harus diubah dari Cloudflare Zero Trust Dashboard.
Menambah Hostname via Dashboard
- Buka Cloudflare Zero Trust Dashboard → Networks → Tunnels
- Klik tunnel codenest-django → Configure
- Tab Public Hostnames → Add a public hostname
- Isi form:
- Subdomain:
webhook - Domain:
codenest.id - Service Type:
HTTP - URL:
localhost:9000 - Save hostname
DNS Record
Cloudflare secara otomatis membuat CNAME record saat hostname ditambahkan:
webhook.codenest.id → 8afgh427-e748-450b-bbc3-e4cd100f0670.cfargotunnel.com
Record ini mengarahkan traffic ke Cloudflare Tunnel, yang kemudian diteruskan ke localhost:9000 di server.
Verifikasi Tunnel
# Cek dari server
curl http://localhost:9000/health
# Output: OK
# Cek via tunnel
curl https://webhook.codenest.id/health
# Output: OK
6. Konfigurasi GitHub Webhook
Langkah Setup
- Buka repo di GitHub → Settings → Webhooks
- Klik Add webhook
- Isi form:
- Payload URL:
https://webhook.codenest.id/webhook - Content type:
application/json - Secret: (paste nilai
WEBHOOK_SECRETdari.env) - SSL verification: Enable SSL verification
- Events: Just the push event
- Klik Add webhook
Jenis Events
GitHub mengirim beberapa jenis event ke webhook:
- ping — Dikirim saat webhook pertama kali ditambahkan. Listener membalas "Pong".
- push — Dikirim saat ada push ke repo. Ini yang memicu deploy.
- pull_request, release, dll — Di-ignore oleh listener.
7. Troubleshooting
Selama proses setup, beberapa masalah yang dihadapi:
Masalah 1: SSH Key antara Local dan Server Berbeda
Server dan local machine memiliki SSH key yang berbeda. Key di local (id_ed25519) tidak terdaftar di GitHub, sementara key di server (yang baru di-generate) juga belum tentu terdaftar.
Solusi: Pastikan SSH key dari kedua mesin terdaftar di GitHub. Bisa ditambahkan beberapa sekaligus di Settings → SSH and GPG keys.
# Cek key di local
cat ~/.ssh/id_ed25519.pub
# Cek key di server
cat ~/.ssh/id_ed25519.pub
# Test koneksi
ssh -T [email protected]
Masalah 2: input.css Tidak Ditemukan
File input.css (source file Tailwind) sebelumnya berada di folder static-unused/css/ karena kesalahan penempatan. package.json mereferensikan static/css/input.css, sehingga npm run build gagal.
Solusi: Pindahkan file ke path yang benar.
# Sebelumnya salah
ls static-unused/css/input.css
# Pindahkan ke lokasi yang benar
mkdir -p static/css
cp static-unused/css/input.css static/css/input.css
Masalah 3: npm install --omit=dev Skip TailwindCSS
Awalnya deploy script menggunakan npm install --omit=dev untuk menghemat waktu install. Namun karena tailwindcss dan @tailwindcss/cli terdaftar sebagai devDependencies di package.json, mereka tidak ter-install.
Solusi: Ganti menjadi npm install (install semua dependencies termasuk dev).
# Sebelumnya (salah)
npm install --omit=dev
# Sesudahnya (benar)
npm install
Masalah 4: Cloudflare Tunnel Remote Managed
Kami mengedit config.yml di server untuk menambahkan route webhook, namun perubahan tidak berpengaruh. Ternyata tunnel dikonfigurasi sebagai Remote Managed dari Cloudflare Dashboard, sehingga config local diabaikan.
Solusi: Tambahkan hostname via Cloudflare Zero Trust Dashboard, bukan dari command line.
Masalah 5: GitHub Webhook Ping Gagal
Saat pertama kali menambahkan webhook, GitHub mengirim ping event yang gagal diterima. Ini karena: 1. DNS record belum di-add 2. Cloudflare Tunnel belum di-restart 3. Webhook listener belum berjalan
Solusi: Pastikan semua komponen sudah berjalan, lalu klik Redeliver di GitHub webhook settings untuk mengirim ulang ping.
8. Monitoring
PM2
# Cek status semua proses
pm2 list
# Cek log webhook listener
pm2 logs webhook --lines 20
# Cek log deploy (dari webhook listener)
pm2 logs webhook --lines 50 | grep "Deploy"
Log Output
Log webhook listener menampilkan informasi seperti:
[2026-07-15 00:00:58] Push to endogh/codenest-django by endogh (branch: refs/heads/main)
[2026-07-15 00:00:58] Running deploy...
[2026-07-15 00:01:05] Deploy succeeded!
Jika deploy gagal, log akan menampilkan error message:
[2026-07-15 00:01:05] Deploy failed: Error: Can't resolve 'tailwindcss'
Health Check
# Dari server
curl http://localhost:9000/health
# Output: OK
# Dari luar (via tunnel)
curl https://webhook.codenest.id/health
# Output: OK
9. Keamanan
Keamanan adalah aspek kritis dalam auto-deploy. Berikut lapisan keamanan yang diterapkan:
HMAC-SHA256 Signature Verification
GitHub menandatangani setiap webhook payload dengan secret yang hanya diketahui GitHub dan pemilik repo. Signature dikirim di header X-Hub-Signature-256 dalam format:
sha256=<hex-digest>
Webhook listener menghitung ulang signature menggunakan secret yang sama dan membandingkan dengan hmac.compare_digest(). Fungsi ini menggunakan timing-safe comparison untuk mencegah timing attack.
def verify_signature(payload_body, signature_header, secret):
if not signature_header or not secret:
return False
expected = "sha256=" + hmac.new(
secret.encode(), payload_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)
Firewall: Tidak ada port yang dibuka
Webhook listener berjalan di port 9000, namun port ini tidak di-expose ke publik. Akses dari luar hanya melalui Cloudflare Tunnel, yang dikontrol oleh konfigurasi DNS dan tunnel di Cloudflare Dashboard.
Jika Cloudflare Tunnel dimatikan atau DNS record dihapus, webhook listener tidak bisa diakses dari luar sama sekali.
Branch Filtering
Deploy hanya trigger untuk push ke branch main. Push ke branch lain (feature branch, staging, dll) di-ignore. Ini mencegah deploy tidak sengaja dari branch yang belum stabil.
if branch != "refs/heads/main":
log(f"Ignored push to non-main branch: {branch}")
self.send_response(200)
self.end_headers()
self.wfile.write(b"Ignored non-main branch")
return
Deploy Timeout
Deploy script dijalankan dengan timeout 5 menit. Jika deploy lebih lama dari itu (misalnya karena npm install timeout atau pip install hanging), process akan di-kill dan listener mengembalikan error 500.
result = subprocess.run(
["/bin/bash", str(DEPLOY_SCRIPT)],
capture_output=True,
text=True,
timeout=300, # 5 menit
)
Environment Variables
WEBHOOK_SECRET disimpan di file .env yang sudah di-.gitignore. Secret tidak pernah di-commit ke repository atau di-hardcode di source code.
10. Alternatif: Manual Deploy
Jika webhook belum di-setup atau sedang ada masalah, deploy bisa dilakukan secara manual di server:
cd /var/Django
# Pull latest code
git pull origin main
# Activate virtual environment
source venv/bin/activate
# Install/update dependencies
pip install -r requirements.txt -q
# Build Tailwind CSS
npm install
npm run build
# Collect static files
python manage.py collectstatic --noinput
# Run migrations
python manage.py migrate --noinput
# Restart application
pm2 restart codenest
Command ini sama persis dengan yang dijalankan oleh deploy.sh, hanya saja dilakukan secara manual.
11. Arsitektur Server
Berikut overview server Codenest setelah semua dikonfigurasi:
┌─────────────────────────────────────────┐
│ PM2 Process Manager │
│ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ codenest │ │ cloudflared │ │
│ │ (Gunicorn) │ │ (Tunnel) │ │
│ │ :77 │ │ │ │
│ └──────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ webhook │ │ nginx │ │
│ │ (Python) │ │ (reverse proxy)│ │
│ │ :90 │ │ :80 │ │
│ └──────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────┘
- Gunicorn (:7777) — Melayani aplikasi Django
- Nginx (:80) — Reverse proxy untuk Gunicorn, melayani static files
- Cloudflare Tunnel — Menghubungkan server ke Cloudflare edge network
- Webhook Listener (:9000) — Menerima webhook dari GitHub untuk auto-deploy
Port Usage
| Port | Service | Akses |
|---|---|---|
| 80 | Nginx | Public via Cloudflare Tunnel (codenest.id) |
| 7777 | Gunicorn | Internal (hanya dari Nginx) |
| 9000 | Webhook Listener | Public via Cloudflare Tunnel (webhook.codenest.id) |
PM2 Configuration
Semua proses dikelola oleh PM2 dengan auto-restart. Jika salah satu proses crash, PM2 akan otomatis me-restart-nya.
# Cek status semua proses
pm2 list
# Output:
# ┌─────┬────────────┬──────────┬──────┬─────────┬──────────┬────────┬─────────┬──────────┐
# │ id │ name │ mode │ ↺ │ status │ cpu │ memory │ user │ watching │
# ├─────┼────────────┼──────────┼──────┼─────────┼──────────┼────────┼─────────┼──────────┤
# │ 0 │ codenest │ fork │ 5 │ online │ 0% │ 45mb │ root │ disabled │
# │ 1 │ cloudflared│ fork │ 2 │ online │ 0% │ 12mb │ cloud.. │ disabled │
# │ 2 │ webhook │ fork │ 0 │ online │ 0% │ 8mb │ root │ disabled │
# └─────┴────────────┴──────────┴──────┴─────────┴──────────┴────────┴─────────┴──────────┘
12. Kesimpulan
Auto-deploy untuk Django di server privat bisa diimplementasikan dengan:
- Python stdlib sebagai webhook listener (tanpa dependensi tambahan)
- Cloudflare Tunnel sebagai jembatan GitHub → server
- PM2 untuk mengelola proses webhook listener
- HMAC-SHA256 untuk keamanan webhook
Yang terpenting dari setup ini adalah keamanan:
- Webhook hanya menerima request dengan signature valid
- Server tidak perlu membuka port ke publik
- Deploy hanya trigger untuk branch main
- Deploy timeout 5 menit untuk mencegah hang
Setup ini sudah berjalan di production untuk Codenest (codenest.id), dan setiap push ke main branch akan otomatis trigger deploy dalam hitungan detik.
Tips untuk yang mau coba
- Mulai dari yang sederhana — Webhook listener yang dibahas di artikel ini hanya ~180 baris Python. Tidak perlu framework berat untuk satu endpoint.
- Manfaatkan infrastruktur yang ada — Jika sudah pakai Cloudflare Tunnel untuk website, tambahkan satu hostname lagi untuk webhook. Gratis dan cepat.
- Gunakan PM2 untuk process management — PM2 memastikan webhook listener selalu berjalan, bahkan jika server restart.
- Jangan lupa webhook secret — Tanpa secret, siapa saja bisa trigger deploy dengan mengirim POST request ke endpoint webhook.
- Test sebelum push ke production — Selalu test deploy manual terlebih dahulu untuk memastikan semua dependency dan path sudah benar.
Tanggal: 15 Juli 2026 Tech Stack: Django 5.2, Python 3, Cloudflare Tunnel, PM2, Tailwind CSS v4, GitHub Webhooks OS: Debian 12 (Bookworm) on VPS Repo: github.com/endogh/codenest-django
Comments