2026'da HedgeDoc Kendi Sunucunuzda Nasıl Barındırılır: WebSockets, OAuth ve Yüklenen Dosyalar

“HedgeDoc çalıştırmanın” iki farklı anlamı vardır: bir container'ın mevcut olması veya servisin asıl işini eksiksiz yapması. Önemli olan yalnızca ikincisidir. Buradaki doğrulama; bir note oluşturmak, iki tarayıcıdan aynı anda düzenlemek, bir görsel yüklemek ve seçilen provider üzerinden kimlik doğrulamaktır.

HedgeDoc bu amaçla kullanılır: gerçek zamanlı ortak Markdown note'ları. Deployment, bu davranışın arkasındaki bileşenleri korumalıdır; bir port, bir volume ve bir certificate girdidir, sonuç değildir.

HedgeDoc'un yeniden oluşturamayacağı durumu yedekleyin

HedgeDoc için recovery point ve recovery time değerlerini database, yüklenen dosyalar ve authentication configuration temelinde tanımlayın. Bootstrap işleminden önce /hedgedoc/public/uploads yolunu mount edin, zararsız örnek veriler yazın ve bu yolun gerçekten kalıcı olduğunu kanıtlamak için container'ı değiştirin. Named volume, redeploy sonrasında kalıcılığı çözer; güvenlik ihlalini veya sunucu kaybını çözmez.

Temiz bir restore ortamı oluşturun, aynı sabitlenmiş application version'ı kullanın ve note'ların, revision'ların, user'ların ve upload'ların geri geldiğini, ayrıca iki tarayıcının restore edilen note üzerinde ortak çalışabildiğini doğrulayın. Komutları, ownership düzeltmelerini ve geçen süreyi kaydedin. Yedekleme rehberi yararlı bir standarttır: bir yedeğe yükleme sonrasında değil, restore sonrasında güvenilir kabul edilir.

HedgeDoc'u bağımlılıklarından ayırın

HedgeDoc için process health ve product health birbirinden ayrıdır. Port 3000 yanıt veriyor olabilir, ancak kullanıcıya sunulan işlem yine de başarısız olabilir. HedgeDoc'un network contract'ı Postgres ile birlikte isteğe bağlı OAuth ve SMTP provider'larından oluşur. Private endpoint'leri internal DNS üzerinde tutun, yalnızca gerekli outbound çağrılara izin verin ve HedgeDoc'a kapsamı sınırlandırılmış bir service credential verin.

Anlamlı configuration değişikliklerinden sonra bu readiness çalışmasını kullanın: bir note oluşturun, iki tarayıcıdan aynı anda düzenleyin, bir görsel yükleyin ve seçilen provider üzerinden kimlik doğrulayın. Pahalı external check'leri liveness probe'larından uzak tutun; böylece bir provider kesintisi restart loop'a neden olmaz. Capacity çalışmalarında WebSocket bağlantılarını, database yazmalarını, yüklenen medyayı ve document history'yi izleyin. Bunlar, HedgeDoc'un gerçek yükünü page request'lerinden daha iyi gösterir.

Container health'ten daha güçlü beş kontrol

HedgeDoc smoke test'ini tekrarlanabilir bir release komutuna veya kısa bir runbook'a dönüştürün. Çıktı şu sonucu kanıtlamalıdır: bir note oluşturmak, iki tarayıcıdan aynı anda düzenlemek, bir görsel yüklemek ve seçilen provider üzerinden kimlik doğrulamak. Sonuçla birlikte application version'ı, container digest'ini, route hostname'ini ve test-data identifier'ını kaydedin.

Aynı kontrolü rutin bir container değişiminden sonra ve database, yüklenen dosyalar ile authentication configuration'ı başka bir yerde restore ettikten sonra çalıştırın. Restore işlemi; note'lar, revision'lar, user'lar ve upload'lar geri geldiğinde ve iki tarayıcı restore edilen note üzerinde ortak çalışabildiğinde başarılıdır. WebSocket bağlantıları, database yazmaları, yüklenen medya ve document history ile ilişkili timing ve consumption değerlerini karşılaştırın; son işlem hâlâ başarılı olsa bile büyük bir değişiklik incelenmeye değerdir.

Ardından güvenli bir failure senaryosu uygulayın: test identity'sinin Postgres ile isteğe bağlı OAuth ve SMTP provider'larına erişimini geçici olarak engelleyin. HedgeDoc'un hatayı görünür hâle getirdiğini ve yıkıcı manual edit'ler olmadan normale döndüğünü doğrulayın. Yalnızca gerekli, redacted log excerpt'ini saklayın. Bu dört parçalı gate; startup, persistence, recovery ve failure handling süreçlerini kapsar.

HedgeDoc'u hareketli parçaları gizlemeden başlatın

Platformun ileride neyi yöneteceğini gösterdiğinde minimal bir komut faydalıdır.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Burada port 3000 host üzerinde private kalır ve gerekli her path açıkça belirtilir. Postgres ile isteğe bağlı OAuth ve SMTP provider'ları için gözden geçirilmiş connection settings'i ekleyin; private servisler için private name'ler kullanın. Başlangıcı hem log'larla hem de application-specific proof ile doğrulayın: bir note oluşturun, iki tarayıcıdan aynı anda düzenleyin, bir görsel yükleyin ve seçilen provider üzerinden kimlik doğrulayın. Doğrulama tamamlandığında image version'ı sabitleyin; böylece rutin bir değişim davranışı sessizce değiştirmez.

HedgeDoc'a tüm host'u vermeyin

HedgeDoc için değerli attack surface her zaman landing page değildir. En yaygın hata, örnek bir session secret kullanmak veya anonymous note creation'a istemeden izin vermektir. Buna bilinçli şekilde karşılık verin: kalıcı bir session secret kullanın, anonymous note creation'ın kabul edilebilir olup olmadığına karar verin ve private note erişimini kısıtlayın.

CMD_SESSION_SECRET değerini uzun ve rastgele bir değer olarak oluşturun; bu değeri değiştirmek normalde session'ları veya token'ları geçersiz kılar. Bu nedenle değişikliği encryption migration gibi değerlendirmek yerine kullanıcı etkisini planlayın. Image destekliyorsa unprivileged container user kullanın ve ilgisiz credential'ları mount etmeyin. Güvenilmeyen işlemlerin WebSocket bağlantılarını, database yazmalarını, yüklenen medyayı ve document history'yi tüketebileceği ingress katmanında rate veya size limit'leri uygulayın.

HedgeDoc'u sunucunun dışından test edin

Kullanıcılar callback veya client settings kaydetmeden önce final HedgeDoc hostname'ini seçin; ardından public URL için CMD_DOMAIN ve CMD_PROTOCOL_USESSL değerlerini ayarlayın. Platform route'u TLS'i sonlandırmalı ve private port 3000'ü hedeflemelidir.

Acceptance transaction'ı dışarıdan çalıştırın. Client HedgeDoc'a hiç ulaşamıyorsa DNS ve certificate kontrolleri için SSL validation checklist listesini kullanın. Request HedgeDoc'a ulaşıyor ancak WebSockets veya domain settings yanlış olduğu için gerçek zamanlı düzenlemeler başarısız oluyorsa proxy redirect'lerini değiştirmeyi bırakın ve bunun yerine application-specific boundary'yi inceleyin.

HedgeDoc'u gerçek darboğazı etrafında işletin

Her deployment sonrasında HedgeDoc smoke test'i olarak bir note oluşturmayı, iki tarayıcıdan aynı anda düzenlemeyi, bir görsel yüklemeyi ve seçilen provider üzerinden kimlik doğrulamayı kullanın. Bunu destekleyen metrikler WebSocket bağlantıları, database yazmaları, yüklenen medya ve document history'dir; kullanıcı işlemini bozacak seviyeye yaklaşan kaynaklar için alert oluşturun.

Temel change risk'i, HedgeDoc database migration'larının, OAuth settings'lerinin ve plugin veya renderer değişikliklerinin staged release gerektirmesidir. Güvenli bir release, restore edilebilir bir snapshot ile başlar ve traffic yönlendirilmeden önce tek yönlü state change'leri doğrular. WebSockets veya domain settings yanlış olduğu için gerçek zamanlı düzenlemeler başarısız olduğunda, configuration'ını ve ilk error'ı okuyabilmek için başarısız container'ı yeterince uzun süre saklayın.

Dockup, HedgeDoc için hangi işleri ortadan kaldırır?

Dockup, değiştirilebilir platform parçalarını üstlenebilir: traffic'i port 3000'e yönlendirebilir, domain ve certificate sağlayabilir, secret'ları inject edebilir, persistent storage bağlayabilir ve HedgeDoc'u managed veya private olarak bağlanmış servislere bağlayabilir. Bunu Dockup infrastructure üzerinde veya bağladığınız bir sunucuda yapabilir.

HedgeDoc'un acceptance çalışması yine açıkça yapılmalıdır. One-click deployment sonrasında public URL için CMD_DOMAIN ve CMD_PROTOCOL_USESSL değerlerini ayarlayın, Postgres ile isteğe bağlı OAuth ve SMTP provider'larına bağlanıp test edin ve şu senaryoyu çalıştırın: bir note oluşturun, iki tarayıcıdan aynı anda düzenleyin, bir görsel yükleyin ve seçilen provider üzerinden kimlik doğrulayın. Bu ayrım bilinçlidir: Dockup, application role'lerinin, provider credential'larının veya restore policy'nin kendiliğinden seçildiğini varsaymadan tekrarlayan infrastructure kurulumunu ortadan kaldırır.

Sık sorulan sorular

Production deployment için HedgeDoc'un nelere ihtiyacı vardır?

HedgeDoc container'ını tek bir HTTPS origin üzerinden port 3000'e route edin. Destekleyici network gereksinimi Postgres ile isteğe bağlı OAuth ve SMTP provider'larıdır. Bir note oluşturabildiğiniz, iki tarayıcıdan aynı anda düzenleyebildiğiniz, bir görsel yükleyebildiğiniz ve seçilen provider üzerinden kimlik doğrulayabildiğiniz doğrulanana kadar HedgeDoc'u hazır kabul etmeyin.

HedgeDoc verilerinin hangileri yedeğe dahil edilmelidir?

/hedgedoc/public/uploads yolunu kalıcı hâle getirin ve database, yüklenen dosyalar ile authentication configuration'ı aynı recovery manifest'e dahil edin. Temiz bir HedgeDoc restore işlemi yalnızca note'lar, revision'lar, user'lar ve upload'lar geri geldiğinde ve iki tarayıcı restore edilen note üzerinde ortak çalışabildiğinde başarılıdır.

Reverse proxy arkasında HedgeDoc için HTTPS gerekir mi?

Public HedgeDoc origin için HTTPS kullanın ve port 3000'ü internal route üzerinde tutun. HedgeDoc setting'ini doğru şekilde uygulayın: public URL için CMD_DOMAIN ve CMD_PROTOCOL_USESSL değerlerini ayarlayın. HedgeDoc için HTTPS, credentials veya user content'in aktarım sırasında korunmasını sağlar ve origin'e duyarlı client davranışını tutarlı hâle getirir.

Bir HedgeDoc upgrade'i nasıl test edilmelidir?

Mevcut HedgeDoc state'ini izole bir deployment'a restore edin, candidate version'ı uygulayın ve acceptance transaction'ını tekrarlayın. HedgeDoc database migration'larının, OAuth settings'lerinin ve plugin veya renderer değişikliklerinin staged release gerektirmesi nedeniyle özellikle dikkatli olun. Data migration ve rollback sınırı anlaşılana kadar önceki HedgeDoc image'ını saklayın.