Cara Self-Host Server VPN NetBird di VPS

Manfaat self-hosting server VPN NetBird

Dengan melakukan self-hosting server VPN NetBird, control plane berada di VPS milik Anda. Komponen ini menyimpan daftar peer, menentukan mesin yang boleh mengakses mesin lain, dan membantu dua peer menemukan satu sama lain di balik NAT (network address translation). Tunnel tetap menggunakan WireGuard dan dienkripsi secara langsung di antara mesin Anda. Perbedaannya, tidak ada perusahaan eksternal yang menyimpan inventaris perangkat atau mengelola alur login Anda.

NetBird berada di antara dua konsep yang mungkin sudah Anda kenal. NetBird adalah overlay mesh, sehingga peer terhubung satu sama lain, bukan mengirim seluruh trafik melalui satu gateway. NetBird juga dapat di-host sendiri secara menyeluruh. Dalam hal ini, NetBird menjadi alternatif untuk Headscale, server control Tailscale yang dapat di-host sendiri. Jika Anda hanya pernah menjalankan tunnel dengan satu gateway, baca terlebih dahulu perbedaan antara WireGuard biasa dan overlay mesh. Model ini membantu Anda memahami bagian lain pada halaman ini.

Jika yang sebenarnya Anda inginkan adalah satu server sebagai jalur keluar seluruh trafik, mesh menyediakan komponen yang lebih banyak daripada yang diperlukan. VPN WireGuard biasa pada satu VPS atau exit node Tailscale dapat melakukan hal tersebut dengan komponen yang jauh lebih sedikit untuk dikelola.

Komponen yang sebenarnya dijalankan stack

Tata letaknya baru-baru ini berubah, dan sebagian besar tulisan lama masih menjelaskan tata letak sebelumnya. Per Agustus 2026, pada rilis v0.76.2, skrip quickstart secara default menulis file Compose dengan tiga service.

• netbird-server memuat API manajemen, service sinyal, relay dengan listener STUN tertanam, dan penyedia identitas tertanam. Pada rilis lama, komponen-komponen ini berada dalam container terpisah, sedangkan penyedia identitasnya adalah instalasi Zitadel terpisah yang harus Anda build terlebih dahulu.
• dashboard adalah konsol web admin.
• traefik melakukan terminasi TLS (transport layer security) dan meminta sertifikat dari Let's Encrypt saat pertama kali dijalankan.

Ada dua service tambahan yang tetap nonaktif kecuali Anda menjawab ya pada prompt. Service NetBird Proxy memublikasikan service internal pada hostname publik. CrowdSec memfilter trafik yang menyalahgunakan layanan. Keduanya tidak diperlukan untuk membangun mesh yang berfungsi, dan keduanya menggunakan memori pada server kecil.

Jika Anda berasal dari wg-easy dalam satu container Docker, jumlah komponennya meningkat cukup banyak. Keuntungannya adalah Anda mendapatkan kebijakan akses dan akun per pengguna, serta peer yang terhubung langsung satu sama lain, bukan melalui satu gateway.

Hal yang diperlukan sebelum memulai

Nama domain publik bukan pilihan. Dashboard, API, dan relay semuanya menggunakan HTTPS pada port 443. Traefik memperoleh sertifikat dari Let's Encrypt melalui HTTP challenge, yang memerlukan nama yang mengarah ke VPS ini dari Internet publik. Alamat IP langsung tidak dapat digunakan dalam alur ini.

Buat satu A record, netbird.example.com yang mengarah ke alamat IPv4 publik VPS, lalu tunggu hingga record tersebut aktif sebelum menjalankan apa pun.

dig +short netbird.example.com

Perintah tersebut harus menampilkan alamat server Anda. Jika installer dijalankan sebelum DNS selesai melakukan propagasi, permintaan sertifikat gagal saat start pertama. Validasi yang gagal berulang kali juga dapat mencapai batas laju Let's Encrypt, sehingga Anda harus menunggu satu jam sebelum mencoba lagi.

Tiga port harus dapat dijangkau dari Internet: TCP 80 untuk certificate challenge dan pengalihan ke HTTPS, TCP 443 untuk dashboard, API, signal, dan trafik relay, serta UDP 3478 untuk STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Buka port tersebut pada network firewall provider Anda. Pada sebagian besar panel VPS, ini merupakan kontrol terpisah. Inilah penyebab server yang ufw status-nya sendiri terlihat benar tetap menolak koneksi.

STUN (session traversal utilities for NAT) memungkinkan peer mengetahui alamat publik dan port yang ditetapkan NAT untuk peer tersebut, sehingga dua peer dapat mencoba membuat tunnel langsung. Jika UDP 3478 diblokir, peer tetap terhubung melalui relay pada TCP 443, sehingga tidak ada yang tampak rusak. Namun, setiap peer akan menampilkan Connection type: Relayed, dan seluruh trafik melewati VPS Anda, bukan langsung dari satu peer ke peer lainnya.

Di sisi perangkat lunak, Anda memerlukan Docker dengan plugin Compose v2, serta jq dan curl. Script memeriksa semuanya dan berhenti jika salah satunya tidak tersedia. Jika Docker baru dipasang pada server ini, buka Menjalankan Docker Compose di VPS terlebih dahulu.

Instal NetBird server dengan skrip quickstart

One-liner yang didokumentasikan mengalirkan release terbaru langsung ke shell:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Tetapkan versinya. latest dapat berubah, sehingga perintah yang sama jika dijalankan dengan jeda dua minggu dapat menghasilkan dua instalasi yang berbeda. Tidak ada catatan di disk yang menunjukkan instalasi mana yang menulis konfigurasi Anda. Unduh release bertag, baca isinya, lalu jalankan.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

Skrip terlebih dahulu meminta domain:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Kemudian skrip menanyakan cara menangani TLS:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

Pilih [0]. Opsi 2 sampai 5 menulis snippet konfigurasi dan menyerahkan konfigurasi koneksinya kepada Anda. Ini tepat pada server yang sudah menjalankan proxy, tetapi tidak tepat pada server baru. Opsi 0 kemudian meminta alamat email Let's Encrypt untuk menerima pemberitahuan masa berlaku.

Pada instalasi pertama, pilih tidak untuk service NetBird Proxy. Service ini memerlukan dua record DNS tambahan, proxy.netbird.example.com dan wildcard *.proxy.netbird.example.com, tetapi tidak diperlukan untuk mesh biasa. Pilih tidak untuk CrowdSec juga. Keduanya dapat ditambahkan nanti.

Skrip menulis file ke direktori saat ini: docker-compose.yml, config.yaml dengan mode 600, dashboard.env, dan traefik-dynamic.yaml jika Anda memilih Traefik bawaan. Perlakukan direktori tersebut sebagai state yang harus dipertahankan karena config.yaml menyimpan key yang mengenkripsi data di store. Kehilangan key tersebut tidak dapat diperbaiki dengan menginstal ulang.

docker compose ps
docker compose logs -f netbird-server

Setiap service harus membaca running, dan log server harus berhenti secara normal, bukan restart berulang kali. Pantau sertifikat secara terpisah:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) adalah protokol yang digunakan Traefik untuk memperoleh sertifikat. Error di sini hampir selalu disebabkan oleh DNS atau port 80 yang tertutup.

Buat akun admin pertama

Buka https://netbird.example.com. Pada instalasi baru, alamat ini menampilkan halaman penyiapan, bukan formulir login. Masukkan alamat email, nama, dan kata sandi, lalu klik Create Account. Akun tersebut menjadi admin pertama, kemudian halaman mengarahkan Anda ke formulir login.

Akun tersebut disimpan di penyimpanan pengguna milik NetBird sendiri, yang dijalankan oleh penyedia identitas yang tertanam dalam container netbird-server. Tidak ada komponen eksternal yang digunakan. Ini merupakan perubahan terbesar dibandingkan NetBird self-hosted setahun lalu. Saat itu, instalasi yang berfungsi mengharuskan Anda menyiapkan Zitadel atau Keycloak terlebih dahulu, lalu menyalin empat nilai OIDC (OpenID Connect) ke setup.env sebelum layanan apa pun dapat dijalankan.

Jika browser menampilkan peringatan sertifikat, bukan halaman penyiapan, berarti sertifikat gagal diterbitkan. Perbaiki masalah tersebut sebelum melanjutkan. Dashboard berkomunikasi dengan API melalui hostname yang sama dan dapat gagal dengan cara yang membingungkan jika sertifikat bermasalah.

Bergabung dengan peer pertama

Instal client pada mesin Linux mana pun, termasuk VPS itu sendiri jika Anda ingin memasukkannya ke dalam mesh:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Di Debian dan Ubuntu, skrip tersebut mengonfigurasi repositori paket NetBird, lalu menginstal client melalui apt. Dengan demikian, package manager tetap mengelola client tersebut. Jika Anda tidak ingin menyalurkan skrip langsung ke shell, simpan skrip terlebih dahulu dengan curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh dan baca isinya sebelum menjalankan sh install.sh. Apa pun caranya, pastikan hasil instalasinya:

apt-cache policy netbird

netbird adalah client command line dan daemon. netbird-ui adalah aplikasi tray desktop, dan server headless tidak membutuhkannya.

Sekarang arahkan client ke server Anda:

sudo netbird up --management-url https://netbird.example.com

Jika --management-url dihilangkan, client akan mendaftar ke layanan hosted NetBird karena itu adalah default yang tertanam dalam binary. Perintah tetap berhasil, mesin tetap memperoleh alamat, dan dashboard self-hosted Anda tetap kosong. Hal ini hampir selalu menimbulkan kebingungan pada percobaan pertama.

Perintah tersebut menampilkan URL yang harus dibuka di browser untuk menyelesaikan login. Setelah itu:

netbird status
ip addr show wt0

Baca empat baris dari netbird status: Management: Connected, Signal: Connected, baris Relays: yang mencantumkan setiap relay yang tersedia, dan NetBird IP: dalam rentang overlay. wt0 adalah interface WireGuard yang dibuat NetBird, dan interface tersebut seharusnya menggunakan alamat yang sama.

Tambahkan mesin kedua tanpa pengawasan menggunakan setup key

Login melalui browser tidak dapat digunakan pada mesin yang tidak memiliki browser dan tidak memiliki pengguna di depannya. setup key adalah token praauthentikasi yang mendaftarkan mesin tanpa langkah interaktif. Buat setup key di dashboard melalui Setup Keys.

Ada dua jenis setup key. One-off key mengautentikasi tepat satu mesin, lalu tidak dapat digunakan lagi. Reusable key mendaftarkan banyak mesin, dengan batas jumlah opsional. Keduanya memiliki masa berlaku dan dapat secara otomatis menetapkan peer baru ke sebuah grup, sehingga access rules pada grup tersebut langsung berlaku saat mesin muncul.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname menetapkan nama yang ditampilkan di dashboard. Tanpa opsi ini, peer menggunakan nama yang diberikan mesin itu sendiri. Fleet yang berisi entri dengan nama ubuntu tidak membantu siapa pun.

Untuk container dan build agent yang berumur pendek, tandai key sebagai ephemeral saat membuatnya. Peer yang didaftarkan dengan ephemeral key akan dihapus secara otomatis setelah offline selama lebih dari 10 minutes. Dengan demikian, entri yang sudah tidak aktif tidak menumpuk dalam daftar peer.

Pahami satu batasan ini sebelum mengandalkan setup keys: saat key kedaluwarsa atau dihapus, key tersebut berhenti menerima pendaftaran baru, tetapi tidak memutus koneksi mesin yang sudah mendaftar dengannya. Untuk menghapus akses sebuah mesin, hapus peer tersebut.

Apakah Anda masih memerlukan identity provider terpisah?

Untuk instalasi kecil, tidak. Penyimpanan pengguna bawaan menangani akun yang dibuat dari dashboard, dan itu sudah cukup untuk beberapa orang.

Anda memerlukan identity provider eksternal jika sudah memilikinya dan tidak ingin memelihara daftar pengguna kedua. NetBird menerima provider apa pun yang mendukung OIDC. Daftarkan client OIDC rahasia di provider Anda, lalu tambahkan di dashboard NetBird dengan empat nilai: nama, client ID, client secret, dan issuer. NetBird akan memberikan URL pengalihan untuk ditempelkan kembali di provider. Integrasi khusus tersedia untuk Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik, dan Pocket ID. Provider lain dapat ditambahkan sebagai OIDC generik. Jika Anda sudah menjalankan Authentik sebagai single sign-on yang di-host sendiri, gunakan cara ini agar hanya ada satu daftar akun.

Login lokal tetap tersedia setelah Anda menambahkan provider, dan setiap provider yang dikonfigurasi akan muncul di halaman login. Pertahankan satu akun admin lokal dengan password yang kuat. Jika konfigurasi OIDC bermasalah, Anda tetap memiliki cara untuk masuk.

NetBird atau Headscale: control plane mana yang sebaiknya Anda jalankan?

Keduanya menghilangkan dependensi yang sama, yaitu control server terkelola yang biasanya dihubungi klien Anda. Namun, bentuk proyeknya berbeda.

Headscale mengimplementasikan ulang control server Tailscale, dan Anda tetap menggunakan klien Tailscale resmi. Tidak ada konsol web resmi. Anda mengelola pengguna dan pre-authentication key dengan perintah headscale terhadap file konfigurasi. Antarmuka web dari komunitas tersedia, tetapi bukan bagian dari proyek ini. Pendekatan ini sesuai bagi Anda yang ingin menyimpan state dalam file dan mengelola perubahannya melalui version control.

NetBird menyediakan seluruh produknya: klien sendiri, dashboard sendiri, identity provider terintegrasi, serta access policy yang dapat diedit melalui browser. Ini berarti lebih banyak komponen yang harus dijalankan pada VPS Anda, tetapi jauh lebih mudah didelegasikan kepada rekan kerja yang tidak akan membuka terminal.

Jalankan Headscale jika Anda sudah menggunakan klien Tailscale atau menginginkan control plane sekecil mungkin. Jalankan NetBird jika beberapa orang perlu mengelola peer dan Anda menginginkan konsol serta SSO tanpa harus merakitnya sendiri.

Seberapa kecil VPS yang dapat menjalankan ini?

Minimum yang didokumentasikan adalah 1 CPU dan memori 2 GB. Catatan NetBird sendiri kini menetapkan batas bawah sekitar 1 GB RAM karena manajemen pengguna sudah bersifat lokal. Sebelumnya, tata letak yang menggunakan deployment Zitadel lengkap memerlukan 2 GB hingga 4 GB. Gunakan VPS dengan memori 2 GB. Ruang tambahan ini memungkinkan proses upgrade mengunduh image baru saat image lama masih tersimpan di disk.

Tiga komponen berikut aman untuk tidak disertakan pada server kecil. Jangan aktifkan service NetBird Proxy. Service ini digunakan untuk memublikasikan service internal pada hostname publik dan tidak berkaitan dengan koneksi antar-peer. Jangan aktifkan CrowdSec. Komponen ini lebih baik ditambahkan nanti pada server yang terekspos, bukan sejak hari pertama. Pertahankan penyimpanan SQLite default pada volume netbird_data. Gunakan PostgreSQL hanya jika deployment dibagi ke beberapa mesin atau terjadi konkurensi nyata. Dokumentasi menyebutkan bahwa migrasi tersebut dapat dilakukan nanti.

Relay adalah satu-satunya komponen yang tidak dapat dihilangkan. Dua peer yang NAT-nya menetapkan port berbeda untuk setiap tujuan tidak akan pernah dapat membuat tunnel langsung. Karena itu, relay adalah satu-satunya jalur yang memungkinkan keduanya berfungsi. Menonaktifkannya hanya menghemat sedikit memori dan memutus koneksi dengan cara yang sulit dilacak.

Jika satu server tidak lagi mencukupi, relay adalah komponen pertama yang sebaiknya dipindahkan. Relay mandiri berjalan dengan NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET dan NB_ENABLE_STUN. Shared secret harus identik pada relay dan server utama. Jika tidak, klien gagal melakukan autentikasi ke relay tersebut.

Mode kegagalan dan hal yang akan Anda lihat

Dashboard menampilkan peringatan sertifikat. Traefik tidak memperoleh sertifikat. Jalankan docker compose logs traefik | grep -i acme. Ada dua kemungkinan penyebab. dig +short netbird.example.com belum mengarah ke VPS ini, atau TCP 80 tertutup di suatu titik antara Let's Encrypt dan container, biasanya pada firewall jaringan provider, bukan pada ufw. Perbaiki penyebabnya sebelum mencoba ulang berulang kali, karena validasi yang gagal dibatasi oleh rate limit dan Anda tidak akan dapat mencoba lagi selama satu jam.

Client menyatakan bahwa koneksi berhasil, tetapi dashboard kosong. Client terdaftar pada layanan hosted NetBird karena --management-url tidak ada. Jalankan netbird status --detail dan baca baris Management:, yang menunjukkan server yang sebenarnya dihubungi. Jika melihat Management: Connected to https://api.netbird.io:443, berarti client terhubung ke cloud. Jalankan sudo netbird down, lalu jalankan sudo netbird up --management-url https://netbird.example.com lagi.

Setiap peer menampilkan Connection type: Relayed. Tidak ada tunnel langsung yang terbentuk, sehingga seluruh trafik melewati VPS dan menambah satu hop latency. Periksa UDP 3478 pada firewall VPS dan firewall provider, karena STUN memungkinkan peer mengetahui alamat dan port publiknya sendiri. netbird status --detail juga menampilkan Direct: false serta tipe kandidat ICE (interactive connectivity establishment) untuk setiap peer. Informasi ini menunjukkan sejauh mana proses tersebut berlangsung. Pada beberapa jaringan, relayed adalah satu-satunya hasil yang tersedia dan tidak ada masalah.

Sebuah peer bergabung, tetapi tidak dapat menjangkau apa pun. Berada dalam mesh tidak berarti dua peer dapat saling berkomunikasi. Access policy menentukan hal tersebut, dan group yang tidak memiliki policy terpasang tidak dapat menjangkau apa pun. Periksa policy di dashboard sebelum mulai melakukan debugging terhadap route dan firewall.

netbird status melaporkan masalah daemon. Service tidak sedang berjalan. Gunakan sudo netbird service status dan sudo netbird service start. Log client berada di /var/log/netbird/client.log. Jika ada hal yang tidak dapat Anda identifikasi, netbird debug bundle --anonymize --system-info mengumpulkan log, status, route, pengaturan DNS, dan status firewall ke dalam satu arsip.

Cadangan dan upgrade

Dua hal menopang seluruh instalasi: direktori yang berisi docker-compose.yml dan config.yaml, serta Docker volume yang menyimpan database dan kunci enkripsi. Cadangkan keduanya secara bersamaan. config.yaml menyimpan kunci yang mengenkripsi data dalam penyimpanan, sehingga salinan database tanpa kunci tersebut tidak dapat dipulihkan menjadi data yang dapat dibaca.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose menambahkan awalan direktori proyek pada nama volume. Karena itu, volume yang didokumentasikan sebagai netbird_data biasanya muncul sebagai netbird_netbird_data. Jalankan docker volume ls terlebih dahulu dan gunakan nama yang ditampilkan. Jika tidak, perintah docker run di atas akan gagal secara diam-diam dengan membuat volume kosong dan tidak mengarsipkan apa pun. Simpan arsip di luar VPS. Jika Anda sudah memiliki alat pencadangan, restic atau BorgBackup dapat menangani pencadangan ke lokasi terpisah.

Upgrade server dilakukan dengan menarik image lalu membuat ulang container:

docker compose pull
docker compose up -d
docker compose ps

Sebelum mengandalkan langkah tersebut, jalankan docker compose config | grep image:. Tag apa pun yang bertuliskan latest harus dikunci ke versi tertentu. Alasannya sama seperti saat Anda mengunci versi skrip instalasi: Anda perlu mengetahui apa yang sedang berjalan dan memiliki versi yang dapat digunakan untuk kembali jika upgrade menimbulkan masalah. Client di-upgrade melalui package manager yang digunakan untuk menginstalnya.

FAQ

Apakah saya memerlukan identity provider sendiri untuk melakukan self-hosting NetBird?

Tidak. Rilis saat ini menyertakan penyimpanan pengguna bawaan. Anda dapat membuat akun admin pertama melalui browser di https://netbird.example.com, lalu menambahkan pengguna dari dashboard. OIDC provider eksternal bersifat opsional dan dapat ditambahkan nanti dengan empat nilai: nama, client ID, client secret, dan issuer. Panduan yang meminta Anda men-deploy Zitadel atau Keycloak sebelum NetBird menjelaskan konfigurasi yang tidak lagi diperlukan. Jika mengikutinya, Anda harus menjalankan satu service tambahan.

Mengapa semua peer saya menampilkan Connection type: Relayed?

Koneksi langsung tidak terbentuk, sehingga trafik melewati relay pada VPS Anda. Penyebab yang umum adalah UDP 3478 diblokir. Port ini digunakan peer melalui STUN untuk menemukan alamat dan port publiknya sendiri. Buka port tersebut pada firewall VPS dan firewall jaringan terpisah milik provider Anda. Setelah itu, jalankan netbird status --detail lagi dan baca baris Direct:. Pada jaringan yang menetapkan port berbeda untuk setiap tujuan melalui NAT, status relayed adalah satu-satunya hasil yang mungkin. Tidak ada konfigurasi yang salah.

Client saya berhasil terhubung, tetapi dashboard tidak menampilkan peer. Apa yang terjadi?

Client mendaftar ke service hosted NetBird, bukan ke server Anda. Hal ini terjadi ketika --management-url tidak disertakan. netbird status --detail menampilkan server yang digunakan client pada baris Management:. Nilai seperti https://api.netbird.io:443 mengonfirmasi hal tersebut. Jalankan sudo netbird down, lalu sudo netbird up --management-url https://netbird.example.com. Setelah itu, peer akan muncul di dashboard Anda.

Apa perbedaan NetBird self-hosted dan Headscale?

Keduanya menggantikan control server hosted dengan server yang Anda jalankan sendiri. Headscale hanya menyediakan control plane. Anda mengelolanya menggunakan perintah headscale dan file konfigurasi. Headscale tidak memiliki konsol web resmi dan mengendalikan client Tailscale resmi. NetBird menyediakan client sendiri, dashboard admin, dan integrasi identity provider dalam stack yang sama. Headscale lebih kecil untuk dijalankan dan menyimpan state dalam file. NetBird lebih mudah diberikan kepada pengguna yang tidak akan menggunakan terminal.

Berapa ukuran VPS yang diperlukan server NetBird self-hosted?

Minimum yang didokumentasikan adalah 1 CPU dan memori 2 GB. Jadi, gunakan VPS dengan memori 2 GB. Batas praktisnya turun menjadi sekitar 1 GB pada rilis terbaru karena identity provider kini tertanam, bukan lagi deployment terpisah. Nonaktifkan proxy dan service CrowdSec opsional selama instalasi. Gunakan penyimpanan SQLite default sampai Anda benar-benar memerlukan PostgreSQL.