Cara Menjalankan Mock Server Self-Hosted di Intranet dengan Apidog

Beberapa tim tidak dapat mengirimkan lalu lintas mereka ke cloud. Mungkin Anda berada di balik firewall perusahaan yang memblokir panggilan keluar ke layanan pihak ketiga. Mungkin aturan kepatuhan menyatakan bahwa data permintaan dan respons harus tetap berada di mesin yang Anda kendalikan. Mungkin seluruh lingkungan terisolasi (air-gapped) dan tidak ada yang meninggalkan intranet sama sekali. Dalam semua kasus tersebut, URL mock yang di-hosting di infrastruktur orang lain tidak dapat digunakan, bahkan ketika data mock itu sendiri palsu.

Apidog menanganinya dengan runner yang di-hosting sendiri. Alih-alih permintaan Anda keluar ke mock cloud Apidog, Anda menyebarkan program kecil di server milik Anda, dan program itu mengembalikan respons mock dari dalam jaringan Anda sendiri. Desainnya tetap ada di proyek Apidog Anda seperti biasa; hanya penyediaannya yang berpindah ke perangkat keras Anda. Panduan ini menjelaskan apa itu runner, kapan memilihnya dibandingkan mock cloud, cara mengaturnya dari dokumen, dan satu perbedaan yang membingungkan banyak orang: runner bukanlah CLI. Jika Anda ingin gambaran yang lebih luas mengapa tim menjalankan mock di mesin mereka sendiri, panduan tentang server mock API yang di-hosting sendiri mencakup kasus umum, dan OpenAPI Initiative menjelaskan spesifikasi dari mana mock ini dihasilkan. Ingin mengikuti? Unduh Apidog terlebih dahulu.

button

Apa itu runner yang di-hosting sendiri

Apidog Self-hosted Runner adalah program otomatis yang Anda host di server mandiri. Secara resmi disebut General Runner, dan ia melakukan tiga tugas: menjalankan pengujian otomatis terjadwal, mengimpor dokumen API, dan mengembalikan respons mock. Tugas ketiga inilah yang dibahas dalam artikel ini.

Ini adalah ide utamanya. Setelah Anda menyebarkan General Runner dan mengatur Server Host-nya, lingkungan baru bernama Runner Mock akan muncul secara otomatis di proyek Anda. Setiap permintaan yang Anda kirim melalui lingkungan itu akan mendapatkan respons mock-nya dari runner yang di-hosting sendiri, bukan dari mock cloud Apidog. Desain mock yang sama, data yang dihasilkan sama, mesin yang menyediakan berbeda. Lalu lintas Anda tidak pernah meninggalkan jaringan Anda.

Ini adalah alternatif self-hosted untuk mock cloud. Jika tim Anda dapat mengakses internet dan tidak ada aturan yang melarangnya, mock cloud Apidog lebih sederhana karena tidak ada yang perlu disebarkan. Gunakan runner ketika salah satu hal berikut ini benar:

Lalu lintas keluar ke host eksternal diblokir atau diaudit secara ketat.
Kebijakan kepatuhan mengharuskan data permintaan tetap berada di infrastruktur internal.
Lingkungan terisolasi (air-gapped) dan tidak dapat mencapai titik akhir cloud sama sekali.
Anda ingin latensi mock diukur di LAN Anda sendiri, bukan melalui internet publik.

Jika tidak ada hal di atas yang berlaku, host Docker tambahan adalah overhead yang tidak Anda perlukan. Jujurlah pada diri sendiri di kategori mana Anda berada sebelum menyediakan server.

Satu catatan tentang paket dan izin. Dokumen Apidog tidak menyatakan batasan eksplisit gratis-vs-berbayar untuk General Runner atau untuk mock yang di-hosting sendiri, dan mereka tidak mencantumkan angka harga untuk itu, jadi panduan ini tidak akan mengada-ada. Yang dibutuhkan dalam pengaturan ini adalah izin admin tim atau proyek, karena penyebaran runner terjadi di dalam Sumber Daya Tim, dan hanya admin yang dapat membuka pengaturan tersebut. Jika Anda tidak dapat melihat panel Sumber Daya, itulah alasannya.

Yang Anda butuhkan sebelum memulai

Runner dikirimkan sebagai kontainer Docker, jadi server yang meng-host-nya perlu menginstal Docker. Dokumen-dokumen memerlukan versi minimum 20.10.0, dan merekomendasikan 20.10.13 atau yang lebih baru. Periksa versi yang Anda miliki:

docker --version

Anda juga memerlukan tempat untuk menjalankannya: mesin Linux, macOS, atau Windows yang dapat dijangkau oleh klien Apidog tim Anda dan layanan Apidog. Di intranet, ini biasanya berarti server internal dengan IP atau nama host yang stabil. Itu seluruh daftar prasyarat: Docker, host, dan hak admin di tim. Segala sesuatu yang lain Anda konfigurasikan di dalam Apidog itu sendiri.

Sebarkan General Runner

Perintah penyebaran dibuat secara otomatis untuk Anda dari dalam Apidog, dan membawa token, jadi Anda tidak perlu menuliskannya secara manual. Berikut alurnya.

Buat perintah

Buka Apidog Home, pilih tim Anda, lalu klik Sumber Daya di sidebar kanan dan pilih Deploy General Runner. Sebuah pop-up muncul di mana Anda mengatur beberapa hal:

Server OS: Linux, macOS, atau Windows, sehingga perintah yang dihasilkan sesuai dengan host Anda.
Docker Image: pilih General, Slim, atau Custom. General dilengkapi dengan Node.js 18, Java 21, Python 3, dan PHP 8 yang sudah terinstal. Slim hanya dilengkapi Node.js 18, untuk gambar yang lebih kecil. Custom memungkinkan Anda menyediakan Dockerfile sendiri ketika Anda membutuhkan runtime tambahan untuk skrip pengujian.
Exposed Port: diatur dengan parameter -p, misalnya -p 80:4524, yang memetakan port host 80 ke port internal runner.
Mounted Data Directory: diatur dengan parameter -v, sehingga data runner tetap ada di host meskipun terjadi restart.

Setelah selesai, salin perintah yang dihasilkan. Ini penting: perintah hanya ditampilkan sekali, untuk alasan keamanan data, karena menyematkan token Anda. Jika Anda kehilangannya, Anda membuat yang baru daripada memulihkan yang lama. Tangkap segera.

Jalankan di server

Tempel perintah ke terminal server Anda. Instalasi dimulai secara otomatis dan menarik gambar. Perintah yang sudah selesai terlihat kira-kira seperti ini (milik Anda akan berbeda, dan akan menyertakan token yang sebenarnya):

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <TOKEN_YANG_ANDA_HASILKAN>

Konfirmasikan bahwa kontainer telah aktif:

docker ps

Anda akan melihat kontainer runner tercantum dengan pemetaan port-nya. Klien Docker seperti Docker Desktop menunjukkan hal yang sama jika Anda lebih suka melihat UI.

Konfirmasikan sudah terdaftar

Kembali ke Apidog, buka Sumber Daya Tim dan buka General Runner. Klik tombol refresh. Runner seharusnya sekarang muncul sebagai deployed dengan status Started. Jika tidak muncul pada awalnya, tombol refresh adalah perbaikannya; tunggu sebentar dan klik lagi.

Status runner memiliki tiga kondisi yang perlu diketahui:

Started: diaktifkan, berkomunikasi dengan Apidog, menangani tugas. Ini adalah kondisi yang Anda inginkan.
Stopped: seseorang menghentikannya secara manual di Apidog. Tetap deployed tetapi tidak akan memproses tugas.
Offline: koneksi ke Apidog terputus, sehingga tidak dapat memproses apa pun. Periksa kontainer dan jalur jaringan.

Aktifkan Runner Mock

Menyebarkan runner memberi Anda agen. Satu langkah lagi mengarahkan lalu lintas mock Anda ke sana.

Di Sumber Daya Tim, buka General Runner dan temukan bidang Server Host. Masukkan alamat tempat runner Anda dapat dijangkau. Pada pengaturan HTTP biasa, itu adalah host dan port yang Anda ekspos, seperti http://127.0.0.1:80 untuk pengujian lokal atau http://runner.internal.example.com:80 untuk host intranet bersama. Di balik proxy penghenti TLS, itu terlihat seperti https://runner.example.com:443. Lebih lanjut tentang HTTPS sebentar lagi.

Setelah Server Host diatur, Apidog secara otomatis menghubungkan lingkungan Runner Mock untuk proyek Anda. Verifikasi: buka proyek, buka Manajemen Lingkungan, dan konfirmasikan bahwa Runner Mock sekarang muncul dalam daftar lingkungan. Anda tidak membuatnya secara manual; pengaturan Server Hostlah yang membuatnya muncul.

Kirim permintaan melalui mock yang di-hosting sendiri

Sekarang gunakan itu. Misalkan Anda memiliki endpoint GET /orders/{orderId} dalam proyek untuk API manajemen pesanan internal. Buka endpoint itu, lalu di dropdown lingkungan di bagian atas, pilih Runner Mock daripada lingkungan cloud. Kirim permintaannya.

Respons kembali dari runner Anda. Karena Apidog menghasilkan data mock dari skema Anda, skema `Order` yang terdefinisi dengan baik mengembalikan nilai-nilai realistis daripada placeholder kosong:

curl http://runner.internal.example.com:80/orders/10583

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}

JSON itu tidak pernah menyentuh internet publik. Runner membangunnya dari skema endpoint Anda dan menyajikannya dari dalam jaringan Anda. Generasi yang sadar bidang seperti nilai `customerEmail` di atas berasal dari Apidog yang membaca jenis dan nama bidang skema Anda, mesin yang sama yang dibahas dalam artikel pendamping tentang pembuatan data mock realistis secara otomatis dengan mock cerdas. Jika Anda ingin mengontrol persis apa yang dikembalikan oleh permintaan tertentu, Anda menambahkan ekspektasi mock pada endpoint, dan runner menyajikan ekspektasi itu dengan cara yang sama seperti mock cloud. Mekanisme membangun respons mock yang baik sama saja apakah server itu milik Apidog atau milik Anda; hanya hostnya yang berubah. Konsep umum di balik mocking API berlaku tanpa perubahan.

HTTPS, mount data, dan detail dunia nyata lainnya

Uji coba pada http://127.0.0.1 mudah. Penerapan intranet bersama memiliki beberapa aspek sulit yang perlu diketahui sebelum Anda meluncurkannya ke tim.

HTTPS membutuhkan reverse proxy

Runner tidak memiliki dukungan sertifikat HTTPS bawaan dan tidak melakukan penyediaan sertifikat otomatis. Ia tidak akan mengambil atau mengelola sertifikat TLS untuk Anda. Jika Anda membutuhkan https://, hentikan TLS di reverse proxy di depan runner, misalnya Nginx yang menyimpan sertifikat Anda, lalu arahkan Server Host ke URL HTTPS proxy. Tanpa proxy, gunakan http://host:port. Jangan mengatur Server Host ke https:// dan mengharapkan runner untuk menjawab TLS secara langsung; itu tidak bisa.

Blok Nginx minimal yang mengungguli runner pada port 4524 terlihat seperti ini:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}

Kemudian Server Host menjadi https://runner.example.com:443. Panduan MDN untuk HTTPS adalah penyegaran yang baik jika penghentian TLS baru bagi tim Anda.

Mount file bersifat spesifik jalur

Jika mock atau tes Anda membutuhkan file tambahan, runner mengharapkannya pada jalur tetap di dalam kontainer, jadi mount mereka di sana:

Program eksternal masuk ke /app/external-programs/.
Konfigurasi koneksi database masuk ke /app/database/database-connections.json.
Sertifikat klien SSL masuk ke /app/ssl/ssl-client-cert-list.json.

Hubungkan ini melalui mount -v Anda sehingga mereka bertahan setelah restart.

Perilaku redeploy dan upgrade

Ketika versi runner baru dirilis, Anda akan melihat opsi Upgrade, dan di bawah More Actions Anda dapat Melakukan Redeploy. Keduanya menghentikan kontainer yang sedang berjalan saat kontainer baru muncul. Bagian yang meyakinkan: tugas terjadwal yang ada di klien Apidog tidak terpengaruh oleh redeploy atau upgrade, jadi Anda hanya menginterupsi layanan langsung untuk saat kontainer dimulai ulang, bukan kehilangan konfigurasi.

Otomatiskan alur kerja dengan Apidog CLI

Ini adalah perbedaan yang mencegah kebingungan: runner adalah agen berumur panjang yang dapat menyajikan mock dan menjalankan tugas terjadwal, sementara Apidog CLI adalah runner pengujian satu kali untuk CI. Keduanya adalah alat yang berbeda. CLI tidak dapat menyajikan, memulai, atau meng-host server mock. Tidak ada apidog run mock dan tidak ada apidog mock serve. Perintah apidog run di CLI menjalankan skenario pengujian, folder skenario pengujian, dan suite pengujian, dan grup perintah mock hanya melakukan CRUD pada ekspektasi mock sebagai data. Penyajian mock adalah tugas runner, bukan CLI.

Jadi keduanya cocok bersama seperti ini. CLI dan agen pengkodean AI seperti Cursor, Claude Code, dan Codex dapat membuat dan memperbarui endpoint serta skema dalam proyek Anda, yang menjaga akurasi output mock Anda seiring dengan berkembangnya spesifikasi. Setelah mock yang di-host sendiri membuka pekerjaan frontend, skenario pengujian proyek yang sama berjalan tanpa kepala di CI dengan satu perintah, memvalidasi backend yang sebenarnya terhadap kontrak yang dijelaskan oleh mock:

apidog run -t <scenario_id> -e <env_id> -r html,cli

Satu perintah itu menjalankan skenario Anda terhadap backend langsung dan menulis laporan HTML plus CLI. Instalasi adalah npm install -g apidog-cli pada Node.js v16 atau lebih baru; panduan instalasi Apidog CLI mencakup apidog login dan pengaturan token. Untuk membuat pengujian itu berjalan di setiap push, hubungkan ke pipeline Anda dengan panduan CI/CD Apidog CLI. Artikel tentang mocking API dari CLI menjelaskan dengan tepat mengapa terminal mengelola definisi mock tetapi tidak meng-host-nya.

FAQ

Apakah saya membutuhkan runner yang di-hosting sendiri jika tim saya dapat menjangkau internet?

Mungkin tidak. Mock cloud tidak memerlukan deployment apa pun dan merupakan jalur yang lebih sederhana. Pilih runner ketika lalu lintas keluar diblokir atau diaudit, aturan kepatuhan menjaga data di infrastruktur internal, atau lingkungan terisolasi (air-gapped). Jika Anda membandingkan pendekatan yang di-hosting dengan yang dikelola terlebih dahulu, panduan mock cloud Apidog adalah pendamping alami panduan ini.

Bisakah Apidog CLI memulai server mock yang di-hosting sendiri?

Tidak. CLI menjalankan pengujian dengan apidog run dan mengelola ekspektasi mock sebagai data dengan grup perintah mock-nya. Menyajikan lalu lintas mock dilakukan oleh General Runner atau oleh mock cloud, tidak pernah oleh CLI. Jika Anda berharap untuk mengetik satu perintah terminal dan mendapatkan mock yang berjalan di port, itu adalah tugas runner, yang diatur melalui GUI seperti yang dijelaskan di atas.

Apakah runner mendukung HTTPS sendiri?

Ia tidak mengirimkan sertifikat atau menyediakannya secara otomatis. Pasang reverse proxy seperti Nginx di depan untuk menghentikan TLS, lalu arahkan Server Host ke URL https:// proxy. Tanpa proxy, gunakan http://host:port.

Mengapa runner saya tidak muncul setelah saya menjalankan perintahnya?

Buka Sumber Daya Tim, pergi ke General Runner, dan klik tombol refresh. Pendaftaran bisa sedikit tertunda. Jika masih tidak muncul, konfirmasikan bahwa kontainer sedang berjalan dengan docker ps dan host dapat dijangkau dari Apidog. Status Offline berarti koneksi terputus; Started adalah yang Anda inginkan.

Bisakah beberapa tim berbagi satu runner untuk layanan mock global?

Sebuah runner mendaftar ke tim tempat Anda menyebarkannya, dan lingkungan Runner Mock-nya muncul per proyek. Jika Anda menjalankan tim terdistribusi yang berbagi lingkungan mock, pola dalam panduan tentang berbagi lingkungan mock antar tim global akan membantu Anda memutuskan berapa banyak runner yang akan disiapkan dan di mana.

Kesimpulan

Mocking yang di-hosting sendiri dengan General Runner menjaga data permintaan Anda tetap berada di infrastruktur yang Anda kendalikan sementara desain mock Anda tetap berada di tempatnya, di proyek Apidog Anda. Anda menyebarkan satu kontainer Docker, mengatur Server Host, dan lingkungan Runner Mock melakukan sisanya. Gunakan ketika cloud tidak dapat diakses, dan tetap gunakan mock cloud ketika bisa. Siap menjalankan mock di jaringan Anda sendiri? Unduh Apidog, sebarkan runner, dan sajikan respons Runner Mock pertama Anda tanpa satu pun paket meninggalkan intranet Anda.