İçeriğe geç
HedgeDoc Markdown İş Birliği Not Altyapısı Kurulumu

HedgeDoc Markdown İş Birliği Not Altyapısı Kurulumu

6 dk okuma DevOps

Ekip içi not alma ve dokümantasyon için gerçek zamanlı Markdown düzenleme ihtiyacı arttıkça, self-hosted çözümler tercih edilir hale geldi. HedgeDoc, birden fazla kullanıcının aynı anda aynı belge üzerinde çalışmasına olanak tanıyan, açık kaynak kodlu bir Markdown platformudur. Node.js tabanlı bu uygulama, canlı ön izleme, slayt modu ve çeşitli kimlik doğrulama yöntemleri sunar.

Ön Gereksinimler

Kurulum öncesinde sunucuda Node.js, npm ve Bash hazır olmalıdır. HedgeDoc, Node.js 18 ve üzeri sürümleri destekler; geliştiriciler güncel LTS sürümünü önerir. Paket yöneticisi olarak Yarn kullanılır; Node.js ile gelen corepack etkinleştirilince doğru Yarn sürümü otomatik seçilir. Veritabanı olarak PostgreSQL, MariaDB, MySQL veya SQLite kullanılabilir. Ön yüzü kendiniz derleyecekseniz sunucuda en az 2 GB RAM bulunmalı; 1.7 sonrası sürüm paketleri derlenmiş ön yüzü içerdiğinden bu adım atlanabilir.

Production ortamında reverse proxy olarak Nginx veya Caddy kullanılması önerilir. SSL/TLS terminasyonu bu katmanda gerçekleştirilir.

Bağımlılıkların Kurulumu

Sistemi hazırlamak için önce temel paketler yüklenir:

apt update && apt upgrade -y
apt install -y git curl unzip build-essential

Node.js kurulumu için NodeSource deposu tercih edilir:

curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs
corepack enable

Kurulum tamamlandıktan sonra sürüm kontrolü yapılır:

node --version
npm --version

Uygulama Kurulumu

HedgeDoc kaynak kodu Git ile çekilir. master dalı yerine release etiketi kullanmak, test edilmemiş değişikliklerin sunucuya girmesini engeller:

cd /opt
git clone -b 1.11.1 https://github.com/hedgedoc/hedgedoc.git
cd hedgedoc
bin/setup

bin/setup bağımlılıkları kurar ve örnek yapılandırma dosyalarını oluşturur. Git'ten kurulumda ön yüz paketini derlemek gerekir; release arşiviyle çalışıyorsanız bu adım gerekmez:

yarn install --immutable
yarn build

İlk kez elle başlatıp logları izlemek, yapılandırma hatasını erken yakalamanın en kolay yolu:

NODE_ENV=production yarn start

Yapılandırma

HedgeDoc, config.json dosyası ya da ortam değişkenleri ile yapılandırılır. Ortam değişkenleri config dosyasındaki değerleri geçersiz kılar. CMD_ önekli değişkenlerle temel ayarlar şöyle tanımlanır:

CMD_DB_URL=postgres://hedgedoc:sifre@localhost:5432/hedgedoc
CMD_DOMAIN=hedgedoc.sunucu.com
CMD_PROTOCOL_USESSL=true
CMD_URL_ADDPORT=false
CMD_SESSION_SECRET=rasgele_guvenli_dize

protocolUseSSL, üretilen bağlantıların HTTPS olmasını sağlar; dinleme portunda şifreleme açmaz, o iş reverse proxy'nindir. URL sonuna port eklenmemesi için urlAddPort false olur. sessionSecret belirtilmezse her başlangıçta yeniden üretilir ve tüm kullanıcılar oturumdan düşer. Veritabanı bağlantısı için PostgreSQL kullanılacaksa, önce veritabanı ve kullanıcı oluşturulmalıdır:

sudo -u postgres psql
CREATE DATABASE hedgedoc;
CREATE USER hedgedoc WITH PASSWORD 'parola';
GRANT ALL PRIVILEGES ON DATABASE hedgedoc TO hedgedoc;
\q

Kimlik doğrulama yöntemi olarak GitHub OAuth uygulaması kullanılabilir. Bunun için GitHub Developer Settings üzerinde yeni bir OAuth uygulaması kaydedilir ve callback URL olarak https://hedgedoc.sunucu.com/auth/github/callback tanımlanır. GitHub'ın verdiği Client ID ve Client Secret ortam değişkenlerine eklenir:

CMD_GITHUB_CLIENTID=xxxxx
CMD_GITHUB_CLIENTSECRET=xxxxx

Systemd Servisi

HedgeDoc'un sistem başlangıcında otomatik çalışması için systemd servisi tanımlanır. hedgedoc kullanıcısı ve grubu önceden oluşturulmalı, kurulum dizininde gerekli izinlere sahip olmalıdır:

[Unit]
Description=HedgeDoc - The best platform to write and share markdown.
Documentation=https://docs.hedgedoc.org/
After=network.target
After=postgresql.service

[Service]
Type=exec
Environment=NODE_ENV=production
Restart=always
RestartSec=2s
ExecStart=/usr/bin/yarn start
User=hedgedoc
Group=hedgedoc
WorkingDirectory=/opt/hedgedoc

[Install]
WantedBy=multi-user.target

Servis dosyası oluşturulduktan sonra systemd yeniden yüklenir ve servis başlatılır:

systemctl daemon-reload
systemctl enable hedgedoc
systemctl start hedgedoc

Servis durumu kontrol edilir:

systemctl status hedgedoc

Nginx Reverse Proxy

Production ortamında gelen istekler Nginx üzerinden HedgeDoc'a aktarılır. Kritik nokta WebSocket yükseltmesi: gerçek zamanlı düzenleme socket.io bağlantısı üzerinden yürür. /socket.io/ yolu için Upgrade ve Connection başlıkları iletilmezse arayüz normal görünür ama diğer kullanıcıların değişiklikleri gelmez, hata mesajı da çıkmaz. SSL için Let's Encrypt sertifikası üretilebilir veya mevcut sertifikalar kullanılabilir.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name hedgedoc.sunucu.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name hedgedoc.sunucu.com;

    ssl_certificate /etc/letsencrypt/live/hedgedoc.sunucu.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hedgedoc.sunucu.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }

    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Yapılandırma doğrulanıp Nginx yeniden yüklenir:

ln -s /etc/nginx/sites-available/hedgedoc /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

İlk Yapılandırma ve Kullanım

Servisler çalıştırıldıktan sonra tarayıcı üzerinden https://hedgedoc.sunucu.com adresine gidilir. E-posta kaydı açıksa ilk hesap oluşturulabilir ya da OAuth sağlayıcı ile giriş yapılır.

Yeni bir not oluşturmak için ana sayfadaki butona tıklanır. Markdown desteği ile birlikte canlı ön izleme penceresi açılır. Sağ üst köşedeki kullanıcı simgesine tıklanarak profil ayarları, tema seçenekleri ve yönetim paneli erişilebilir hale gelir.

Yönetim panelinden kullanıcılar, yetkilendirme ayarları ve sistem yapılandırması düzenlenebilir. Gerçek zamanlı düzenleme özelliği sayesinde aynı belge üzerinde birden fazla kullanıcı çalışabilir ve değişiklikler anlık olarak yansır. Bu anlatım 1.x serisine ait; HedgeDoc 2.x'te sunucu mimarisi ve WebSocket yolu değişti, güncelleme yapmadan önce yeni sürümün breaking change notlarını okumak gerekir.

Tüm yazılar