BookStack Nedir ve Kurumsal Dokümantasyon Wiki Kurulumu

Kurum içi bilgi, çoğu şirkette kimsenin fark etmeden dağıldığı bir yerdir. Kurulum adımları bir kişinin masaüstündeki metin dosyasında, süreç notları eski bir Word belgesinde, "bu ayarı nereden değiştiriyorduk?" sorusunun cevabı ise yalnızca doğru kişiye sorunca ortaya çıkan sözlü bir bilgide durur. Bu dağınıklık büyüdükçe hem yeni çalışanların işe alışması yavaşlar hem de anahtar kişi ayrıldığında bilgi de birlikte gider. BookStack, tam olarak bu sorunu çözmek için tasarlanmış, açık kaynaklı bir dokümantasyon ve wiki uygulamasıdır. Adından da anlaşılacağı gibi bilgiyi bir "kitaplık" mantığıyla düzenler: raflar, kitaplar, bölümler ve sayfalar.

Bu rehberde BookStack'in ne olduğunu, onu diğer wiki araçlarından ayıran raf-kitap-bölüm-sayfa hiyerarşisini, hem görsel (WYSIWYG) hem de Markdown editörünü, klasik bir LAMP sunucusuna adım adım kurulumunu, rol ve izin yapısını, arama mantığını ve Outline gibi alternatiflerle karşılaştırmasını ele alacağız. Amaç, aracı gerçek anlamda tanımanız ve ekibiniz için doğru seçim olup olmadığına kendiniz karar verebilmenizdir.

BookStack Nedir?#

BookStack, PHP ile yazılmış (Laravel çatısı üzerinde çalışan) açık kaynaklı bir bilgi tabanı platformudur. Notion, Confluence veya Wiki.js gibi araçlara benzer bir işi görür; ancak en belirgin farkı, içeriği serbest bir sayfa yığını olarak değil, tanıdık bir kitap metaforuyla organize etmesidir. Yazdığınız her doküman bir "sayfa" olur, ilgili sayfalar bir "kitapta" toplanır, kitaplar da "raflarda" gruplanır. Bu yapı, dokümantasyonu tıpkı gerçek bir referans kitaplığı gibi gezilebilir kılar.

Uygulama tamamen tarayıcı üzerinden çalışır ve kurulumu bilinçli olarak sade tutulmuştur. Ağır bağımlılıklar yerine yalnızca standart bir web sunucusu, PHP ve MySQL/MariaDB veritabanına ihtiyaç duyar; bu da onu paylaşımlı hosting'in bir adım üzerindeki hemen her sunucuda çalıştırılabilir hale getirir. Verinin tamamı sizin veritabanınızda durduğu için içeriğinizin nerede tutulduğu konusunda tam kontrole sahip olursunuz.

BookStack'i en iyi tanımlayan söz, projenin kendi felsefesidir: basit tutmak. Amaç, herkesin dakikalar içinde yazmaya başlayabileceği, teknik olmayan ekip üyelerinin bile rahatça kullanabileceği, temiz ve erişilebilir bir dokümantasyon aracı sunmaktır. Karmaşık proje yönetimi tabloları, veritabanı görünümleri veya takvimler burada yoktur; BookStack tek bir işe, düzenli dokümantasyona odaklanır ve bunu iyi yapar.

Raf, Kitap, Bölüm ve Sayfa Hiyerarşisi#

BookStack'i diğer wiki araçlarından ayıran en temel özellik, içerik hiyerarşisidir. Dört seviyeden oluşur ve bu yapı hem düzeni hem de erişimi doğal biçimde organize eder:

• Sayfa (Page): İçeriğin yazıldığı en küçük birim. Bir kurulum rehberi, bir prosedür ya da bir toplantı notu tek bir sayfadır.
• Bölüm (Chapter): İlgili sayfaları gruplayan, isteğe bağlı ara katman. "Yedekleme" adlı bir kitabın içinde "Günlük Yedekler" ve "Felaket Kurtarma" gibi bölümler açabilirsiniz.
• Kitap (Book): Belirli bir konuyu kapsayan sayfa ve bölüm koleksiyonu. "Sunucu Yönetimi" veya "İK Politikaları" birer kitaptır.
• Raf (Shelf / Bookshelf): Birbiriyle ilişkili kitapları bir arada gösteren en üst düzey grup. Bir kitap birden fazla rafta yer alabilir.

Bu yapının en büyük avantajı, bilginin nereye konacağının çoğu zaman kendiliğinden belli olmasıdır. Ekip üyeleri "bunu hangi klasöre koysam?" diye düşünmek zorunda kalmaz; konuya en uygun kitabın içindeki mantıklı bir bölüme yazarlar. Aşağıdaki tablo, tipik bir kurumsal kurulumun nasıl görünebileceğini özetliyor:

Kitaplar ve sayfalar sürükle-bırak ile kolayca yeniden sıralanabilir, bir sayfa başka bir kitaba taşınabilir. Her kitabın otomatik oluşturulan bir içindekiler listesi (ToC) vardır ve okuyucular bu yapı üzerinden hızlıca gezinebilir. Yapılandırılmış bu düzen, Outline'ın daha akışkan, koleksiyon tabanlı yaklaşımından belirgin biçimde ayrılır; hangisinin daha iyi olduğu tamamen ekibinizin çalışma alışkanlığına bağlıdır.

WYSIWYG ve Markdown Editörü#

BookStack, iki farklı yazma tarzını da destekler ve bunu kullanıcı bazında ayarlanabilir hale getirir. Bu, hem teknik hem de teknik olmayan ekiplerin aynı platformda rahat etmesini sağlayan önemli bir esnekliktir.

Görsel editör (WYSIWYG) varsayılan moddur ve Word'e benzer bir deneyim sunar. Başlıklar, listeler, tablolar, bağlantılar, kod blokları ve görseller araç çubuğundaki düğmelerle eklenir; Markdown bilmeyen bir muhasebe veya İK çalışanı bile hiçbir sözdizimi öğrenmeden içerik üretebilir. Görselleri doğrudan panodan yapıştırabilir veya sürükleyip bırakabilirsiniz; BookStack bunları otomatik olarak yükler ve sayfaya gömer. Diyagram çizmek isteyenler için yerleşik bir çizim aracı (Draw.io tabanlı) da bulunur.

Markdown editörü ise teknik ekipler için tercih edilir. Sol tarafta Markdown yazar, sağ tarafta anlık önizlemeyi görürsünüz. Standart Markdown söz diziminin yanında kod bloklarında sözdizimi renklendirmesi ve içeriğe gömülü çizimler de desteklenir. İki editör aynı içeriği paylaşır; yani bir sayfayı Markdown ile başlatıp başka biri görsel editörle düzenleyebilir. Kullanıcılar kendi profil ayarlarından hangi editörle başlayacaklarını seçebilir.

Editör tarafında dikkat çeken bir başka özellik de sayfa şablonlarıdır. Sık tekrar eden bir doküman tipiniz varsa (örneğin bir olay müdahale raporu ya da yeni müşteri kurulum kontrol listesi) bunu bir şablon olarak kaydeder, her yeni sayfada tek tıkla çağırırsınız. Bu, dokümantasyonun tutarlı bir yapıda kalmasına ciddi katkı sağlar.

LAMP Üzerinde Adım Adım Kurulum#

BookStack'in en cazip yanlarından biri, egzotik bir altyapı gerektirmemesidir. Klasik bir LAMP (Linux, Apache/Nginx, MySQL, PHP) yığını üzerinde çalışır. Aşağıda Ubuntu tabanlı bir sanal sunucu için tipik adımları bulacaksınız. İlk olarak sistemi güncelleyip gerekli paketleri kuralım:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git unzip nginx mariadb-server \
  php8.2-fpm php8.2-cli php8.2-mysql php8.2-curl \
  php8.2-mbstring php8.2-xml php8.2-gd php8.2-zip php8.2-ldap

BookStack, PHP 8.1 ve üzerini, MySQL 5.7+ veya MariaDB 10.3+ sürümünü ister. Ayrıca composer (PHP bağımlılık yöneticisi) kurulu olmalıdır. Şimdi veritabanını ve ona özel bir kullanıcıyı oluşturalım:

CREATE DATABASE bookstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'cok-guclu-bir-parola';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';
FLUSH PRIVILEGES;

Ardından uygulama kaynağını çekip bağımlılıkları yükleyelim. BookStack'in release dalı, kararlı sürümleri takip etmenin en güvenli yoludur:

cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git \
  --branch release --single-branch bookstack
cd bookstack
sudo composer install --no-dev --no-plugins
sudo cp .env.example .env

Şimdi .env dosyasını düzenleyerek uygulamanın adresini ve veritabanı bilgilerini tanımlayın. Bu dosya, kurulumun kalbidir:

APP_URL=https://wiki.ornek.com
APP_LANG=tr

DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=cok-guclu-bir-parola

MAIL_DRIVER=smtp
MAIL_HOST=smtp.ornek.com
MAIL_PORT=587

Uygulama anahtarını üretin, veritabanı tablolarını oluşturun ve dosya izinlerini web sunucusu kullanıcısına verin:

sudo php artisan key:generate --force
sudo php artisan migrate --force
sudo chown -R www-data:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 storage bootstrap/cache public/uploads

Son adım, web sunucusunu yapılandırmaktır. Nginx tarafında minimal bir sunucu bloğu şöyle görünür (kök dizinin public klasörünü gösterdiğine dikkat edin):

server {
    listen 80;
    server_name wiki.ornek.com;
    root /var/www/bookstack/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Uygulamanın erişilebilir olması için alt alan adınızı sunucunuza yönlendiren bir DNS kaydı gerekir. Alan adı yönetim panelinizde şöyle bir A kaydı eklemeniz yeterlidir:

wiki    IN  A     203.0.113.10

Kurulum tamamlandıktan sonra tarayıcıdan adrese gidip varsayılan yönetici hesabıyla ([email protected] / password) giriş yapın ve bu parolayı ilk iş olarak değiştirin. Yayına almadan önce mutlaka bir SSL sertifikası kurarak trafiği HTTPS'e taşıyın; Let's Encrypt ile bu ücretsizdir. Bu manuel adımlar sizi yormasın istiyorsanız, App Center üzerinden BookStack'i bağımlılıklarıyla birlikte hazır kurulmuş halde de alabilirsiniz.

Rol ve İzin Yapısı#

Bir dokümantasyon aracı ancak doğru bilgiyi doğru kişiye gösterdiği ölçüde işe yarar. BookStack'in izin sistemi, çoğu ekibin ihtiyacını karşılayacak kadar esnek, aynı zamanda anlaşılır tutulmuştur. İki katmanda çalışır:

Birinci katman, rol tabanlı izinlerdir. Her kullanıcı bir veya birden fazla role atanır ve her rolün sistem genelinde ne yapabileceği tanımlıdır. Varsayılan roller şöyledir:

İkinci katman, içerik düzeyinde izin geçersiz kılmalarıdır (permission overrides). Genel rol izinlerinin dışına çıkmanız gereken durumlarda, tek bir raf, kitap, bölüm ya da sayfa için özel erişim kuralları tanımlarsınız. Örneğin tüm ekibin okuyabildiği bir wiki'de, yalnızca yönetim ekibinin görebileceği bir "Bordro Prosedürleri" kitabı oluşturabilirsiniz. İzinler hiyerarşi boyunca aşağı doğru miras alınır: bir kitaba koyduğunuz kısıtlama, aksini belirtmediğiniz sürece onun bölüm ve sayfalarına da uygulanır.

Kimlik doğrulama tarafında BookStack oldukça yeteneklidir. Standart e-posta/parola girişinin yanında LDAP/Active Directory, SAML 2.0, OpenID Connect (OIDC) ve sosyal giriş sağlayıcılarını destekler. Bu, mevcut kurumsal kimlik altyapınıza bağlanmayı kolaylaştırır; çalışanlar zaten kullandıkları hesapla tek oturum açma (SSO) yaparak wiki'ye erişir. Kurumsal ölçekte bu özellik, hesap yönetimini ciddi biçimde sadeleştirir.

Arama ve İçerik Keşfi#

Dokümantasyon büyüdükçe en kritik özellik, aradığınızı hızlı bulabilmek olur. BookStack, MySQL'in tam metin arama altyapısını kullanarak tüm sayfa içeriklerini tarar. Arama kutusuna yazdığınız kelime yalnızca başlıklarda değil, sayfa gövdesinde de aranır ve sonuçlar ilgililik sırasına göre listelenir.

Aramayı güçlü kılan, desteklediği filtreleme sözdizimidir. Basit kelime aramasının ötesine geçmek istediğinizde şu operatörler işe yarar:

{updated_after:2026-01-01}   son güncelleme tarihine göre filtre
[tag=güvenlik]               belirli bir etikete sahip sayfalar
"tam eşleşen ifade"          tırnak içindeki ifadenin birebir geçtiği yerler
-kelime                      belirtilen kelimeyi içermeyen sonuçlar

BookStack'in bir diğer düzenleme aracı etiketlerdir (tags). Hiyerarşi konuya göre bir düzen kurar; etiketler ise buna dik kesen ikinci bir sınıflandırma katmanı sağlar. Örneğin farklı kitaplarda dağılmış ama hepsi "kvkk" ile ilgili sayfaları tek bir etiket altında toplayıp aramada bu etiketle çağırabilirsiniz. Etiketler anahtar-değer biçiminde de olabilir (ortam=üretim gibi), bu da özellikle teknik dokümantasyonda güçlü filtrelemeler kurmanıza olanak tanır.

Ayrıca her sayfa ve kitaba doğrudan bağlantı verilebildiği, sayfalar arası çapraz bağlantılar kurulabildiği için içerik zamanla kendi iç referans ağını oluşturur. Yeni bir ekip üyesi bir konuya girdiğinde, ilgili sayfalar arasında zincirleme gezerek ihtiyacı olan bağlamı toplayabilir.

BookStack ve Alternatifleri#

BookStack'in nerede durduğunu görmek için, sık karşılaşılan alternatiflerle karşılaştırmak faydalıdır. Aşağıdaki tablo temel farkları özetliyor:

BookStack'in en güçlü yanı, katı ama sezgisel yapısıdır. Herkesin bilgiyi nereye koyacağını bildiği, dağınıklaşması zor bir düzen sunar; kurulumu da alternatiflerin çoğundan basittir. Buna karşılık bu yapı bazı ekipler için fazla kalıplaşmış gelebilir. İçeriği daha serbest, "yaz ve akıp gitsin" tarzında organize etmek isteyenler Outline'ı daha rahat bulur. Çok sayıda depolama ve kimlik sağlayıcı seçeneğiyle maksimum esneklik arayanlar için Wiki.js öne çıkar. Confluence ise güçlü bir kurumsal çözümdür ama kapalı kaynaktır ve lisanslama tarafı ağır olabilir.

Şunu da unutmamak gerekir: bu araçlar birbirinin tam yerine geçmez, farklı ihtiyaçlara hitap eder. Dosya paylaşımı, takvim ve senkronizasyon gibi ofis işlevlerini de aynı çatı altında istiyorsanız, dokümantasyonu bir wiki'ye bırakıp bunun yanında Nextcloud kurmayı değerlendirebilirsiniz. Doğru yaklaşım genellikle "tek araca her şeyi yaptırmak" değil, her işi kendi alanında iyi olan araca vermektir.

Sıkça Sorulan Sorular#

BookStack ücretsiz mi?#

BookStack tamamen açık kaynaklıdır ve MIT lisansıyla dağıtılır; yazılımın kendisi için hiçbir lisans ücreti ödemezsiniz. Yalnızca üzerinde çalıştığı sunucunun maliyetini üstlenirsiniz, o kadar. Kullanıcı sayısına bağlı ücretlendirme olmadığı için ekibiniz büyüdükçe maliyetiniz artmaz; bu yönüyle kullanıcı başına ücret alan bulut tabanlı wiki hizmetlerine göre ölçekte belirgin bir maliyet avantajı sağlar.

BookStack hangi sunucu gereksinimlerine ihtiyaç duyar?#

BookStack, PHP 8.1 ve üzeri, MySQL 5.7+ veya MariaDB 10.3+ ile Apache ya da Nginx gerektiren standart bir LAMP uygulaması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. 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ükseltebilirsiniz; kaynağı sonradan büyütmek mümkündür.

BookStack ile Outline arasındaki fark nedir?#

İkisi de açık kaynaklı, self-host edilebilen dokümantasyon araçlarıdır; temel fark, içeriği organize etme felsefelerindedir. BookStack, raf-kitap-bölüm-sayfa şeklinde katı ve yapısal bir hiyerarşi sunar; bu, bilginin nereye konacağını netleştirir ve büyük dokümantasyonların dağılmasını önler. Outline ise daha akışkan, koleksiyon tabanlı ve hızlı bir yazma deneyimine odaklanır. Yapı ve düzen önceliğinizse BookStack, yazma hızı ve esneklik önceliğinizse Outline daha uygundur.

Var olan içeriğimi BookStack'e aktarabilir miyim?#

BookStack, sayfaları HTML, PDF, Markdown ve düz metin formatlarında dışa aktarmayı destekler; bu da verinize kilitli kalmamanızı sağlar. İçe aktarma tarafında ise sayfaları Markdown ile hızlıca oluşturabilir veya BookStack'in REST API'sini kullanarak içeriği programatik olarak toplu halde yükleyebilirsiniz. Farklı bir sistemden geçiş yapıyorsanız, API üzerinden yazılmış küçük bir taşıma betiği çoğu senaryoda işi görür.

BookStack çok dilli içerik ve Türkçe destekliyor mu?#

BookStack arayüzü Türkçe dahil çok sayıda dile çevrilmiştir; .env dosyasındaki APP_LANG=tr ayarıyla varsayılan arayüz dilini Türkçe yapabilirsiniz. Kullanıcılar ayrıca kendi profillerinden tercih ettikleri arayüz dilini seçebilir. İçeriğin kendisi ise dil bağımsızdır; farklı diller için ayrı kitaplar veya raflar oluşturarak çok dilli bir dokümantasyon yapısını kolayca kurabilirsiniz.

BookStack'i mevcut kullanıcı sistemimize bağlayabilir miyim?#

Evet. BookStack; LDAP/Active Directory, SAML 2.0 ve OpenID Connect (OIDC) ile kurumsal kimlik sağlayıcılarına bağlanabilir, ayrıca sosyal giriş seçenekleri sunar. Bu sayede çalışanlar zaten kullandıkları kurumsal hesapla tek oturum açma (SSO) yaparak wiki'ye erişir; ayrı parola yönetmek gerekmez. Bu özellik, hesap oluşturma ve devre dışı bırakma süreçlerini merkezi kimlik sisteminizle senkron tutmayı kolaylaştırır.

Kapanış#

BookStack, dokümantasyonu göz korkutan bir kurumsal yazılım olmaktan çıkarıp herkesin katkı verebileceği düzenli bir kitaplığa dönüştürür. Raf-kitap-bölüm-sayfa hiyerarşisi bilgiye net bir yer kazandırır, çift editör seçeneği hem teknik hem teknik olmayan ekibi memnun eder, sade LAMP gereksinimi ise onu neredeyse her sunucuda çalıştırılabilir kılar. Kurum içi hafızanızı tek bir yerde, aranabilir ve size ait bir yapıda toplamak istiyorsanız, değerlendirmeye kesinlikle değer.

Başlamak için ihtiyacınız olan tek şey, üzerinde barındıracağınız sağlam bir altyapıdır. Kendi kontrolünüzdeki bir kurulum için sanal sunucu planlarımıza göz atabilir, Docker ve yapılandırma detaylarıyla tek tek uğraşmadan hızlı bir başlangıç isterseniz BookStack'i hazır kurulumla sunan App Center sayfamızı inceleyebilirsiniz. Kurulumu profesyonel ellere bırakmak isterseniz sunucu yönetimi hizmetimiz, kurulumdan güncelleme ve yedeklemeye kadar süreci sizin adınıza üstlenir; siz yalnızca içeriğinizi yazmaya odaklanırsınız.