Πώς να κάνετε self-hosting του HedgeDoc το 2026: WebSockets, OAuth και ανεβασμένα αρχεία

Υπάρχουν δύο εκδοχές του «τρέχω το HedgeDoc»: είτε υπάρχει ένα container είτε η υπηρεσία ολοκληρώνει πραγματικά τη δουλειά της. Μόνο η δεύτερη έχει σημασία. Εδώ, η απόδειξη είναι να δημιουργήσετε μια σημείωση, να την επεξεργαστείτε ταυτόχρονα από δύο browsers, να ανεβάσετε μια εικόνα και να κάνετε authentication μέσω του επιλεγμένου provider.

Το HedgeDoc εξυπηρετεί ακριβώς αυτόν τον σκοπό: συνεργατικές Markdown σημειώσεις σε πραγματικό χρόνο. Το deployment πρέπει να διατηρεί τα στοιχεία που υποστηρίζουν αυτήν τη συμπεριφορά· μια θύρα, ένα volume και ένα certificate είναι προαπαιτούμενα, όχι το τελικό αποτέλεσμα.

Κάντε backup την κατάσταση που το HedgeDoc δεν μπορεί να αναδημιουργήσει

Καθορίστε το recovery point και το recovery time του HedgeDoc με βάση τη βάση δεδομένων, τα ανεβασμένα αρχεία και το authentication configuration. Κάντε mount το /hedgedoc/public/uploads πριν από το bootstrap, γράψτε ακίνδυνα sample data και αντικαταστήστε το container για να αποδείξετε ότι η συγκεκριμένη διαδρομή είναι πράγματι persistent. Ένα named volume λύνει το ζήτημα της persistence μετά από redeploy· δεν αντιμετωπίζει όμως ένα compromise ή την απώλεια του server.

Δημιουργήστε ένα καθαρό περιβάλλον restore, χρησιμοποιήστε την ίδια pinned έκδοση της εφαρμογής και επιβεβαιώστε ότι οι σημειώσεις, τα revisions, οι users και τα uploads επανέρχονται και ότι δύο browsers μπορούν να συνεργαστούν στη restored σημείωση. Καταγράψτε τις εντολές, τις διορθώσεις ownership και τον χρόνο που χρειάστηκε. Ο οδηγός backup αποτελεί χρήσιμο πρότυπο: ένα backup θεωρείται αξιόπιστο μετά το restore και όχι μετά το upload.

Διαχωρίστε το HedgeDoc από τις dependencies του

Η υγεία της διεργασίας και η υγεία του προϊόντος είναι διαφορετικά πράγματα για το HedgeDoc. Η θύρα 3000 μπορεί να απαντά, ενώ η συναλλαγή που βλέπει ο χρήστης εξακολουθεί να αποτυγχάνει. Το network contract του HedgeDoc είναι το Postgres, καθώς και οι προαιρετικοί OAuth και SMTP providers. Διατηρήστε τα private endpoints σε internal DNS, επιτρέψτε μόνο τις απαιτούμενες outbound κλήσεις και δώστε στο HedgeDoc ένα scoped service credential.

Χρησιμοποιήστε αυτήν την άσκηση readiness μετά από κάθε ουσιαστική αλλαγή ρυθμίσεων: δημιουργήστε μια σημείωση, επεξεργαστείτε την ταυτόχρονα από δύο browsers, ανεβάστε μια εικόνα και κάντε authentication μέσω του επιλεγμένου provider. Μην συμπεριλαμβάνετε ακριβούς external ελέγχους στα liveness probes, ώστε μια διακοπή λειτουργίας provider να μην προκαλεί restart loop. Η εργασία capacity planning πρέπει να παρακολουθεί τις WebSocket connections, τα database writes, τα uploaded media και το document history, καθώς αυτά αντικατοπτρίζουν καλύτερα την πραγματική πίεση στο HedgeDoc από ό,τι τα page requests.

Πέντε έλεγχοι ισχυρότεροι από το container health

Μετατρέψτε το smoke test του HedgeDoc σε επαναλήψιμη εντολή release ή σε σύντομο runbook. Η έξοδός του πρέπει να αποδεικνύει το εξής αποτέλεσμα: δημιουργία μιας σημείωσης, ταυτόχρονη επεξεργασία της από δύο browsers, upload μιας εικόνας και authentication μέσω του επιλεγμένου provider. Καταγράψτε μαζί με το αποτέλεσμα την έκδοση της εφαρμογής, το container digest, το route hostname και το identifier των test data.

Εκτελέστε τον ίδιο έλεγχο μετά από μια συνηθισμένη αντικατάσταση container και μετά από restore της βάσης δεδομένων, των ανεβασμένων αρχείων και του authentication configuration σε διαφορετικό περιβάλλον. Το restore έχει ολοκληρωθεί με επιτυχία όταν οι σημειώσεις, τα revisions, οι users και τα uploads επανέρχονται και δύο browsers μπορούν να συνεργαστούν στη restored σημείωση. Συγκρίνετε τον χρόνο και την κατανάλωση που σχετίζονται με τις WebSocket connections, τα database writes, τα uploaded media και το document history· μια μεγάλη αλλαγή αξίζει διερεύνηση ακόμη και όταν η τελική ενέργεια εξακολουθεί να πετυχαίνει.

Στη συνέχεια, δοκιμάστε μια ασφαλή αποτυχία: αρνηθείτε προσωρινά στην test identity την πρόσβαση στο Postgres, καθώς και στους προαιρετικούς OAuth και SMTP providers. Επιβεβαιώστε ότι το HedgeDoc εμφανίζει το σφάλμα και επανέρχεται κανονικά χωρίς καταστροφικές χειροκίνητες αλλαγές. Διατηρήστε μόνο το απαραίτητο, redacted απόσπασμα των logs. Αυτό το τετραμερές gate καλύπτει το startup, την persistence, το recovery και τον χειρισμό αποτυχιών.

Εκκινήστε το HedgeDoc χωρίς να κρύβετε τα επιμέρους στοιχεία

Μια minimal εντολή είναι χρήσιμη όταν αποκαλύπτει τι θα διαχειρίζεται αργότερα η πλατφόρμα.

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

Εδώ, η θύρα 3000 παραμένει private στον host και κάθε απαιτούμενη διαδρομή δηλώνεται ρητά. Προσθέστε τις ελεγμένες ρυθμίσεις σύνδεσης για το Postgres, καθώς και για τους προαιρετικούς OAuth και SMTP providers· χρησιμοποιήστε private names για τις private υπηρεσίες. Επιβεβαιώστε το startup τόσο από τα logs όσο και με το application-specific proof: δημιουργήστε μια σημείωση, επεξεργαστείτε την ταυτόχρονα από δύο browsers, ανεβάστε μια εικόνα και κάντε authentication μέσω του επιλεγμένου provider. Αφού ολοκληρωθεί η επιβεβαίωση, κλειδώστε την έκδοση του image, ώστε μια συνηθισμένη αντικατάσταση να μην αλλάξει αθόρυβα τη συμπεριφορά.

Μην παραχωρείτε στο HedgeDoc πρόσβαση σε ολόκληρο τον host

Για το HedgeDoc, η επιφάνεια που έχει αξία δεν είναι απαραίτητα η landing page. Το βασικό λάθος είναι να χρησιμοποιείτε ένα example session secret ή να επιτρέπετε κατά λάθος τη δημιουργία anonymous σημειώσεων. Αντιμετωπίστε το σκόπιμα: χρησιμοποιήστε ένα σταθερό session secret, αποφασίστε αν επιτρέπεται η δημιουργία anonymous σημειώσεων και περιορίστε την πρόσβαση σε private σημειώσεις.

Δημιουργήστε το CMD_SESSION_SECRET ως μια μεγάλη random τιμή· η αλλαγή του συνήθως ακυρώνει sessions ή tokens, επομένως σχεδιάστε τον αντίκτυπο στους users αντί να την αντιμετωπίζετε ως encryption migration. Χρησιμοποιήστε unprivileged container user όταν το image το υποστηρίζει και μην κάνετε mount άσχετα credentials. Εφαρμόστε rate ή size limits στο ingress, όπου untrusted εργασία μπορεί να καταναλώσει WebSocket connections, database writes, uploaded media και document history.

Δοκιμάστε το HedgeDoc εκτός του server

Επιλέξτε το τελικό hostname του HedgeDoc πριν οι users αποθηκεύσουν callbacks ή client settings και, στη συνέχεια, ορίστε τα CMD_DOMAIN και CMD_PROTOCOL_USESSL για το public URL. Το platform route πρέπει να τερματίζει το TLS μία φορά και να στοχεύει την private θύρα 3000.

Εκτελέστε εξωτερικά τη συναλλαγή acceptance. Αν ο client δεν φτάνει ποτέ στο HedgeDoc, χρησιμοποιήστε το checklist επικύρωσης SSL για τους ελέγχους DNS και certificate. Αν το request φτάνει στο HedgeDoc αλλά οι real-time επεξεργασίες αποτυγχάνουν επειδή τα WebSockets ή τα domain settings είναι λανθασμένα, σταματήστε να αλλάζετε τα proxy redirects και ελέγξτε αντί γι’ αυτό το application-specific boundary.

Λειτουργήστε το HedgeDoc με βάση το πραγματικό bottleneck του

Χρησιμοποιήστε τη δημιουργία μιας σημείωσης, την ταυτόχρονη επεξεργασία της από δύο browsers, το upload μιας εικόνας και το authentication μέσω του επιλεγμένου provider ως smoke test του HedgeDoc μετά από κάθε deployment. Τα supporting metrics του είναι οι WebSocket connections, τα database writes, τα uploaded media και το document history· δημιουργήστε alerts όταν αυτοί οι πόροι πλησιάζουν σε σημείο που υποβαθμίζει την ενέργεια του χρήστη.

Ο βασικός κίνδυνος αλλαγών είναι ότι τα database migrations του HedgeDoc, οι OAuth settings και οι αλλαγές σε plugins ή renderers χρειάζονται staged release. Ένα ασφαλές release ξεκινά από ένα restorable snapshot και επικυρώνει κάθε one-way state change πριν μεταφερθεί η κίνηση. Όταν οι real-time επεξεργασίες αποτυγχάνουν επειδή τα WebSockets ή τα domain settings είναι λανθασμένα, διατηρήστε το αποτυχημένο container για αρκετό χρόνο ώστε να διαβάσετε τη διαμόρφωσή του και το πρώτο error.

Πού το Dockup μειώνει την εργασία για το HedgeDoc

Το Dockup μπορεί να αναλάβει τα replaceable κομμάτια της πλατφόρμας: να δρομολογεί την κίνηση προς τη θύρα 3000, να εκδίδει το domain και το certificate, να κάνει inject τα secrets, να συνδέει persistent storage και να συνδέει το HedgeDoc με managed ή privately attached services. Αυτό μπορεί να γίνει είτε στην υποδομή του Dockup είτε σε server που έχετε συνδέσει.

Η acceptance εργασία του HedgeDoc παραμένει ρητή. Μετά το one-click deployment, ορίστε τα CMD_DOMAIN και CMD_PROTOCOL_USESSL για το public URL, συνδέστε και δοκιμάστε το Postgres, καθώς και τους προαιρετικούς OAuth και SMTP providers, και εκτελέστε το εξής σενάριο: δημιουργήστε μια σημείωση, επεξεργαστείτε την ταυτόχρονα από δύο browsers, ανεβάστε μια εικόνα και κάντε authentication μέσω του επιλεγμένου provider. Αυτός ο διαχωρισμός είναι σκόπιμος: το Dockup αφαιρεί την επαναλαμβανόμενη ρύθμιση υποδομής χωρίς να προσποιείται ότι οι ρόλοι της εφαρμογής, τα credentials των providers ή η πολιτική restore επιλέγονται αυτόματα.

Συχνές ερωτήσεις

Τι χρειάζεται το HedgeDoc για deployment σε production;

Δρομολογήστε το container του HedgeDoc στη θύρα 3000 μέσω ενός HTTPS origin. Η υποστηρικτική network απαίτηση είναι το Postgres, καθώς και οι προαιρετικοί OAuth και SMTP providers. Μην θεωρήσετε το HedgeDoc έτοιμο μέχρι να μπορείτε να δημιουργήσετε μια σημείωση, να την επεξεργαστείτε ταυτόχρονα από δύο browsers, να ανεβάσετε μια εικόνα και να κάνετε authentication μέσω του επιλεγμένου provider.

Ποια δεδομένα του HedgeDoc πρέπει να περιλαμβάνονται σε backup;

Διατηρήστε το /hedgedoc/public/uploads και συμπεριλάβετε τη βάση δεδομένων, τα ανεβασμένα αρχεία και το authentication configuration στο ίδιο recovery manifest. Ένα καθαρό restore του HedgeDoc θεωρείται επιτυχές μόνο όταν επανέρχονται οι σημειώσεις, τα revisions, οι users και τα uploads και δύο browsers μπορούν να συνεργαστούν στη restored σημείωση.

Απαιτεί το HedgeDoc HTTPS πίσω από reverse proxy;

Χρησιμοποιήστε HTTPS για το public origin του HedgeDoc και διατηρήστε τη θύρα 3000 στο internal route. Εφαρμόστε σωστά τη ρύθμιση του HedgeDoc: ορίστε τα CMD_DOMAIN και CMD_PROTOCOL_USESSL για το public URL. Για το HedgeDoc, το HTTPS προστατεύει τα credentials ή το περιεχόμενο των users κατά τη μεταφορά και διατηρεί συνεπή τη client behavior που εξαρτάται από το origin.

Πώς πρέπει να δοκιμάζεται μια αναβάθμιση του HedgeDoc;

Κάντε restore την τρέχουσα κατάσταση του HedgeDoc σε ένα isolated deployment, εφαρμόστε την candidate έκδοση και επαναλάβετε τη συναλλαγή acceptance. Δώστε ιδιαίτερη προσοχή, επειδή τα database migrations του HedgeDoc, οι OAuth settings και οι αλλαγές σε plugins ή renderers χρειάζονται staged release. Διατηρήστε το προηγούμενο HedgeDoc image μέχρι να κατανοήσετε τα όρια του data migration και του rollback.