DEV Community: İsa Sarıoğlan

Liman MYS Eklentisi ile Elasticsearch API'sine Bağlanma Rehberi

İsa Sarıoğlan — Thu, 04 Dec 2025 10:51:31 +0000

Bu yazı, Liman MYS eklenti şablonunu kullanarak, Basic Authentication (Kullanıcı Adı/Şifre) ile korunan bir Elasticsearch API'sine bağlanmayı ve veri çekmeyi adım adım anlatır.

Bu rehber, zaten çalışan bir Liman MYS geliştirme ortamınız olduğunu varsayar.

Eğer henüz sunucunuza SSH ile bağlanmadıysanız, liman kullanıcısı için yetkilendirme yapmadıysanız, VS Code Remote - SSH eklentisini kurmadıysanız veya Node.js/pnpm kurulumunu tamamlamadıysanız, lütfen öncelikle aşağıdaki rehberi okuyun:

➡️ Referans: Liman MYS Eklentisi Geliştirme Ortamı Sorun Rehberi

Bu rehberdeki adımları tamamladıktan sonra buradan devam edebilirsiniz.

Adım 1: Eklenti Ayarlarını Yapılandırma (db.json)

Amacımız Eklentimizin, bağlanacağı API'nin adresini, kullanıcı adını ve şifresini Liman arayüzünden güvenli bir şekilde almasını sağlamak.

db.json dosyası, Liman'ın "Eklenti Ayarları" menüsüne hangi ayar alanlarını ekleyeceğimizi tanımlar.

Eklentinizin ana dizininde bulunan db.json dosyasını açın.
database isimli JSON dizisini bulun.
Bu dizinin içine, API URL'si, kullanıcı adı ve şifre için aşağıdaki üç JSON objesini ekleyin.

{
  "name": "elasti",
  "publisher": "...",
  "version": "...",
  "database": [
    {
      "variable": "api_url",
      "type": "text",
      "name": "API URL (ex. https://10.67.67.202:30936)",
      "required": true,
      "global": true,
      "writable": false
    },
    {
      "variable": "Username",
      "type": "text",
      "name": "Elasticsearch Username",
      "required": true,
      "global": true,
      "writable": false
    },
    {
      "variable": "Password",
      "type": "password",
      "name": "Elasticsearch Password",
      "required": true,
      "global": true,
      "writable": false
    }
  ],
  "language": "php",
  "vite": true,
  "...": "..."
}

Detaylı Açıklama:

"variable": "api_url": Bu, PHP kodumuzun içinden extensionDb('api_url') fonksiyonunu kullanarak bu değere erişmesini sağlayan anahtar isimdir.
"type": "password": Bu ayar, Liman arayüzündeki bu metin kutusuna girilen değerin **** şeklinde maskelenmesini sağlar. Güvenlik için kritik bir adımdır.
"global": true: Ayarın eklenti bazında global olmasını sağlar.

Önemli: Bu değişikliği yaptıktan sonra eklentinizi Liman arayüzünden Yeniden Yükle yapın ve Eklenti Ayarları'na giderek API URL,Elasticsearch Username ve Elasticsearch Password olmak üzere aşşağıdaki görselde bulunan üç alanı da doldurun

Adım 2: helpers.php Dosyasını Güncelleme (Yetkilendirme)

Bu adımda amacımız PHP backend'imizin, Adım 1'de kaydettiğimiz ayarları okuyup Elasticsearch'e Basic Authentication başlığını (header) göndermesini sağlamak.

helpers.php dosyası, backend kodumuzun her yerinden çağırabileceğimiz yardımcı fonksiyonları barındırır. getDefaults() fonksiyonu, eklentimizden dışarı giden her API isteği için varsayılan ayarları belirler.

/views klasörünün (veya ana dizinin) yanındaki helpers.php dosyasını açın.
getDefaults() fonksiyonunu bulun.
Bu fonksiyonun tamamını, db.json'dan Username ve Password değişkenlerini okuyacak ve Authorization başlığını oluşturacak şekilde aşağıdaki gibi güncelleyin.

if (!function_exists('getDefaults')) {
    function getDefaults()
    {
        // 1. ADIM: db.json'dan kullanıcı adı ve şifreyi al
        $username = extensionDb('Username');
        $password = extensionDb('Password');

        // 2. ADIM: Basic Auth için kullanıcı adı ve şifreyi "kullanıcı:şifre" formatında
        // base64 algoritmasıyla kodla
        $auth = base64_encode($username . ':' . $password);

        // 3. ADIM: Guzzle (PHP HTTP istemcisi) için ayar dizisini oluştur
        return [
            'headers' => [
                'Content-Type' => 'application/json',

                // Oluşturduğumuz kodu "Authorization" başlığına "Basic " ön ekiyle ekle
                'Authorization' => 'Basic ' . $auth,
            ],

            // 4. ADIM: SSL Sertifika Doğrulamasını Kapat
            // Eğer API'niz (https://...) kendinden imzalı (self-signed)
            // bir sertifika kullanıyorsa bu gereklidir. Aksi halde bağlantı hatası alırsınız.
            'verify' => false 
        ];
    }
}

Adım 3: CORS ve HMR Hatalarını Önleme (vite.config.ts)

Amacımız localhost sorununu çözdükten sonra ortaya çıkan CORS policy (farklı port) ve WebSocket (HMR) bağlantı hatalarını en baştan engellemek.

Sorun: Liman arayüzü (örn: https_://10.68.68.249) ile Vite sunucusu (örn: https_://10.68.68.249:5173) farklı portlarda çalıştığı için tarayıcı bunu "güvenliksiz" bir işlem olarak görür ve CORS hatası verir.

frontend/vite.config.ts dosyasını açın.
defineConfig objesine, plugins ve resolve gibi anahtarların yanına, server adında yeni bir yapılandırma bloğu ekleyin.

// CORS VE HMR HATALARINI ÖNLEMEK İÇİN BU BLOĞU EKLEYİN
  // ###############################################################
  server: {
    // 1. Sunucunun tüm IP'lerden gelen isteklere yanıt vermesini sağlar
    // (Sadece localhost'tan değil)
    host: '0.0.0.0', 

    // 2. CORS HATASININ ÇÖZÜMÜ:
    // Bu ayar, tarayıcıya "Access-Control-Allow-Origin: *" başlığını gönderir
    // ve farklı portlardan (örn: Liman'ın 443 portu) gelen isteklere izin verir.
    cors: true, 

    // 3. HMR (WebSocket) HATASININ ÇÖZÜMÜ:
    // Kodda değişiklik yaptığınızda sayfanın otomatik yenilenmesi (HMR)
    // için Vite bir WebSocket bağlantısı kullanır. Bu ayar,
    // WebSocket'in hangi IP'ye bağlanacağını söyler.
    hmr: {
      host: '10.68.68.249' // Buraya Vite sunucunuzun IP'sini yazın
    }
  }
  // ###############################################################

Adım 4: Geliştirme Sunucusu Sertifika (SSL) Uyarısını Geçme

Amacımız Tarayıcınızın, Vite geliştirme sunucusunun "kendinden imzalı" (self-signed) SSL sertifikasına güvenmesini sağlamak.

Adım 3 ve 4'ü yapsanız bile, pnpm run dev komutunu çalıştırdıktan sonra eklentiyi açtığınızda konsolda net::ERR_TIMED_OUT veya net::ERR_CERT_AUTHORITY_INVALID hatası alabilirsiniz.

Vite sunucusu (https://10.68.68.249:5173) https kullanır ancak resmi olmayan bir sertifikaya sahiptir. Tarayıcınız, sizden onay almadan bu "güvenli olmayan" adresten script (main.ts) yüklemeyi reddeder.

Çözüm: Tarayıcınıza bu adrese güvenmesini manuel olarak öğretmeniz gerekir.

Vite sunucunuzun adresini (örn: https://10.68.68.249:5173) kopyalayın.
Tarayıcınızda yeni bir sekme açın.
Bu adresi yapıştırın ve Enter'a basın.
Karşınıza "Bağlantınız gizli değil" (Your connection is not private) uyarısı çıkacaktır.
"Gelişmiş" (Advanced) butonuna tıklayın.
"10.68.68.249 sitesine ilerle (güvenli değil)" (Proceed to 10.68.68.249 (unsafe)) linkine tıklayın.
Ekrana beyaz bir sayfa veya "Vite" logosu gelirse, işlem başarılıdır. Bu sekmeyi kapatabilirsiniz.

Bu işlemi yaptığınızda, tarayıcınız bu sertifikayı geçici olarak kabul etmiş olur ve Liman arayüzü artık main.ts dosyasını yükleyebilir.

Adım 5: Frontend Veri Katmanını Oluşturma (elastic.ts)

data.ts dosyasını kopyalayıp elastic.ts adında yeni bir dosya oluşturmanızı ve içeriğini aşağıdaki gibi düzenlemenizi istiyorum.

Bu dosyada, data.ts içindeki tüm CRUD (create, update, delete) fonksiyonlarını kaldıracağız. Sadece bizim Elastic API'mizden veri çekecek fetchStats adında tek bir fonksiyon bırakacağız. Bu fonksiyon, RequestController.php dosyanızdaki apiProxy fonksiyonunu tetikleyecek.

Komut parametrelerini URL'den (GET) gönderdiğimiz takdirde RequestController.php'deki apiProxy fonksiyonu, GET isteğiyle gelen URL parametrelerini (örn: ?type=...) hedef API'ye (Elasticsearch) "taşıma" eğilimindedir. Elasticsearch bu type ve endpoint parametrelerini tanımadığı için hata verir.

bu yüzden komut parametrelerini URL'den (GET) göndermek yerine bir POST isteğinin gövdesinde (body) göndereceğiz. RequestController bu verileri gövdeden okuyacak ve Elasticsearch'e "temiz" bir GET isteği atacaktır.

src/stores/data.ts dosyasını kopyalayıp src/stores/elastic.ts adında yeni bir dosya oluşturun.
İçeriğini aşağıdaki gibi (hatayı en baştan önleyecek şekilde) düzenleyin:

import http from "@/utils/http-common"
import { i18n } from "@/utils/i18n"
import { defineStore } from "pinia"

// Store adını useElasticStore olarak değiştiriyoruz
export const useElasticStore = defineStore({
  id: "elastic",
  state: () => ({
    elasticData: {} as any, // Gelen veriyi tutmak için
  }),
  getters: {
    getStats: (state) => state.elasticData,
  },
  actions: {
    // Veri çekme fonksiyonumuz
    async fetchStats() {

      // Parametreleri POST gövdesinde göndermek için hazırlıyoruz
      const payload = {
        // Backend'e "get" isteği yapmasını söylüyoruz
        type: "get",
        // Backend'e hangi uca gitmesini istediğimizi söylüyoruz
        endpoint: "_nodes/stats/fs?pretty=true" 
      }

      // Hata almamak için http.get yerine http.post kullanıyoruz.
      // RequestController bu POST gövdesini okur
      // ve Elastic'e temiz bir GET isteği atar.
      // İlk parametre olan URL'e sadece "?" koymamız, 
      // apiProxy'nin kök dizine gitmesini sağlar.
      return http.post(`?`, payload).then((res) => {
        if (res.status == 200) {
          if (res.data) {
            this.elasticData = res.data
            console.log("Elastic verisi başarıyla alındı:", res.data)
          }
        } else {
          window.$notification.error({
            duration: 5000,
            title: i18n.t("common.error"),
            content: "Elastic verisi alınırken bir hata oluştu.",
          })
        }
      })
    },
  },
})

Adım 6: RequestController.php Debug (Hata Ayıklama)

Lütfen RequestController.php dosyanızı açın ve apiProxy fonksiyonunu bulun.

Bu fonksiyonun içine, validate([...]); satırından hemen sonra, aşağıdaki dd() satırlarını ekleyin. Bu sayede frontend'den gelen isteği yakalayıp, API'ye gitmeden önce tam olarak hangi URL'i ve hangi ayarları kullandığımızı göreceğiz.

// --- DEBUG BAŞLANGIÇ ---
        // Bu iki satırı ekleyin:

        // 1. Doğru URL'i oluşturup oluşturmadığımızı kontrol edelim
        dd(extensionDb('api_url') . '/' . request("endpoint"));

        // 2. helpers.php'den doğru ayarların (Auth Header) gelip gelmediğini kontrol edelim
        // (Eğer ilk dd çalışırsa, tarayıcıda sonucu gördükten sonra bu satırı açıp ilkini silebilirsiniz)
        // dd(getDefaults()); 

        // --- DEBUG BİTİŞ ---

Adım 7: Home.vue Dosyasını Düzenleme ve Debug'ı Tetikleme

Bu adımda, Home.vue dosyanızı, oluşturduğumuz elastic.ts store'unu kullanacak şekilde düzenleyeceğiz.

Yeni useElasticStore'u import edeceğiz.
onMounted (sayfa yüklendiğinde) store.fetchStats() fonksiyonunu çağıracağız.
Gelen veriyi basit bir <pre> etiketi içinde ekrana basacağız.

Lütfen src/views/Home.vue dosyanızın içeriğini tamamen aşağıdaki kodla değiştirin:

<script lang="ts" setup>
import { onMounted } from "vue"
// 1. Oluşturduğumuz elastic store'u import et
import { useElasticStore } from "@/stores/elastic"

// 2. Store'u kur
const store = useElasticStore()

// 3. Sayfa yüklendiğinde fetchStats fonksiyonunu çalıştır
onMounted(() => {
  store.fetchStats()
})
</script>

<template>
  <div>
    <h2>Elasticsearch FS İstatistikleri</h2>
    <pre>{{ store.elasticData }}</pre>
  </div>
</template>

<style scoped>
pre {
  background-color: #f4f4f4;
  border: 1px solid #ddd;
  padding: 10px;
  white-space: pre-wrap; /* Uzun satırların kaydırmasını sağlar */
  word-wrap: break-word;
}
</style>

Şimdi Test Edelim:

Bu değişikliği kaydedin.
Projenizin derlendiğinden emin olun (genellikle pnpm run dev veya pnpm run serve).
Tarayıcınızı açın ve Liman arayüzünden eklentinize gidin.
Tarayıcınızın Geliştirici Araçları'nı açın (F12) ve "Ağ (Network)" sekmesine tıklayın.
Eklentinizin ana sayfasını (Home.vue) açın veya yenileyin.

Beklenen Sonuç:

Sayfanız büyük ihtimalle yüklenmeyecek (veya "500 Sunucu Hatası" gibi bir hata gösterecek).

Ağ (Network) sekmesinde, apiProxy?type=get&endpoint=... ile başlayan kırmızı bir istek görmelisiniz. Bu isteğe tıklayın ve "Önizleme (Preview)" veya "Yanıt (Response)" sekmesine bakın.

Orada, RequestController.php içine yazdığımız ilk dd() komutunun çıktısını görmeniz gerekiyor. Çıktı, bir string (metin) olarak şunu içermeli:

"https://10.67.67.202:30936/_nodes/stats/fs?pretty=true" (Eğer db.json'a IP'yi 10.67.67.202 olarak girdiyseniz)

ilk debug komutunda istediğimiz sonuçlara ulaştıktan sonra ikinci debug komutunu tetikleyelim.

Lütfen RequestController.php dosyasını açın.
validate([...]); satırından hemen sonra, dd(getDefaults()); satırını aşşağıdaki gibi yorum satırı olmaktan çıkarıp ilk debug komutunu yorum satırına alalım.

// --- DEBUG BAŞLANGIÇ ---
        // Bu iki satırı ekleyin:

        // 1. Doğru URL'i oluşturup oluşturmadığımızı kontrol edelim
        // dd(extensionDb('api_url') . '/' . request("endpoint"));

        // 2. helpers.php'den doğru ayarların (Auth Header) gelip gelmediğini kontrol edelim
        // (Eğer ilk dd çalışırsa, tarayıcıda sonucu gördükten sonra bu satırı açıp ilkini silebilirsiniz)
         dd(getDefaults()); 

        // --- DEBUG BİTİŞ ---

Şimdi Test Edin:

Dosyayı bu şekilde kaydedin.
Tarayıcıda Geliştirici Araçları (F12) açıkken sayfayı yenileyin (F5).
Network sekmesinde yine kırmızı bir apiProxy isteği göreceksiniz.
Bu isteğe tıklayın ve "Önizleme (Preview)" sekmesine bakın.

Beklenen Sonuç: Bu kez, ekranda o URL'i görmemelisiniz. Onun yerine "Önizleme (Preview)" sekmesinde, Authorization başlığını içeren şu JSON objesini görmelisiniz:

Bu çıktıyı gördüğünüzde kimlik doğrulama adımını başarıyla geçtiğimiz anlamına gelecek.
Artık tüm testlerimiz (debug) bitti. Backend'imiz (PHP) isteği göndermeye hazır.

Şimdi son adıma geçiyoruz: Yola koyduğumuz tüm bu "tuzakları" (yani dd() komutlarını) kaldıracağız ve isteğin Elastic API'sine gerçekten gitmesine izin vereceğiz.

Adım 8: Eklentiyi Çalıştırma ve Son Test

Tüm dosyaları doğru şekilde yapılandırdık. Artık eklentiyi çalıştırabiliriz.

Önemli: Geliştirme (Dev) ve Üretim (Build) Modu Farkı

Geliştirme (Dev) Modu:
pnpm run dev ile çalışır. Kodunuzda yaptığınız her değişiklik anında tarayıcıya yansır (vite: true ve HMR sayesinde). Bu mod, eklentiyi aktif olarak geliştirirken kullanılır.
Üretim (Build) Modu:
pnpm run build ile çalışır. Tüm Vue/TS kodunuzu derleyip optimize edilmiş, tek bir statik JavaScript dosyası haline getirir. Eklentiyi bitirip son kullanıcıya sunacağınız zaman bu modu kullanırsınız ve db.json'daki vite: true ayarını vite: false yaparsınız.
Terminalde frontend klasörüne gidin (/liman/extensions/elasti/frontend).
Gerekli paketlerin yüklü olduğundan emin olun:

pnpm install

Vite geliştirme sunucusunu (tüm ayarlarıyla beraber) başlatın:

pnpm run dev --host 0.0.0.0

Liman arayüzüne gidin (tarayıcıdan).
Sol menüden eklentinizi açın.
KRİTİK ADIM: Geliştirme sunucusunu görmek için, eklentinizin normal URL'inin sonuna /development eklemeniz gerekir.

Yanlış Adres: https://.../l/e/elasti (Bu, üretim modunu (build) açar)

Doğru Adres: https://.../l/e/elasti/development (Bu, pnpm run dev sunucusuna bağlanır)

Nihai Sonuç: .../development adresini açtığınızda, ekrandaElasticsearch FS İstat istikleri başlığının altında, API'den gelen (içinde _nodes, cluster_name vb. bulunan) JSON verisinin tamamını hatasız bir şekilde aşşağdaki şekilde arayüzde görmelisiniz.

Liman MYS için Eklenti Geliştirme Ortamı Kurulum Rehberi

İsa Sarıoğlan — Thu, 04 Dec 2025 10:43:34 +0000

Liman MYS, sunucu yönetimini kolaylaştıran güçlü bir platform olmasının yanı sıra, esnek eklenti altyapısıyla da öne çıkar. Bu rehberde, "Liman Extension Template" adını vereceğimiz hazır bir eklenti şablonunu kullanarak, kod değişikliklerimizi anında Liman arayüzünde görebileceğimiz profesyonel bir geliştirme ortamını nasıl kuracağımızı adım adım inceleyeceğiz.

Bölüm 1: Eklenti Şablonunu Liman'a Yükleme

Geliştirme ortamını kurmadan önce, üzerinde çalışacağımız eklentinin Liman tarafından tanınması gerekir. Bu nedenle, hazır eklenti şablonumuzu sisteme yüklüyoruz.

Liman MYS web arayüzünde oturum açın ve sağ üst köşedeki Ayarlar simgesine tıklayın.
Açılan menüden Sistem Ayarları seçeneğine ve ardından sol menüden Eklentiler sekmesine gidin.
Yükle butonuna tıklayarak bilgisayarınızdaki .zip uzantılı eklenti şablonu dosyasını seçin ve yüklemeyi tamamlayın.
Yükleme başarılı olduğunda, eklentiniz listede görünecektir.

Bu adımdan sonra artık eklentimizi arayüzden silip yüklemeyeceğiz. Tüm süreci sunucu tarafında yöneteceğiz.Bu ksımla ılgili detaylı bilgi aşşağıdaki linkten erişebilirsiniz.

Limana Eklenti Yükleme

Bölüm 2: Sunucuya Bağlantı ve Yetkilendirme Hazırlıkları

Bu bölümde, geliştirme yapacağımız sunucuya SSH üzerinden bağlanacak ve VS Code ile sorunsuz bir bağlantı kurmak için gerekli yapılandırmaları yapacağız.

Adım 1: Sunucuya İlk Bağlantı

Öncelikle sunucunuza standart kullanıcınız ile (genellikle ubuntu, centos, debian vb.) bağlanın.

ssh kullanici_adiniz@<SUNUCU_IP_ADRESINIZ>

<SUNUCU_IP_ADRESINIZ>kısmını Liman'ın kurulu olduğu sunucunun IP adresi ile değiştirin.

Bu aşamada sizden sunucu şifreniz istenecektir.

Adım 2: liman Kullanıcısını Geliştirmeye Hazırlama

Liman, sistem üzerinde kendi işlemlerini yönetmek için genellikle liman adında bir kullanıcı oluşturur. Geliştirme yaparken yetki ve sahiplik sorunları yaşamamak adına işlemlerimizi bu kullanıcı üzerinden yürütmek en sağlıklı yöntemdir.

liman Kullanıcısına Şifre Atama:

liman kullanıcısının varsayılan olarak bir şifresi olmayabilir. SSH bağlantısı için bir şifre belirlememiz gerekiyor.

sudo passwd liman

Bu komutu çalıştırdıktan sonra liman kullanıcısı için yeni bir şifre belirlemeniz istenir.Şifre belirledikten sonra terminale aşağıdaki formatta bağlantı komutunu girin:

ssh liman@<SUNUCU_IP_ADRESINIZ>

Bu komut,liman adlı kullanıcıya bağlanmamızı sağlar.

liman Kullanıcısının Kabuğunu (Shell) Değiştirme:

Güvenlik nedeniyle liman kullanıcısının kabuğu interaktif olmayan bir kabuk (/usr/bin/login gibi) olabilir. Etkileşimli bir terminal deneyimi için bu kabuğu bash olarak değiştirmeliyiz.

sudo usermod --shell /bin/bash liman

Bu komut, liman kullanıcısının oturum açtığında standart bir Bash terminali kullanmasını sağlar.

Adım 3: Şifresiz ve Güvenli Bağlantı için SSH Anahtarı Oluşturma

Her seferinde şifre girmek yerine, SSH anahtar tabanlı kimlik doğrulama kullanarak süreci otomatikleştirebiliriz.

SSH Anahtar Çifti Oluşturma (Lokal Makinenizde):

Eğer daha önce oluşturmadıysanız, kendi bilgisayarınızın terminalinde aşağıdaki komutu çalıştırın:

ssh-keygen

"Enter file in which to save the key...": Bu soruya Enter'a basarak varsayılan konumu onaylayın.

"Enter passphrase...": Daha fazla güvenlik için bir parola belirleyebilirsiniz, ancak geliştirme kolaylığı için bu adımı Enter'a basarak boş geçebilirsiniz.

Public Anahtarı Sunucuya Kopyalama:

Oluşturduğunuz public anahtarı (.pub uzantılı olan) Liman sunucusundaki liman kullanıcısının yetkilendirilmiş anahtarlar listesine ekleyeceğiz.

ssh-copy-id liman@<SUNUCU_IP_ADRESINIZ>

Bu komut sizden son bir kez liman kullanıcısının şifresini isteyecektir. Şifreyi girdikten sonra, artık ssh liman@<SUNUCU_IP_ADRESINIZ> komutuyla şifresiz bir şekilde sunucuya bağlanabilirsiniz.

Bölüm 3: Visual Studio Code ile Geliştirme Ortamını Yapılandırma

Artık sunucu tarafı hazır olduğuna göre, kodlarımızı doğrudan sunucu üzerinde düzenlemek için VS Code'u yapılandıracağız. Her seferinde IP adresi ve kullanıcı adı yazmak yerine, SSH yapılandırma dosyasına kalıcı bir kayıt ekleyerek bağlantı sürecini otomatikleştireceğiz.

Adım 1:"Remote - SSH" Eklentisini Yükleyin

VS Code'u açın, sol taraftaki Eklentiler (Extensions) sekmesine gidin, arama çubuğuna Remote - SSH yazın ve Microsoft tarafından geliştirilen eklentiyi yükleyin.

Adım 2: Kalıcı Bir SSH Bağlantısı Oluşturma (Config Dosyası)

Bu adım, sunucu bağlantı bilgilerimizi config adında özel bir dosyaya kaydederek, bu bağlantıya kolayca hatırlanabilir bir isim vermemizi sağlar.

SSH Yapılandırma Dosyasını Açın:

Kendi lokal bilgisayarınızda, bir terminal veya komut istemi açın. SSH yapılandırma dosyasını bir metin editörü ile açın. Bu dosya genellikle aşağıdaki konumlarda bulunur:

Linux veya macOS: ~/.ssh/config
Windows: C:\Users\KULLANICI_ADINIZ\.ssh\config

Not:
Eğer .ssh klasörü veya config dosyası mevcut değilse, kendiniz oluşturabilirsiniz.

Kendi lokal bilgisayarınızda bir terminal açın. nano gibi kullanımı kolay bir terminal editörü ile yapılandırma dosyasını doğrudan açmak için aşağıdaki komutu çalıştırın:


nano ~/.ssh/config

Not: nano editöründe dosyayı kaydetmek için Ctrl+O (Write Out) ve ardından Enter'a, çıkmak için ise Ctrl+X tuş kombinasyonunu kullanabilirsiniz.

Eğer Windows kullanıyorsanız ve terminal kullanmak istemiyorsanız, dosyayı C:\Users\KULLANICI_ADINIZ.ssh\config konumunda bulup Not Defteri (Notepad) gibi bir metin editörü ile de açabilirsiniz.

(Eğer .ssh klasörü veya config dosyası mevcut değilse, komut dosyayı sizin için oluşturacaktır.)

Yeni host bilgilerini eklemek için aşşağıdaki işlemleri gerçekleştirin.

Açtığınız config dosyasına aşağıdaki bloğu ekleyin ve kendi bilgilerinizle doldurun:

# Liman MYS Geliştirme Sunucusu
Host liman-dev-sunucusu
    HostName <SUNUCU_IP_ADRESINIZ>
    User liman
    IdentityFile ~/.ssh/id_rsa

Host: Bağlantınızın kısa adıdır. VS Code'da görünecek ve kullanacağınız isim budur.
HostName: Liman sunucusunun gerçek IP adresi.
User: Bağlanacağınız kullanıcı adı, yani liman.
IdentityFile: Şifresiz bağlantı için oluşturduğunuz SSH özel anahtarınızın yolu (~/.ssh/id_rsa genellikle varsayılandır).
Dosyayı kaydedip kapatın.

Adım 3: VS Code ile Yapılandırılmış Host'a Bağlanma

Ctrl+Shift+P (veya F1) tuş kombinasyonu ile komut paletini açın.

Remote-SSH: Connect to Host... yazıp seçin.

Karşınıza çıkan listede, config dosyasına eklediğiniz Host isminin (liman-dev-sunucusu gibi) doğrudan göründüğünü göreceksiniz.Bu isme tıklayarak bağlantıyı başlatın.

VS Code yeni bir pencere açacaktır. Sol alt köşede "SSH: liman-dev-sunucusu" yazdığını gördüğünüzde, bağlantı başarıyla kurulmuş demektir.

Adım 4:Eklenti Klasörünü Açma

VS Code'da File > Open Folder... (veya Dosya > Klasör Aç...) seçeneğine tıklayın.

Açılan diyalog kutusuna eklentilerin bulunduğu yolu girin: /liman/extensions/

OK butonuna tıklayın.

Artık sol taraftaki dosya gezgininde, sunucudaki tüm eklenti dosyalarınızı görebilirsiniz. Yaptığınız her değişiklik anında sunucuya kaydedilecektir.

Bölüm 4: Eklentiyi Derleme ve Geliştirme Modunu Aktif Etme

Son aşamada, kodumuzun canlı olarak derlenmesini ve Liman arayüzünde görüntülenmesini sağlayacağız.

Adım 1 :Node.js ve pnpm Kurulumu (Gerekliyse)

Eklenti bağımlılıklarını yönetmek ve derleme işlemlerini yapmak için pnpm paket yöneticisine ihtiyacımız var. pnpm'in çalışabilmesi için de öncelikle sunucunuzda Node.js'in kurulu olması gerekmektedir.

Node.js Kurulumu:

Eğer sunucunuzda Node.js kurulu değilse veya çok eski bir sürüm varsa, aşağıdaki komutlarla güncel bir LTS (Uzun Süreli Destek) sürümünü kurabilirsiniz.

# Terminalde aşağıdaki komutları sırasıyla çalıştırın:

# Node.js 22.x LTS sürümü için kurulum betiğini indirip çalıştırın
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Node.js ve beraberinde gelen npm'i yükleyin
sudo apt-get install -y nodejs

# Kurulumun başarılı olduğunu kontrol edin
node -v
npm -v

Bu komutlar sonunda v22.x.x ve v10.x.x gibi sürüm numaraları görmelisiniz.

PNPM Kurulumu:

Node.js ve npm'i kurduktan sonra, npm'i kullanarak pnpm'i global olarak (sistemin her yerinden erişilebilir şekilde) kurabiliriz.

# npm kullanarak pnpm'i global olarak yükleyin
sudo npm install -g pnpm

# pnpm kurulumunu kontrol edin
pnpm -v

Bu komut sonunda pnpm'in sürüm numarasını (9.x.x gibi) görüyorsanız, kurulum tamamlanmıştır.

Adım 2: Bağımlılıkları Yükleme

Artık pnpm kurulu olduğuna göre, eklentimizin ihtiyaç duyduğu kütüphaneleri ve paketleri yükleyebiliriz.
VS Code içerisinde Terminal > New Terminal (veya Terminal > Yeni Terminal) menüsünden yeni bir terminal açın. Bu terminalin doğrudan sunucunuzda, açtığınız klasör yolunda (/liman/extensions/) açıldığına dikkat edin.

Üzerinde çalıştığınız eklentinin klasörüne girin (örneğin: cd eklenti-adiniz).

Proje bağımlılıklarını yüklemek için aşağıdaki komutu çalıştırın:

pnpm install

Bu komut, package.json dosyasını okur ve projenin ihtiyaç duyduğu tüm kütüphaneleri node_modules klasörü altına indirir.

Geliştirme Sunucusunu Başlatma:

Aynı terminalde, projenin canlı olarak derlenmesini ve dosya değişikliklerini izlemesini sağlayacak komutu çalıştırın:

pnpm run dev

Bu komut, genellikle arkaplanda bir geliştirme sunucusu başlatır ve dosyalarınızda yaptığınız her değişikliği otomatik olarak algılayıp yeniden derler.

Adım 3 :Liman Arayüzünde Geliştirme Modunu Aktif Etme

Öncelikle Liman arayüzünden, geliştirdiğiniz eklentiyi bir sunucu gerekir. Bu işlem hakkında detaylı bilgi için resmi Liman dokümantasyonunu inceleyebilirsiniz: Liman Sunucu Yönetimi

Eklentiyi sunucuya atadıktan sonra, ilgili sunucu üzerinden eklentinizi açın.

Tarayıcınızın adres çubuğundaki URL'nin sonuna /development ekleyin ve Enter'a basın.

Bu işlemi yaptığınızda, Liman artık eklentinin derlenmiş statik dosyalarını değil, pnpm run dev komutunun çalıştırdığı geliştirme sunucusundan gelen canlı verileri kullanacaktır.

Ek Bölüm: Geliştirme Sürecinde Sık Karşılaşılan Sorunlar ve Çözümleri

Aşağıda, ana rehberi takip ederken veya geliştirme yaparken karşılaşabileceğiniz en yaygın dört sorun ve bu sorunları çözmek için izlemeniz gereken adımlar detaylandırılmıştır.

1. Eklenti Panelde Görünmüyor veya "Undefined" Olarak Gözüküyor

Eklentiyi Liman'a yükledikten sonra, panelde hiç görünmemesi veya isminin "Undefined" olarak listelenmesi.
Bu sorunun neredeyse her zaman tek bir nedeni vardır: Eklentinin .zip dosyasının hatalı bir klasör yapısıyla sıkıştırılması. Liman MYS, eklentiyi tanımak için hayati bir dosya olan extension.json'ın doğrudan zip dosyasının kök dizininde olmasını bekler.

Çözüm Yolları:

Doğru Zip Yapısı: Eklenti dosyalarınızın bulunduğu klasörün içine girin, tüm dosyaları (extension.json, views, public vb.) seçin ve bunları doğrudan zipleyin.

my-extension.zip
-> extension.json
-> views/

-> public/

-> ...diğer dosyalar

Yanlış Zip Yapısı (Kaçınılması Gereken): Eklenti dosyalarını içeren ana klasöre sağ tıklayıp onu zip'lemek. Bu durumda extension.json kök dizinde olmaz.

my-extension.zip

-> my-extension/ (Hatalı alt klasör)

-> extension.json
-> views/

-> ...

2. Port Çakışması (EADDRINUSE) Hatası
pnpm run dev komutunu çalıştırdığınızda, terminalde "EADDRINUSE" (Error: address already in use) hatası almanız.

Temel Nedeni Geliştirme sunucusunun kullanmaya çalıştığı portun (genellikle 5173) başka bir uygulama veya arka planda unutulmuş eski bir geliştirme süreci tarafından zaten kullanılıyor olması.

Çözüm Yolları:

Yöntem A: Alternatif Bir Port Kullanmak (En Hızlı Çözüm)
pnpm run dev komutunu, boş olduğundan emin olduğunuz farklı bir port numarası ile çalıştırın:

pnpm run dev -- --port 5174

Yöntem B: Portu Kullanan İşlemi Sonlandırmak
Mevcut portu meşgul eden işlemi bulup sonlandırın:

# Örnek olarak 5173 portunu kullanan işlemi bulalım
sudo lsof -i :5173
# Komut çıktısındaki PID (Process ID) numarasını kullanarak işlemi sonlandıralım
# Örneğin PID 12345 ise:
sudo kill -9 12345

Bu işlemden sonra pnpm run dev komutunu tekrar çalıştırabilirsiniz.

3. 404 - Not Found (/development) Hatası
Liman arayüzünde eklentiyi açıp URL sonuna /development eklediğinizde "404 - Not Found" hatası almanız.

Temel Nedeni Tarayıcınız, geliştirme sunucusuyla iletişim kuramıyor. Bunun birkaç sebebi olabilir.

Çözüm Yolları (Sırasıyla Kontrol Edin):

Geliştirme Sunucusu Çalışıyor mu?
VS Code'daki terminalinize geri dönün. pnpm run dev komutunun hala çalıştığından ve bir hata vermediğinden emin olun. Eğer durmuşsa, yeniden başlatın.

Doğru Portu mu Kullanıyorsunuz?
pnpm run dev komutunun çıktısını kontrol edin. Geliştirme sunucusu hangi portta (5173, 5174 vb.) çalıştığını size söyleyecektir. Liman'ın bu porta erişebildiğinden emin olun.

Güvenlik Duvarı (Firewall) Engelliyor mu?
Sunucunuzun güvenlik duvarı, geliştirme portuna dışarıdan erişimi engelliyor olabilir. Ubuntu'da ufw kullanılıyorsa, ilgili porta izin verin:

# Vite'ın varsayılan portu 5173 için izin verelim
sudo ufw allow 5173
sudo ufw reload