Wiki.js Nedir ve Modern Açık Kaynak Wiki Kurulumu

Bir kurumun bilgisi zamanla dağılır. Kurulum notları birinin masaüstünde, süreç dokümanları eski bir e-posta ekinde, "bunu geçen sefer nasıl çözmüştük?" sorusunun cevabı ise ancak doğru kişiyi yakalayınca ortaya çıkan bir şeye dönüşür. Wiki.js, bu dağınıklığı tek bir yerde toplamak için tasarlanmış, Node.js üzerinde çalışan modern ve açık kaynaklı bir wiki platformudur. Sade fakat güçlü arayüzü, çoklu editör desteği ve esnek depolama seçenekleriyle hem küçük ekiplerin iç dokümantasyonu hem de halka açık bilgi merkezleri için tercih edilir.

Bu yazıda Wiki.js'in ne olduğunu, onu benzerlerinden ayıran özellikleri, Docker ile en pratik kurulum yöntemini, veritabanı seçimini, LDAP ve OAuth gibi kurumsal yetkilendirme entegrasyonlarını, Git senkronizasyonunu ve tema yapılandırmasını adım adım ele alacağız. Amaç, aracı yeterince tanıyıp kendi ekibiniz için doğru seçim olup olmadığına karar verebilmeniz ve gerçekten çalışır bir kuruluma ulaşabilmenizdir. Komutlar ve örnekler gerçek bir senaryodan alınmış gibi, doğrudan uygulanabilecek biçimde verilmiştir.

Wiki.js Nedir, Neden Tercih Edilir?#

Wiki.js, belgeleri hiyerarşik bir sayfa ağacında saklayan, tarayıcı üzerinden yazıp düzenlemenizi sağlayan bir dokümantasyon motorudur. Klasik wiki yazılımlarının (örneğin PHP tabanlı MediaWiki'nin) aksine tamamen JavaScript ekosisteminde, Node.js üzerinde çalışır ve arka planda GraphQL tabanlı modern bir mimari kullanır. Bu, hem hızlı bir kullanıcı deneyimi hem de kolay genişletilebilirlik anlamına gelir.

Wiki.js'i cazip kılan asıl nokta esnekliğidir. İçeriği Markdown, görsel WYSIWYG, ham HTML veya AsciiDoc gibi farklı editörlerle yazabilirsiniz. Sayfalar veritabanında dursa da içeriğin bir Git deposuyla iki yönlü senkronize edilmesi mümkündür; böylece hem web arayüzünden hem de kod editörünüzden aynı belgeyi düzenleyebilirsiniz. Yetkilendirme tarafında yerel hesapların yanında LDAP, OAuth2, SAML ve pek çok kimlik sağlayıcıyı destekler. Yani tek bir kişilik kişisel bir not defterinden yüzlerce çalışanlı bir kurumun merkezi bilgi tabanına kadar geniş bir aralığa uyum sağlar.

Bir ekip bilgi tabanı ararken Wiki.js dışında Outline gibi alternatifleri de değerlendirebilirsiniz; Outline daha akıcı bir "yaz-git" deneyimi sunarken Wiki.js, Git senkronizasyonu ve zengin editör seçenekleriyle daha teknik ekiplere ve genişletme ihtiyacı olanlara hitap eder. Doğru araç, ekibinizin çalışma biçimine bağlıdır.

Öne Çıkan Özellikler#

Wiki.js'i günlük kullanımda verimli kılan başlıca özellikleri şöyle özetleyebiliriz:

• Çoklu editör desteği: Markdown, görsel (WYSIWYG), ham HTML ve AsciiDoc arasında sayfa bazında seçim yapabilirsiniz. Markdown editörü canlı önizleme, kod bloğu vurgusu ve diyagram (Mermaid) desteği sunar.
• Sayfa ağacı ve gezinme: Belgeler klasör benzeri bir yol yapısında (/mühendislik/dağıtım/üretim) durur; sol menüde otomatik bir ağaç oluşur ve okuyucu içeriği kolayca gezinir.
• Güçlü arama: Yerleşik veritabanı aramasının yanında Elasticsearch, Algolia veya PostgreSQL tam metin arama motorlarını bağlayabilirsiniz. Büyüyen bir bilgi tabanında bu fark yaratır.
• Git senkronizasyonu: İçeriğinizi bir GitHub, GitLab veya kendi Git sunucunuzla iki yönlü eşitleyebilir; her değişikliği sürüm kontrolüne alabilirsiniz.
• Esnek depolama: Yüklenen dosya ve görseller yerel diskte, S3 uyumlu nesne depolamada veya diğer sağlayıcılarda tutulabilir.
• Kapsamlı kimlik doğrulama: Yerel hesaplar, LDAP/Active Directory, Google/Microsoft/GitHub OAuth, SAML ve daha fazlası.
• Sayfa düzeyinde izinler ve sürüm geçmişi: Kimin neyi görüp düzenleyebileceği yollara göre tanımlanır; her sayfanın değişiklik geçmişi tutulur ve eski sürüme dönülebilir.
• Tema ve markalama: Renk şeması, logo ve özel CSS ile arayüzü kendi kurumsal kimliğinize uyarlayabilirsiniz.

Bu özelliklerin birçoğu yönetim panelinden birkaç tıkla açılıp kapatılan modüller halindedir. Kuruluma sade başlayıp ihtiyaç doğdukça arama motoru, depolama sağlayıcısı veya kimlik entegrasyonu eklemek mümkündür.

Docker ile Kurulum#

Wiki.js'i çalıştırmanın en temiz yolu Docker Compose'dur. Uygulamayı ve veritabanını birlikte tanımlayan bir docker-compose.yml dosyası hazırlamak yeterlidir. Aşağıdaki örnek, PostgreSQL veritabanıyla üretime hazır bir başlangıç sağlar:

version: "3"

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: gucluBirParola123
    volumes:
      - db-data:/var/lib/postgresql/data
    restart: unless-stopped

  wiki:
    image: ghcr.io/requarks/wiki:2
    depends_on:
      - db
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: gucluBirParola123
      DB_NAME: wiki
    ports:
      - "3000:3000"
    restart: unless-stopped

volumes:
  db-data:

Dosyayı bir dizine koyduktan sonra kurulumu başlatmak tek komuttur:

docker compose up -d

Konteynerler ayağa kalktığında tarayıcınızda http://sunucu-ip:3000 adresine giderek karşılama ekranına ulaşırsınız. Bu ilk ekranda yönetici e-postasını, parolasını ve sitenin dış URL'sini tanımlarsınız. Bundan sonrası tamamen web arayüzünden yönetilir; ilk giriş yaptığınızda boş bir ana sayfa ve yönetim menüsü sizi karşılar.

Konteynerin sağlıklı çalışıp çalışmadığını ve olası hataları görmek için günlükleri izleyebilirsiniz:

docker compose logs -f wiki

Güncelleme de aynı ölçüde basittir: imajı çekip konteyneri yeniden oluşturmanız yeterlidir. 2 etiketini kullandığınız için 2.x sürüm ailesi içinde kalırsınız, bu da beklenmedik büyük sürüm atlamalarını önler:

docker compose pull
docker compose up -d

Kalıcı verinizin tamamı PostgreSQL'de ve db-data isimli Docker volume'unda durduğu için, düzenli yedek almak istediğinizde bu iki noktaya odaklanmanız yeterlidir. Yedekleme stratejinizi baştan kurmak için yedekleme rehberimizden yararlanabilirsiniz.

Veritabanı Seçimi#

Wiki.js birden fazla veritabanı motoruyla çalışabilir ve doğru seçim, kurulumunuzun ölçeğine bağlıdır. Aşağıdaki tablo yaygın seçenekleri kısaca karşılaştırır:

Çoğu üretim kurulumu için PostgreSQL önerilir. Kararlıdır, eş zamanlı yükü iyi kaldırır ve yerleşik tam metin arama sağlayarak ayrı bir arama motoruna ihtiyaç duymadan iyi sonuç verir. MySQL veya MariaDB, kurumunuzda zaten bu altyapı varsa mantıklı bir seçenektir. SQLite ise yalnızca denemek, tek kişilik küçük bir wiki tutmak ya da hızlı bir test ortamı kurmak için idealdir; birden fazla kişinin aynı anda yazdığı bir ortama uygun değildir.

Veritabanı bağlantı ayarlarının tamamı ortam değişkenleri (DB_TYPE, DB_HOST, DB_USER vb.) ile yönetilir. Parola gibi hassas değerleri docker-compose.yml içine düz metin yazmak yerine bir .env dosyasında tutmak daha güvenli bir alışkanlıktır:

DB_TYPE=postgres
DB_HOST=db
DB_PORT=5432
DB_USER=wikijs
DB_PASS=gucluBirParola123
DB_NAME=wiki

Bu dosyayı sürüm kontrolüne (Git) eklememeye özen gösterin; .gitignore içine .env satırını koymak, sırların yanlışlıkla dışarı sızmasını önler.

Ters Proxy ve HTTPS#

Wiki.js varsayılan olarak 3000 portunda, şifresiz HTTP üzerinden yayın yapar. Gerçek bir yayına almadan önce bunun önüne bir ters proxy koyup HTTPS ile sarmalamak gerekir. En yaygın tercih Nginx'tir. Aşağıdaki yapılandırma, wiki.ornekfirma.com alan adına gelen istekleri konteynere yönlendirir:

server {
    listen 80;
    server_name wiki.ornekfirma.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Upgrade ve Connection başlıkları önemlidir; Wiki.js, canlı düzenleme ve bildirimler için WebSocket kullanır ve bu başlıklar olmadan bazı özellikler çalışmaz. Yapılandırmayı etkinleştirdikten sonra ücretsiz bir Let's Encrypt sertifikası almak için Certbot yeterlidir:

sudo certbot --nginx -d wiki.ornekfirma.com

Certbot, Nginx yapılandırmanızı otomatik olarak HTTPS'e çevirir ve sertifikayı düzenli yeniler. Wiki.js yönetim panelinde site URL'sini https:// ile başlayacak şekilde güncellemeyi de unutmayın; aksi halde bazı bağlantılar ve OAuth geri dönüş adresleri hatalı üretilebilir. Sertifika ve HTTPS konularında derinleşmek isterseniz SSL çözümlerimize göz atabilirsiniz.

LDAP ve OAuth ile Yetkilendirme#

Wiki.js'in kurumsal ortamlarda öne çıkmasının başlıca nedenlerinden biri zengin kimlik doğrulama desteğidir. Yönetim panelinde Yönetim → Authentication bölümünden birden fazla sağlayıcıyı aynı anda etkinleştirebilirsiniz. En sık kullanılan iki yol LDAP/Active Directory ve OAuth2'dir.

LDAP / Active Directory entegrasyonu, çalışanların zaten var olan kurumsal kullanıcı adı ve parolalarıyla giriş yapmasını sağlar. Yeni bir kimlik deposu oluşturmak yerine mevcut dizini kullanırsınız; bir çalışan işten ayrıldığında dizinde devre dışı bırakılması Wiki.js erişimini de otomatik keser. Kurarken sağlamanız gereken temel alanlar şunlardır:

• Sunucu adresi: ldaps://dc.ornekfirma.com gibi güvenli bir bağlantı (mümkünse LDAPS kullanın).
• Bind DN ve parola: Dizinde arama yapabilecek bir servis hesabı.
• Arama tabanı (Base DN): Kullanıcıların bulunduğu dal, örneğin ou=Kullanicilar,dc=ornekfirma,dc=com.
• Alan eşlemeleri: E-posta, ad ve kullanıcı adının hangi LDAP niteliklerinden (mail, displayName, sAMAccountName) okunacağı.

OAuth2 / SAML ise Google Workspace, Microsoft Entra ID (eski adıyla Azure AD), GitHub veya kendi kimlik sağlayıcınızla tek oturum açma (SSO) kurmanızı sağlar. Sağlayıcı tarafında bir uygulama kaydı oluşturur, oradan aldığınız istemci kimliği (Client ID) ve gizli anahtarı (Client Secret) Wiki.js'e girersiniz. Geri dönüş (callback) adresi genellikle şu kalıptadır:

https://wiki.ornekfirma.com/login/<saglayici-anahtari>/callback

Her iki yöntemde de önemli bir ayrıntı grup ve rol eşlemesidir. Wiki.js, giriş yapan kullanıcıyı bir gruba atar ve izinler bu gruplara bağlıdır. LDAP gruplarını veya OAuth "claim" değerlerini Wiki.js gruplarıyla eşleyerek, örneğin yalnızca "Mühendislik" grubundaki kişilerin /mühendislik yolundaki sayfaları düzenleyebilmesini sağlayabilirsiniz. Böylece herkes tek bir kimlikle giriş yaparken, gördükleri ve düzenleyebildikleri içerik rollerine göre ayrışır.

Git Senkronizasyonu#

Wiki.js'in en sevilen özelliklerinden biri, içeriğini bir Git deposuyla iki yönlü senkronize edebilmesidir. Yönetim → Storage bölümünden Git modülünü etkinleştirip bir depo adresi, dal (branch) ve kimlik bilgisi tanımlarsınız. Bundan sonra web arayüzünde yaptığınız her değişiklik otomatik olarak depoya işlenirken (commit), depoya doğrudan gönderilen değişiklikler de wikiye geri yansır.

Bu yaklaşımın birkaç somut faydası vardır. Birincisi, tüm dokümantasyon geçmişiniz Git'te tam bir sürüm kontrolüyle saklanır; kimin neyi ne zaman değiştirdiğini standart Git araçlarıyla inceleyebilirsiniz. İkincisi, teknik ekibiniz istediği takdirde belgeleri sevdiği kod editöründe yazıp git push ile yayına alabilir. Üçüncüsü, deponun kendisi doğal bir yedek görevi görür: Wiki.js sunucusuyla bir sorun yaşasanız bile içeriğinizin tam bir kopyası Git'te durur.

Kimlik doğrulama için SSH anahtarı kullanmak, parola gömmekten daha güvenlidir. Depoyu bağlarken üretilen açık anahtarı Git sağlayıcınıza (örneğin GitHub veya GitLab) dağıtım anahtarı olarak eklersiniz. Çakışmaları en aza indirmek için özel bir dal (örneğin main yerine wiki) ayırmak ve senkronizasyon sıklığını içeriğinizin değişim hızına göre ayarlamak iyi bir pratiktir.

Tema ve Görünüm Yapılandırması#

Wiki.js, kurumsal kimliğinize uyum sağlayacak esnek bir görünüm yönetimi sunar. Yönetim → Theme bölümünden temel renk şemasını (açık/koyu), birincil rengi, sayfa genişliğini ve kod bloğu vurgu stilini ayarlayabilirsiniz. Küçük dokunuşlarla wiki, standart bir varsayılan görünümden çıkıp firmanızın sitesinin bir uzantısı gibi durabilir.

Daha ileri özelleştirme için aynı bölümde özel CSS ve özel HTML alanları bulunur. Buraya kendi CSS kurallarınızı ekleyerek yazı tiplerini, kenar boşluklarını veya menü renklerini değiştirebilir; üst bilgi (head) alanına ek betikler koyarak analitik veya farklı entegrasyonlar bağlayabilirsiniz. Logonuzu ve favicon'unuzu yüklemek de aynı panelden yapılır. Örneğin markanızın ana rengini birincil renk olarak tanımlayıp koyu temayı varsayılan yaparak tutarlı bir okuma deneyimi oluşturabilirsiniz.

Görünümü ayarlarken okunabilirliği ön planda tutmak faydalıdır. Aşırı düşük kontrastlı renkler veya çok dar bir içerik genişliği, uzun teknik belgelerde göz yorar. Sade, ferah ve kontrastı yeterli bir düzen; wikinin asıl amacı olan "bilgiye hızlı ulaşmayı" destekler.

Kimler İçin Uygun, Nasıl Barındırılır?#

Wiki.js, kendi altyapısında kalıcı bir bilgi tabanı isteyen ama aynı zamanda Git ve modern kimlik entegrasyonları gibi teknik olanaklara değer veren ekipler için biçilmiş kaftandır. Yazılım ekipleri için teknik dokümantasyon ve runbook deposu, ürün ekipleri için süreç kılavuzu, destek ekipleri için genel bir yardım merkezi ve kurumlar için iç politika arşivi olarak rahatça kullanılır. Hem tamamen kapalı bir iç wiki hem de herkese açık bir bilgi merkezi olarak yapılandırılabilmesi, onu tek bir kalıba sokmayı zorlaştıracak kadar esnektir.

Barındırma tarafında ihtiyaç mütevazıdır. Küçük ve orta ölçekli bir ekip için 1-2 vCPU ve 2 GB RAM'lik bir sunucu çoğu durumda rahatça yeter; Elasticsearch gibi ek bir arama motoru eklerseniz RAM'i biraz yükseltmek isteyebilirsiniz. Uygulamayı Docker ile çalıştırdığınız için taşıması ve büyütmesi kolaydır: yük arttıkça sunucu kaynağını yükseltmeniz yeterli olur. Bu tür self-host kurulumlar için sanal sunucu çözümleri iyi bir başlangıç noktasıdır; kaynağı ihtiyaç doğdukça büyütebilir, sunucunun bakımını üstlenmek istemiyorsanız sunucu yönetimi hizmetiyle destek alabilirsiniz.

Dosya paylaşımı, takvim veya ekip iş birliği gibi wiki dışı ihtiyaçlar da masadaysa, Nextcloud gibi daha geniş kapsamlı bir platformu Wiki.js'in yanında konumlandırabilirsiniz; ikisi birbirinin yerini almaz, farklı işleri üstlenerek birbirini tamamlar.

Sıkça Sorulan Sorular#

Wiki.js ücretsiz mi?#

Evet, Wiki.js tamamen açık kaynaklıdır ve yazılımın kendisi için lisans ücreti ödemezsiniz. Kendi sunucunuzda barındırdığınızda yalnızca sunucu ve alan adı gibi altyapı maliyetlerini üstlenirsiniz. Bu da onu, kullanıcı başına ücretlendiren kapalı kaynak wiki hizmetlerine göre öngörülebilir maliyetli bir alternatif yapar.

Wiki.js ile MediaWiki arasındaki fark nedir?#

MediaWiki, PHP tabanlı ve Wikipedia'yı da çalıştıran köklü bir wiki yazılımıdır; çok büyük ve topluluk odaklı içerik siteleri için güçlüdür ancak arayüzü ve kurulumu daha eski bir his verir. Wiki.js ise Node.js üzerinde çalışan, modern bir arayüze, çoklu editör desteğine ve Git senkronizasyonuna sahip daha yeni bir platformdur. Kurumsal iç dokümantasyon ve teknik ekipler için Wiki.js genellikle daha ferah bir deneyim sunar.

Verilerimi başka bir sisteme taşıyabilir miyim?#

Evet. Wiki.js içeriği Markdown gibi taşınabilir bir formatta saklar ve Git senkronizasyonunu etkinleştirdiğinizde tüm belgeleriniz sade metin dosyaları olarak bir depoda birikir. Bu sayede ileride başka bir platforma geçmek isterseniz veriniz size ait kalır; herhangi bir sağlayıcıya kilitlenmezsiniz. Açık kaynak olmanın getirdiği en önemli avantajlardan biri budur.

Kurulum için hangi teknik bilgi gerekir?#

Docker ve Docker Compose ile temel bir çalışma bilgisi, bir de ters proxy (Nginx) kavramına aşinalık işi büyük ölçüde kolaylaştırır. Veritabanı bağlantısı, ortam değişkenleri ve HTTPS sertifikası gibi adımlar orta düzey bir sistem yönetimi bilgisiyle rahatça tamamlanır. Bu konularda kendinizi rahat hissetmiyorsanız, sunucunun kurulum ve bakımını profesyonel bir ekibe bırakabileceğiniz yönetilen hizmet seçenekleri de vardır.

Ne kadar sunucu kaynağı gerekir?#

Küçük ve orta ölçekli ekipler için 1-2 vCPU ve 2 GB RAM genellikle yeterlidir. Kullanıcı sayısı, eş zamanlı erişim ve yüklenen dosya hacmi arttıkça CPU, RAM ve disk alanını kademeli olarak yükseltmeniz gerekebilir; ayrıca Elasticsearch gibi harici bir arama motoru eklerseniz biraz daha fazla belleğe ihtiyaç duyarsınız. Docker ile çalıştığınız için kaynağı büyütmek yalnızca daha güçlü bir sunucuya geçmekten ibarettir.

Wiki.js'i tek oturum açma (SSO) ile kullanabilir miyim?#

Evet. Wiki.js; Google, Microsoft Entra ID, GitHub gibi OAuth2 sağlayıcılarının yanı sıra SAML ve LDAP/Active Directory ile tek oturum açmayı destekler. Yönetim panelinden ilgili sağlayıcıyı etkinleştirip istemci kimliği ve gizli anahtar gibi bilgileri girerek çalışanların mevcut kurumsal kimlikleriyle giriş yapmasını sağlarsınız. Grup eşlemesiyle de kimin hangi bölümü düzenleyebileceğini rollere göre ayırabilirsiniz.

Kapanış#

Wiki.js, açık kaynak dünyasında modern bir wiki deneyimi arayanlar için dengeli ve güçlü bir seçenektir: kurulumu Docker ile birkaç dakikaya iner, çoklu editör ve Git senkronizasyonu teknik ekipleri mutlu eder, LDAP ve OAuth entegrasyonları da onu kurumsal ölçeğe taşır. En güzeli, tüm bunları kendi altyapınızda, verileriniz size ait kalacak biçimde çalıştırırsınız.

Bir Wiki.js kurulumunu yayına almak için sağlam bir sunucuya ve doğru bir altyapıya ihtiyacınız var. Kaynaklarını ihtiyacınıza göre ölçeklendirebileceğiniz sanal sunucu ve VDS çözümleriyle başlayabilir, kurulum ve bakımı bize bırakmak isterseniz sunucu yönetimi hizmetimizden yararlanabilir, hazır uygulama kurulumlarına göz atmak için App Center sayfamızı ziyaret edebilirsiniz. Ekibinizin dağınık bilgisini tek bir düzenli, aranabilir ve size ait bir bilgi merkezinde toplamanın tam zamanı.