DEV Community

Cover image for Cara Menjalankan Mock Server Self-Hosted di Intranet dengan Apidog
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menjalankan Mock Server Self-Hosted di Intranet dengan Apidog

Beberapa tim tidak dapat mengirimkan lalu lintas API ke cloud. Penyebabnya bisa berupa firewall perusahaan, aturan kepatuhan yang mewajibkan data permintaan dan respons tetap di infrastruktur internal, atau lingkungan air-gapped tanpa akses internet. Dalam kondisi ini, URL mock yang di-hosting di infrastruktur pihak ketiga tidak dapat digunakan, bahkan jika data mock-nya sepenuhnya sintetis.

Coba Apidog hari ini

Apidog menyediakan solusi melalui Self-hosted Runner. Alih-alih mengirim permintaan ke mock cloud Apidog, Anda menjalankan program kecil di server sendiri untuk menyajikan respons mock dari jaringan internal. Definisi endpoint, skema, dan ekspektasi mock tetap dikelola di proyek Apidog; yang berpindah hanya lokasi server mock-nya.

Jika Anda memerlukan konteks tambahan, lihat panduan tentang server mock API yang di-hosting sendiri serta spesifikasi dari OpenAPI Initiative.

Apa itu Self-hosted Runner?

Apidog Self-hosted Runner, yang secara resmi disebut General Runner, adalah program otomatis yang Anda jalankan pada server mandiri.

General Runner dapat digunakan untuk:

  1. Menjalankan pengujian otomatis terjadwal.
  2. Mengimpor dokumentasi API.
  3. Menyajikan respons mock.

Artikel ini berfokus pada fungsi ketiga: menjalankan mock API dari infrastruktur Anda sendiri.

Diagram Apidog Self-hosted Runner

Setelah General Runner dideploy dan Server Host dikonfigurasi, Apidog otomatis membuat environment bernama Runner Mock di proyek Anda. Permintaan yang dikirim melalui environment tersebut akan menerima respons dari runner internal, bukan dari mock cloud Apidog.

Gunakan runner saat salah satu kondisi berikut berlaku:

  • Lalu lintas keluar ke host eksternal diblokir atau diaudit ketat.
  • Kebijakan kepatuhan mengharuskan data permintaan tetap berada di infrastruktur internal.
  • Lingkungan Anda air-gapped dan tidak dapat mengakses endpoint cloud.
  • Anda membutuhkan latensi mock di jaringan LAN, bukan melalui internet publik.

Jika tim Anda dapat mengakses internet dan tidak memiliki batasan tersebut, mock cloud Apidog biasanya lebih sederhana karena tidak memerlukan server tambahan.

Anda memerlukan hak admin tim atau proyek untuk mengelola General Runner dari bagian Sumber Daya Tim.

Prasyarat

General Runner berjalan sebagai kontainer Docker. Siapkan host Linux, macOS, atau Windows yang dapat dijangkau oleh klien Apidog tim Anda.

Dokumentasi mensyaratkan Docker minimal versi 20.10.0 dan merekomendasikan 20.10.13 atau lebih baru.

Periksa versi Docker:

docker --version
Enter fullscreen mode Exit fullscreen mode

Siapkan juga:

  • Server atau mesin dengan IP/nama host yang stabil.
  • Akses Docker pada server tersebut.
  • Hak admin pada tim Apidog.
  • Jalur jaringan antara server runner dan layanan Apidog.

Deploy General Runner

1. Buat perintah deployment dari Apidog

Di Apidog:

  1. Buka Home.
  2. Pilih tim Anda.
  3. Buka Sumber Daya di sidebar kanan.
  4. Pilih Deploy General Runner.

Pada dialog deployment, konfigurasi beberapa opsi berikut.

Opsi Fungsi
Server OS Pilih Linux, macOS, atau Windows agar Apidog menghasilkan perintah yang sesuai.
Docker Image Pilih General, Slim, atau Custom.
Exposed Port Memetakan port host ke port runner dengan -p, misalnya -p 80:4524.
Mounted Data Directory Menyimpan data runner pada host menggunakan -v.

Pilihan image yang tersedia:

  • General: Node.js 18, Java 21, Python 3, dan PHP 8.
  • Slim: hanya Node.js 18, dengan ukuran image lebih kecil.
  • Custom: gunakan Dockerfile sendiri jika skrip pengujian membutuhkan runtime tambahan.

Setelah konfigurasi selesai, salin perintah yang dihasilkan.

Perintah deployment hanya ditampilkan sekali karena menyertakan token. Jika hilang, buat perintah baru daripada mencoba memulihkan token lama.

2. Jalankan kontainer di server

Tempel perintah dari Apidog ke terminal server. Bentuk perintahnya kira-kira seperti berikut:

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

Perintah tersebut:

  • Menjalankan runner di background dengan -d.
  • Memetakan port host 80 ke port internal runner 4524.
  • Menyimpan data runner di /opt/apidog-runner/data.
  • Menghubungkan runner ke tim Apidog melalui token deployment.

Verifikasi bahwa kontainer berjalan:

docker ps
Enter fullscreen mode Exit fullscreen mode

Pastikan kontainer apidog-runner muncul dan port mapping-nya sesuai dengan konfigurasi Anda.

3. Konfirmasi runner terdaftar

Kembali ke Apidog:

  1. Buka Sumber Daya Tim.
  2. Pilih General Runner.
  3. Klik tombol refresh.

Runner seharusnya muncul dengan status Started.

Status yang perlu diperhatikan:

  • Started: runner aktif, terhubung ke Apidog, dan siap memproses tugas.
  • Stopped: runner dihentikan secara manual dari Apidog.
  • Offline: koneksi runner ke Apidog terputus.

Jika status masih Offline, periksa:

docker ps
docker logs apidog-runner
Enter fullscreen mode Exit fullscreen mode

Lalu pastikan server runner memiliki jalur jaringan yang diperlukan untuk terhubung ke Apidog.

Aktifkan Runner Mock

Deploy runner belum otomatis mengarahkan traffic mock ke runner tersebut. Anda perlu mengatur Server Host.

Di halaman Sumber Daya Tim → General Runner:

  1. Temukan field Server Host.
  2. Masukkan URL yang dapat dijangkau oleh klien Anda.

Contoh konfigurasi:

http://127.0.0.1:80
Enter fullscreen mode Exit fullscreen mode

Untuk server intranet bersama:

http://runner.internal.example.com:80
Enter fullscreen mode Exit fullscreen mode

Jika menggunakan reverse proxy TLS:

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Setelah Server Host disimpan, Apidog otomatis menambahkan environment Runner Mock pada proyek Anda.

Verifikasi melalui:

  1. Buka proyek Apidog.
  2. Masuk ke Manajemen Lingkungan.
  3. Pastikan Runner Mock muncul dalam daftar environment.

Kirim permintaan ke mock internal

Misalnya, proyek Anda memiliki endpoint berikut:

GET /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

Untuk menguji mock internal:

  1. Buka endpoint tersebut di Apidog.
  2. Pilih environment Runner Mock pada dropdown environment.
  3. Kirim permintaan.

Anda juga dapat memanggil endpoint langsung melalui curl:

curl http://runner.internal.example.com:80/orders/10583
Enter fullscreen mode Exit fullscreen mode

Contoh respons mock:

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

Respons di atas disajikan oleh runner dari jaringan internal Anda. Apidog menghasilkan data berdasarkan skema endpoint, termasuk tipe dan nama field seperti customerEmail.

Untuk memahami mekanisme pembangkitan data, baca panduan pembuatan data mock realistis secara otomatis dengan mock cerdas.

Jika Anda membutuhkan respons yang spesifik, tambahkan mock expectation pada endpoint. Runner akan menyajikan expectation tersebut dengan mekanisme yang sama seperti mock cloud. Konsep dasar mocking API tetap sama; perbedaannya hanya pada lokasi server.

Konfigurasi HTTPS dengan reverse proxy

Runner tidak menyediakan sertifikat HTTPS dan tidak mengelola TLS secara otomatis. Jika endpoint mock harus menggunakan https://, letakkan reverse proxy di depan runner.

Contoh konfigurasi Nginx:

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;
    }
}
Enter fullscreen mode Exit fullscreen mode

Dengan konfigurasi ini:

  • Nginx menerima koneksi HTTPS pada port 443.
  • Nginx menangani sertifikat TLS.
  • Nginx meneruskan request ke runner pada 127.0.0.1:4524.

Kemudian, set Server Host menjadi:

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Jika Anda belum menggunakan reverse proxy, gunakan URL HTTP biasa:

http://host:port
Enter fullscreen mode Exit fullscreen mode

Lihat juga dokumentasi konfigurasi HTTPS Nginx dan panduan HTTPS dari MDN.

Mount file tambahan

Jika mock atau pengujian Anda membutuhkan file tambahan, mount file tersebut ke jalur yang diharapkan runner.

Jenis file Jalur dalam kontainer
Program eksternal /app/external-programs/
Konfigurasi koneksi database /app/database/database-connections.json
Sertifikat klien SSL /app/ssl/ssl-client-cert-list.json

Contoh mount konfigurasi database:

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  -v /opt/apidog-runner/database-connections.json:/app/database/database-connections.json \
  apidog/runner:latest \
  --token <TOKEN_YANG_ANDA_HASILKAN>
Enter fullscreen mode Exit fullscreen mode

Gunakan volume mount agar file tetap tersedia setelah kontainer direstart atau dideploy ulang.

Redeploy dan upgrade runner

Saat versi runner baru tersedia, Apidog menyediakan opsi Upgrade. Anda juga dapat menggunakan More Actions → Redeploy.

Keduanya akan menghentikan kontainer lama ketika kontainer baru dibuat. Dampaknya adalah gangguan singkat pada layanan mock selama restart.

Konfigurasi tugas terjadwal yang sudah ada di klien Apidog tidak hilang saat redeploy atau upgrade. Yang terhenti hanya layanan runner selama proses penggantian kontainer.

Bedakan General Runner dan Apidog CLI

General Runner dan Apidog CLI memiliki fungsi yang berbeda.

Alat Fungsi utama
General Runner Menyajikan mock API dan menjalankan tugas terjadwal.
Apidog CLI Menjalankan pengujian sekali jalan atau di pipeline CI/CD.

Apidog CLI tidak dapat menjalankan server mock. Tidak ada perintah seperti:

apidog run mock
Enter fullscreen mode Exit fullscreen mode

atau:

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

Perintah apidog run digunakan untuk menjalankan skenario pengujian, folder skenario, atau test suite. Grup perintah mock pada CLI hanya mengelola data mock expectation, bukan menyajikan traffic mock.

Contoh menjalankan skenario pengujian di CI:

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Perintah tersebut menjalankan skenario terhadap backend target dan menghasilkan laporan HTML serta output CLI.

Instal Apidog CLI dengan:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

CLI membutuhkan Node.js v16 atau lebih baru. Untuk autentikasi dan token, lihat panduan instalasi Apidog CLI.

Untuk menjalankan test pada setiap push, integrasikan CLI ke pipeline Anda melalui panduan CI/CD Apidog CLI. Penjelasan tentang mengelola definisi mock dari terminal tersedia di artikel mocking API dari CLI.

FAQ

Apakah saya membutuhkan self-hosted runner jika tim dapat mengakses internet?

Biasanya tidak. Mock cloud lebih sederhana karena tidak membutuhkan deployment server. Gunakan runner jika traffic keluar diblokir, diaudit, dibatasi oleh kepatuhan, atau lingkungan Anda air-gapped.

Untuk membandingkan pendekatannya, lihat panduan mock cloud Apidog.

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

Tidak. CLI menjalankan pengujian melalui apidog run dan mengelola mock expectation sebagai data. Penyajian traffic mock dilakukan oleh General Runner atau mock cloud Apidog.

Apakah runner mendukung HTTPS secara langsung?

Tidak. Runner tidak mengelola sertifikat TLS. Gunakan reverse proxy seperti Nginx untuk menghentikan TLS, lalu arahkan Server Host ke URL HTTPS reverse proxy tersebut.

Mengapa runner tidak muncul setelah menjalankan perintah deployment?

Klik refresh pada Sumber Daya Tim → General Runner. Jika runner tetap tidak muncul:

  1. Periksa kontainer dengan docker ps.
  2. Periksa log dengan docker logs apidog-runner.
  3. Pastikan konektivitas jaringan runner ke Apidog tersedia.
  4. Pastikan token deployment yang digunakan adalah token terbaru.

Bisakah beberapa tim berbagi satu runner?

Runner terdaftar pada tim tempat runner tersebut dideploy, sedangkan environment Runner Mock muncul per proyek. Untuk tim terdistribusi yang membutuhkan environment bersama, gunakan pola pada panduan berbagi lingkungan mock antar tim global untuk menentukan jumlah dan lokasi runner.

Kesimpulan

Self-hosted mocking dengan General Runner memungkinkan tim menjalankan mock API tanpa mengirim traffic permintaan ke infrastruktur eksternal. Proses implementasinya sederhana:

  1. Siapkan host dengan Docker.
  2. Deploy General Runner dari Apidog.
  3. Verifikasi status runner.
  4. Atur Server Host.
  5. Pilih environment Runner Mock pada proyek.
  6. Kirim request ke endpoint mock dari jaringan internal.

Gunakan self-hosted runner ketika cloud tidak dapat diakses atau data harus tetap berada di infrastruktur yang Anda kendalikan. Jika tidak ada batasan tersebut, mock cloud tetap menjadi pilihan yang lebih ringan.

Untuk mulai mencoba, unduh Apidog, deploy runner, lalu jalankan respons mock pertama langsung dari intranet Anda.

Top comments (0)