Bazı ekipler trafiğini buluta gönderemeyebilir. Belki üçüncü taraf hizmetlere giden çağrıları engelleyen bir şirket güvenlik duvarının arkasındasınızdır. Belki bir uyumluluk kuralı, istek ve yanıt verilerinin kontrol ettiğiniz makinelerde kalmasını gerektiriyordur. Belki de tüm ortam hava boşluklu (air-gapped) olup, hiçbir şey intranet dışına çıkmıyordur. Bu durumların herhangi birinde, sahte veriler bile olsa, başkasının altyapısında barındırılan bir sahte URL (mock URL) hiç de uygun değildir.
Apidog bunu kendi kendine barındırılan bir çalıştırma aracı (runner) ile ele alır. İsteklerinizin Apidog'un bulut sahtesine (cloud mock) gitmesi yerine, sahip olduğunuz bir sunucuya küçük bir program kurarsınız ve bu program sahte yanıtları kendi ağınızın içinden döndürür. Tasarım, her zamanki gibi Apidog projenizde kalır; yalnızca sunum donanımınıza taşınır. Bu kılavuz, çalıştırma aracının ne olduğunu, bulut sahtesi yerine ne zaman seçilmesi gerektiğini, belgelerden nasıl kurulacağını ve insanların kafasını karıştıran bir ayrımı açıklar: çalıştırma aracı bir CLI değildir. Ekiplerin neden kendi sunucularında sahteler (mocks) çalıştırdığına dair daha geniş bir bakış açısı isterseniz, kendi kendine barındırılan API sahte sunucuları hakkındaki kılavuz genel durumu kapsar ve OpenAPI Initiative bu sahtelerin oluşturulduğu spesifikasyonu açıklar. Takip etmek ister misiniz? Önce Apidog'u indirin.
Kendi kendine barındırılan çalıştırma aracı nedir
Apidog Kendi Kendine Barındırılan Çalıştırma Aracı, bağımsız bir sunucuda barındırdığınız otomatik bir programdır. Resmi olarak Genel Çalıştırma Aracı (General Runner) olarak adlandırılır ve üç işlevi vardır: zamanlanmış otomatik testleri çalıştırır, API belgelerini içe aktarır ve sahte yanıtlar döndürür. Bu makale, üçüncü işleviyle ilgilidir.
İşte ana fikir. Bir Genel Çalıştırma Aracı dağıtıp Sunucu Ana Bilgisayarını (Server Host) ayarladığınızda, projenizde otomatik olarak Çalıştırma Aracı Sahtesi (Runner Mock) adı verilen yeni bir ortam belirir. Bu ortam üzerinden gönderdiğiniz herhangi bir istek, sahte yanıtını Apidog'un bulut sahtesi yerine kendi kendine barındırılan çalıştırma aracınızdan alır. Aynı sahte tasarım, aynı oluşturulan veriler, ancak sunumu yapan farklı bir makine. Trafiğiniz ağınızdan asla ayrılmaz.
Bu, bulut sahtesinin kendi kendine barındırılan alternatifidir. Ekibiniz internete erişebiliyor ve buna karşı bir kural yoksa, Apidog bulut sahtesi daha basittir çünkü dağıtılacak hiçbir şey yoktur. Aşağıdakilerden biri doğru olduğunda çalıştırma aracını tercih edin:
- Harici ana bilgisayarlara giden trafik engellenmiş veya yoğun bir şekilde denetleniyordur.
- Bir uyumluluk politikası, istek verilerinin dahili altyapıda kalmasını gerektiriyordur.
- Ortam hava boşluklu (air-gapped) olup, bulut uç noktasına hiç erişemiyordur.
- Sahte gecikme süresini genel internet üzerinden değil, kendi LAN'ınızda ölçmek istiyorsunuzdur.
Bunların hiçbiri geçerli değilse, fazladan Docker ana bilgisayarı ihtiyacınız olmayan bir yüktür. Bir sunucu sağlamadan önce hangi tarafta olduğunuza dair kendinize karşı dürüst olun.
Planlar ve izinler hakkında bir not. Apidog belgelerinde Genel Çalıştırma Aracı veya kendi kendine barındırılan sahte için açıkça ücretsiz-karşı-ücretli bir sınırlama belirtilmemiştir ve bunun için herhangi bir fiyatlandırma rakamı listelenmemiştir, bu nedenle bu kılavuz herhangi bir şey uydurmayacaktır. Kurulumun gerektirdiği şey, ekip veya proje yönetici iznidir, çünkü bir çalıştırma aracının dağıtımı Ekip Kaynakları (Team Resources) içinde gerçekleşir ve bu ayarlara yalnızca yöneticiler erişebilir. Kaynaklar panelini göremiyorsanız, nedeni budur.
Başlamadan önce neye ihtiyacınız var
Çalıştırma aracı bir Docker konteyneri olarak gelir, bu nedenle onu barındıracak sunucuda Docker yüklü olması gerekir. Belgeler minimum 20.10.0 sürümünü önermekte ve 20.10.13 veya daha yenisini tavsiye etmektedir. Ne kurduğunuzu kontrol edin:
docker --version
Ayrıca çalıştırmak için bir yere ihtiyacınız var: ekibinizin Apidog istemcilerinin ve Apidog hizmetinin erişebileceği bir Linux, macOS veya Windows makinesi. Bir intranette bu genellikle sabit bir IP veya ana bilgisayar adına sahip dahili bir sunucu anlamına gelir. Tüm önkoşul listesi bu kadar: Docker, bir ana bilgisayar ve ekip üzerinde yönetici hakları. Diğer her şeyi Apidog içinde yapılandırırsınız.
Genel Çalıştırma Aracını Dağıtın
Dağıtım komutu Apidog içinden sizin için oluşturulur ve bir belirteç (token) içerir, bu nedenle elle yazmanıza gerek yoktur. İşte akış:
Komutu oluşturun
Apidog Ana Sayfasını açın, ekibinizi seçin, ardından sağ kenar çubuğundaki Kaynaklar'a tıklayın ve Genel Çalıştırma Aracını Dağıt (Deploy General Runner) seçeneğini belirleyin. Birkaç ayar yapabileceğiniz bir açılır pencere belirecektir:
- Sunucu İşletim Sistemi: Linux, macOS veya Windows, böylece oluşturulan komut ana bilgisayarınızla eşleşir.
- Docker İmajı: Genel (General), İnce (Slim) veya Özel (Custom) seçin. Genel, Node.js 18, Java 21, Python 3 ve PHP 8 önceden yüklenmiş olarak gelir. İnce, daha küçük bir imaj için yalnızca Node.js 18 ile gelir. Özel, test betikleri için ek çalışma zamanlarına ihtiyacınız olduğunda kendi Dockerfile dosyanızı sağlamanıza olanak tanır.
- Maruz Kalan Bağlantı Noktası (Exposed Port):
-pparametresiyle ayarlanır, örneğin ana bilgisayar bağlantı noktası 80'i çalıştırma aracının dahili bağlantı noktasına eşleyen-p 80:4524gibi. - Bağlı Veri Dizini (Mounted Data Directory):
-vparametresiyle ayarlanır, böylece çalıştırma aracı verileri yeniden başlatmalar arasında ana bilgisayarda kalıcı olur.
İşiniz bittiğinde, oluşturulan komutu kopyalayın. Bu önemlidir: komut, veri güvenliği nedenleriyle yalnızca bir kez gösterilir, çünkü belirtecinizi (token) içerir. Kaybederseniz, eskiyi kurtarmak yerine yeni bir tane oluşturursunuz. Hemen yakalayın.
Sunucuda çalıştırın
Komutu sunucunuzun terminaline yapıştırın. Kurulum kendiliğinden başlar ve imajı çeker. Tamamlanmış bir komut kabaca şöyle görünür (sizinki farklı olacak ve gerçek belirteci içerecektir):
docker run -d \
--name apidog-runner \
-p 80:4524 \
-v /opt/apidog-runner/data:/app/data \
apidog/runner:latest \
--token <YOUR_GENERATED_TOKEN>
Konteynerin çalışır durumda olduğunu doğrulayın:
docker ps
Çalıştırma aracı konteynerinin bağlantı noktası eşlemesiyle birlikte listelendiğini görmelisiniz. Docker Desktop gibi bir Docker istemcisi, bir kullanıcı arayüzüne bakmak isterseniz aynı şeyi gösterir.
Kaydolduğunu onaylayın
Apidog'a geri dönün, Ekip Kaynakları'na (Team Resources) gidin ve Genel Çalıştırma Aracı'nı (General Runner) açın. Yenile düğmesine tıklayın. Çalıştırma aracı artık Dağıtıldı (Deployed) ve Başladı (Started) durumuyla görünmelidir. İlk başta görünmezse, yenile düğmesi çözümünüzdür; bir an bekleyin ve tekrar tıklayın.
Çalıştırma aracı durumu bilmeye değer üç halden oluşur:
- Başladı (Started): etkinleştirilmiş, Apidog ile iletişim kuruyor, görevleri yönetiyor. İstediğiniz durum budur.
- Durduruldu (Stopped): biri Apidog'da manuel olarak durdurdu. Dağıtılmış kalır ancak görevleri işlemez.
- Çevrimdışı (Offline): Apidog ile bağlantısını kaybetti, bu nedenle hiçbir şeyi işleyemez. Konteyneri ve ağ yolunu kontrol edin.
Çalıştırma Aracı Sahtesini Açın
Çalıştırma aracını dağıtmak size aracıyı sağlar. Bir adım daha sahte trafiğinizi ona yönlendirir.
Ekip Kaynakları'nda, Genel Çalıştırma Aracı'nı açın ve Sunucu Ana Bilgisayarı (Server Host) alanını bulun. Çalıştırma aracınızın erişilebilir olduğu adresi girin. Basit bir HTTP kurulumunda bu, yerel bir test için http://127.0.0.1:80 veya paylaşılan bir intranet ana bilgisayarı için http://runner.internal.example.com:80 gibi, maruz bıraktığınız ana bilgisayar ve bağlantı noktasıdır. TLS sonlandıran bir proxy'nin arkasında https://runner.example.com:443 gibi görünür. HTTPS hakkında birazdan daha fazla bilgi vereceğiz.
Sunucu Ana Bilgisayarı (Server Host) ayarlandıktan sonra, Apidog projeniz için Çalıştırma Aracı Sahte (Runner Mock) ortamını otomatik olarak bağlar. Doğrulayın: projeyi açın, Ortam Yönetimi'ne (Environment Management) gidin ve Çalıştırma Aracı Sahtesi'nin (Runner Mock) artık ortam listesinde göründüğünü onaylayın. Onu elle oluşturmadınız; Sunucu Ana Bilgisayarı'nı ayarlamak onun görünmesini sağladı.
Kendi kendine barındırılan sahte aracılığıyla bir istek gönderin
Şimdi onu kullanın. Dahili bir sipariş yönetimi API'si için bir projenizde GET /orders/{orderId} gibi bir uç noktanız olduğunu varsayalım. Bu uç noktayı açın, ardından üstteki ortam açılır menüsünden bulut ortamı yerine Çalıştırma Aracı Sahtesi'ni (Runner Mock) seçin. İsteği gönderin.
Yanıt çalıştırma aracınızdan gelir. Apidog, şemanızdan sahte veri oluşturduğu için, iyi tanımlanmış bir Order şeması, boş yer tutucular yerine gerçekçi değerler döndürür:
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"
}
Bu JSON hiçbir zaman genel internete dokunmadı. Çalıştırma aracı onu uç noktanızın şemasından oluşturdu ve ağınızın içinden sundu. Yukarıdaki customerEmail değeri gibi alan farkında oluşturma, Apidog'un şemanızın türlerini ve alan adlarını okumasından gelir; bu, akıllı sahte ile gerçekçi sahte verileri otomatik olarak oluşturma hakkındaki eşlik eden makalede ele alınan motorla aynıdır. Belirli bir isteğin tam olarak ne döndürdüğünü kontrol etmek isterseniz, uç noktaya bir sahte beklenti eklersiniz ve çalıştırma aracı bu beklentiyi bulut sahtesinin yapacağı gibi sunar. İyi sahte yanıtlar oluşturmanın mekaniği, sunucu Apidog'un veya sizin olsun fark etmez aynıdır; yalnızca ana bilgisayar değişir. API sahte oluşturma arkasındaki genel kavramlar değişmeden uygulanır.
HTTPS, veri bağlamaları ve diğer gerçek dünya detayları
http://127.0.0.1 üzerinde bir test çalıştırmak kolaydır. Paylaşılan bir intranet dağıtımının bir ekibe sunmadan önce bilmeye değer birkaç zorlu yanı vardır.
HTTPS için ters proxy gerekir
Çalıştırma aracının yerleşik HTTPS sertifika desteği yoktur ve otomatik sertifika sağlama yapmaz. Sizin için bir TLS sertifikası almaz veya yönetmez. https://'ye ihtiyacınız varsa, TLS'yi çalıştırma aracının önündeki bir ters proxy'de sonlandırın; örneğin sertifikanızı tutan bir Nginx kullanarak, ardından Sunucu Ana Bilgisayarı'nı (Server Host) proxy'nin HTTPS URL'sine yönlendirin. Proxy olmadan, http://ana_bilgisayar:bağlantı_noktası kullanın. Sunucu Ana Bilgisayarı'nı https:// olarak ayarlayıp çalıştırma aracının doğrudan TLS'ye yanıt vermesini beklemeyin; yapamaz.
4524 numaralı bağlantı noktasındaki bir çalıştırma aracının önünde yer alan minimalist bir Nginx bloğu şöyle görünür:
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;
}
}
Daha sonra Sunucu Ana Bilgisayarı https://runner.example.com:443 olur. TLS sonlandırma ekibiniz için yeni bir şeyse, HTTPS için MDN kılavuzu iyi bir hatırlatıcıdır.
Dosya bağlamaları yola özgüdür
Sahteleriniz veya testleriniz ek dosyalara ihtiyaç duyuyorsa, çalıştırma aracı bunları konteyner içinde sabit yollarda bekler, bu nedenle onları oraya bağlayın:
- Harici programlar
/app/external-programs/dizinine gider. - Veritabanı bağlantı yapılandırması
/app/database/database-connections.jsondizinine gider. - SSL istemci sertifikaları
/app/ssl/ssl-client-cert-list.jsondizinine gider.
Bunları -v bağlamalarınız aracılığıyla bağlayın, böylece yeniden başlatmalarda korunurlar.
Yeniden dağıtım ve yükseltme davranışı
Yeni bir çalıştırma aracı sürümü çıktığında, bir Yükselt (Upgrade) seçeneği görürsünüz ve Daha Fazla Eylem (More Actions) altında Yeniden Dağıt (Redeploy) yapabilirsiniz. Her ikisi de yeni konteyner çalışırken çalışan konteyneri durdurur. Güven verici kısım: Apidog istemcisindeki mevcut zamanlanmış görevler yeniden dağıtım veya yükseltmeden etkilenmez, bu nedenle yalnızca konteynerin yeniden başladığı an için canlı sunumu kesersiniz, yapılandırmayı kaybetmezsiniz.
Apidog CLI ile iş akışını otomatikleştirin
İşte kafa karışıklığını önleyen ayrım: çalıştırma aracı, sahteleri sunabilen ve zamanlanmış görevleri çalıştırabilen uzun ömürlü bir aracıdır; Apidog CLI ise CI için tek seferlik bir test çalıştırma aracıdır. Bunlar farklı araçlardır. CLI, bir sahte sunucuya hizmet veremez, başlatamaz veya barındıramaz. apidog run mock veya apidog mock serve diye bir komut yoktur. CLI'nin apidog run komutu test senaryolarını, test senaryo klasörlerini ve test paketlerini yürütürken, mock komut grubu yalnızca sahte beklentiler üzerinde veri olarak CRUD işlemleri yapar. Sahte sunumu, çalıştırma aracının işidir, asla CLI'nin değil.
Yani ikisi şöyle bir araya gelir. CLI ve Cursor, Claude Code ve Codex gibi yapay zeka kodlama ajanları, projenizdeki uç noktaları ve şemaları oluşturup güncelleyebilir, bu da spesifikasyon geliştikçe sahte çıktınızın doğru kalmasını sağlar. Kendi kendine barındırılan sahte, ön uç çalışmalarının önündeki engelleri kaldırdıktan sonra, aynı projenin test senaryoları tek bir komutla CI'da başsız olarak çalışır ve gerçek arka ucu sahtenin tanımladığı sözleşmeye karşı doğrular:
apidog run -t <scenario_id> -e <env_id> -r html,cli
Bu tek komut, senaryolarınızı canlı arka uca karşı çalıştırır ve bir HTML ile CLI raporu yazar. Kurulum Node.js v16 veya sonrası üzerinde npm install -g apidog-cli şeklindedir; Apidog CLI kurulum kılavuzu apidog login ve belirteç (token) kurulumunu kapsar. Her push işleminde bu testin çalışmasını sağlamak için, Apidog CLI CI/CD kılavuzu ile onu pipeline'ınıza bağlayın. CLI'dan API'leri sahte oluşturma hakkındaki makale, terminalin sahte tanımlarını neden yönettiğini ancak barındırmadığını tam olarak açıklar.
Sıkça Sorulan Sorular
Ekibim internete erişebiliyorsa kendi kendine barındırılan çalıştırma aracına ihtiyacım var mı?
Muhtemelen hayır. Bulut sahtesi (cloud mock) hiçbir dağıtım gerektirmez ve daha basit bir yoldur. Giden trafik engellendiğinde veya denetlendiğinde, bir uyumluluk kuralı verileri dahili altyapıda tuttuğunda veya ortam hava boşluklu (air-gapped) olduğunda çalıştırma aracını seçin. Barındırılan yaklaşımı yönetilen yaklaşımla karşılaştırıyorsanız, Apidog bulut sahtesi incelemesi bu kılavuzun doğal bir tamamlayıcısıdır.
Apidog CLI kendi kendine barındırılan bir sahte sunucu başlatabilir mi?
Hayır. CLI, apidog run ile testleri çalıştırır ve mock komut grubuyla sahte beklentilerini veri olarak yönetir. Sahte trafiğe hizmet vermek Genel Çalıştırma Aracı (General Runner) veya bulut sahtesi (cloud mock) tarafından yapılır, asla CLI tarafından değil. Tek bir terminal komutu yazıp bir bağlantı noktasında çalışan bir sahte bekliyorsanız, bu çalıştırma aracının işidir ve yukarıda açıklandığı gibi GUI üzerinden kurulur.
Çalıştırma aracı kendi başına HTTPS'yi destekler mi?
Sertifikaları birlikte göndermez veya otomatik olarak sağlamaz. TLS'yi sonlandırmak için önüne Nginx gibi bir ters proxy koyun, ardından Sunucu Ana Bilgisayarı'nı (Server Host) proxy'nin https:// URL'sine yönlendirin. Proxy olmadan, http://ana_bilgisayar:bağlantı_noktası kullanın.
Komutu çalıştırdıktan sonra çalıştırma aracım neden görünmüyor?
Ekip Kaynakları'nı (Team Resources) açın, Genel Çalıştırma Aracı'na (General Runner) gidin ve yenile düğmesine tıklayın. Kayıt işlemi bir an gecikebilir. Hala görünmüyorsa, konteynerin docker ps ile çalıştığını ve ana bilgisayarın Apidog'dan erişilebilir olduğunu onaylayın. Çevrimdışı (Offline) durumu bağlantının kesildiği anlamına gelir; Başladı (Started) durumu istediğinizdir.
Birden fazla ekip, küresel sahte sunumu için tek bir çalıştırma aracını paylaşabilir mi?
Bir çalıştırma aracı, onu dağıttığınız ekibe kaydolur ve Çalıştırma Aracı Sahte (Runner Mock) ortamı her projede belirir. Sahte ortamları paylaşan dağıtılmış ekipleri yönetiyorsanız, küresel ekipler arasında sahte ortamları paylaşma kılavuzundaki modeller, kaç tane çalıştırma aracı kuracağınıza ve nerede kuracağınıza karar vermenize yardımcı olacaktır.
Özet
Genel Çalıştırma Aracı (General Runner) ile kendi kendine barındırılan sahte oluşturma, sahte tasarımınız her zaman olduğu gibi Apidog projenizde kalırken, istek verilerinizi kontrol ettiğiniz altyapıda tutar. Bir Docker konteyneri dağıtırsınız, Sunucu Ana Bilgisayarı'nı (Server Host) ayarlarsınız ve Çalıştırma Aracı Sahte (Runner Mock) ortamı gerisini halleder. Bulut erişilemez olduğunda onu tercih edin, erişilebilir olduğunda ise bulut sahtesini kullanın. Kendi ağınızda sahteleri çalıştırmaya hazır mısınız? Apidog'u indirin, bir çalıştırma aracı dağıtın ve intranetinizi tek bir paket bile terk etmeden ilk Çalıştırma Aracı Sahte yanıtınızı sunun.