Φιλοξενήστε το BookStack σε Managed VPS: η τεκμηρίωσή σας σε δικό σας διακομιστή

Τι κάνει το BookStack

Το BookStack είναι μια πλατφόρμα τεκμηρίωσης σχεδιασμένη να μένει απλή: το README του στοχεύει σε άμεση εξοικείωση, με απλές γνώσεις επεξεργασίας κειμένου. Οι ομάδες σας γράφουν εκεί τις διαδικασίες, την τεκμηρίωση και τη βάση γνώσεών τους, μέσα σε έναν περιηγητή, στα ελληνικά αν το θέλουν.

• Τέσσερα επίπεδα οργάνωσης: τα ράφια ομαδοποιούν βιβλία, τα βιβλία φέρουν κεφάλαια και σελίδες, τα κεφάλαια είναι προαιρετικά, και το περιεχόμενο ζει στις σελίδες.
• Δύο επεξεργαστές: ένας οπτικός επεξεργαστής εξ ορισμού, και ένας επεξεργαστής Markdown με ζωντανή προεπισκόπηση, στους οποίους προστίθενται τα σχεδιαγράμματα του diagrams.net.
• Η αναζήτηση: μέσα σε ένα βιβλίο, ή σε όλα τα βιβλία, τα κεφάλαια και τις σελίδες.
• Τα δικαιώματα: ρόλοι για ολόκληρο το σύστημα, και δικαιώματα ιδιαίτερα για ένα ράφι, ένα βιβλίο, ένα κεφάλαιο ή μια σελίδα.
• Οι συνδέσεις: email και κωδικός πρόσβασης, OpenID Connect, SAML 2.0, LDAP, με έλεγχο ταυτότητας δύο παραγόντων μέσω εφαρμογής ή κωδικών ανάγκης, που μπορεί να επιβληθεί ανά ρόλο.
• Η παρακολούθηση και οι ανταλλαγές: το ιστορικό των αναθεωρήσεων κάθε σελίδας, ένα API REST, και η εξαγωγή σε HTML, PDF, κείμενο, Markdown ή φορητό ZIP.

Το έργο αναλαμβάνει τις επιλογές του: το README του διευκρινίζει ότι το BookStack δεν έχει σχεδιαστεί ως πλατφόρμα επεκτάσιμη προς άλλες χρήσεις, και μένει προσηλωμένο στην τεκμηρίωση. Η απόδοση PDF περνά από το dompdf, χωρίς επιπλέον εγκατάσταση, με περιορισμένες δυνατότητες· το έργο τεκμηριώνει άλλες μηχανές με το EXPORT_PDF_COMMAND.

Τι επιτρέπει η άδεια MIT

Το BookStack δημοσιεύεται με την άδεια MIT από τον Dan Brown και τους συντελεστές του έργου. Επιτρέπει κάθε χρήση, κάθε τροποποίηση και κάθε διανομή, με έναν όρο: να διατηρείται η σημείωση πνευματικών δικαιωμάτων και το κείμενο της άδειας σε κάθε αντίγραφο του λογισμικού. Οι συχνές ερωτήσεις του έργου διευκρινίζουν ότι η απόδοση αυτή αφορά τον κώδικα που μοιράζεστε: τίποτα δεν σας υποχρεώνει να εμφανίζετε το όνομα ή το λογότυπο του BookStack στο στιγμιότυπό σας.

Το έργο κρατά μία μόνο έκδοση, ελεύθερη και δωρεάν: δεν προσφέρει έκδοση για επιχειρήσεις, και δεν έχει επίσημη φιλοξενία, ούτε σχέδιο να ανοίξει μία. Πουλά ωστόσο πλάνα υποστήριξης, που συμβάλλουν στη χρηματοδότησή του μαζί με τις δωρεές και τις χορηγίες. Το BookStack εγκαθίσταται λοιπόν στον διακομιστή σας, χωρίς να αγοράσετε άδεια.

Τα προαπαιτούμενα του BookStack

Το Docker παραμένει προαιρετικό. Το έργο δεν δημοσιεύει επίσημη εικόνα: οι εγκαταστάσεις σε κοντέινερ προέρχονται από κοινοτικά έργα, το LinuxServer.io και το solidnerd. Ο οδηγός αυτός ακολουθεί την επίσημη διαδρομή, PHP και MySQL απευθείας στον διακομιστή, που δεν ζητά τίποτα παραπάνω.

Η τεκμηρίωση αποκλείει την κοινόχρηστη φιλοξενία PHP: το BookStack ζητά έναν διακομιστή που τον διαχειρίζεστε εσείς. Δεν δίνει αριθμούς για τη μνήμη ή τον επεξεργαστή που χρειάζονται. Σε ένα Managed VPS, περιγράψτε μας τη χρήση σας, τον αριθμό των ατόμων και τον όγκο των εικόνων και των συνημμένων, και σας προτείνουμε το μέγεθος που ταιριάζει.

Η εγκατάσταση του BookStack

Το έργο προτείνει δύο διαδρομές: ένα σενάριο για Ubuntu, το συντομότερο σε έναν νέο διακομιστή, και μια χειροκίνητη εγκατάσταση για όλες τις άλλες περιπτώσεις.

Με το σενάριο του έργου, σε ένα ολοκαίνουργιο Ubuntu

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

Τα σενάρια αυτά προορίζονται για φρεσκοεγκατεστημένο σύστημα: μπορούν να αντικαταστήσουν μια υπάρχουσα διαμόρφωση ιστού. Αφήνουν επίσης έξω δύο θέματα, τις ρυθμίσεις email και την ασφάλεια του συστήματος, που πρέπει να τα προβλέψετε χωριστά.

Το σενάριο τοποθετεί το BookStack στο /var/www/bookstack. Αυτό του Ubuntu 26.04 ζητά τον τομέα και τη διεύθυνση του λογαριασμού διαχειριστή, και εμφανίζει στο τέλος έναν τυχαίο κωδικό πρόσβασης, που απουσιάζει από το αρχείο καταγραφής του: σημειώστε τον. Με άλλο σενάριο, κρατήστε τα στοιχεία πρόσβασης που εμφανίζονται στο τέλος και αλλάξτε κάθε προεπιλεγμένη πρόσβαση από την πρώτη σύνδεση.

Με το χέρι, σε οποιοδήποτε άλλο μηχάνημα

Ξεκινήστε από τη βάση δεδομένων: μία βάση, και ένας χρήστης περιορισμένος σε αυτήν τη βάση. Το σενάριο του έργου ακολουθεί αυτή τη διαδικασία, με τον κωδικό πρόσβασης της επιλογής σας στη θέση του change-me:

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Κατεβάστε έπειτα τον κλάδο release, ορίστε τα δικαιώματα που δίνει η τεκμηρίωση για το /var/www/bookstack, και εγκαταστήστε τις εξαρτήσεις:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Συμπληρώστε τη βάση και τη διεύθυνση στο .env:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Κατευθύνετε τέλος τη ρίζα ιστού στον φάκελο public: DocumentRoot στο Apache, root στο Nginx. Χωρίς Apache, ή όταν τα αρχεία .htaccess είναι απενεργοποιημένα, προσθέστε τους κανόνες επανεγγραφής διευθύνσεων: το έργο δημοσιεύει παραδείγματα για το Apache και για το Nginx.

Μια χειροκίνητη εγκατάσταση ανοίγει με τον λογαριασμό admin@admin.com και τον κωδικό πρόσβασης password. Αλλάξτε τη διεύθυνση και τον κωδικό από την πρώτη σύνδεση.

HTTPS και APP_URL

Οι επισκέπτες φτάνουν στις θύρες 80 και 443, με το όνομα τομέα του διακομιστή. Δημιουργήστε για το όνομα αυτό εγγραφές A και AAAA, και ζητήστε έπειτα το πιστοποιητικό: το σενάριο του Ubuntu 26.04 ρυθμίζει το Apache μόνο στη θύρα 80, και η σελίδα εγκατάστασης αφήνει το HTTPS στο χέρι σας. Το Certbot εγκαθιστά το πιστοποιητικό Let’s Encrypt, προσαρμόζει το Apache και ανανεώνει το πιστοποιητικό μόνο του. Με Nginx, αντικαταστήστε το --apache με --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Περάστε έπειτα τη διεύθυνση σε HTTPS στο .env. Το APP_URL πρέπει να αντιστοιχεί ακριβώς στη διεύθυνση επίσκεψης, μαζί με το πρόθεμα: μια απόκλιση φαίνεται από στυλ που λείπουν, υπερβολικά μεγάλα εικονίδια και χαλασμένα μενού. Μια διεύθυνση σε https ενεργοποιεί μόνη της τα ασφαλή cookies.

APP_URL=https://docs.example.com

Αν υπάρχουν ήδη σελίδες, οι σύνδεσμοί τους κρατούν την παλιά διεύθυνση στη βάση. Κρατήστε αντίγραφο της βάσης και εκτελέστε έπειτα την εντολή του έργου:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

Το BookStack σερβίρεται στη ρίζα ενός τομέα ή υποτομέα, και η τεκμηρίωση περιγράφει επίσης μια εγκατάσταση κάτω από υποφάκελο, όπως το example.com/bookstack. Αν προστεθεί reverse proxy μπροστά από το Apache, δηλώστε τη διεύθυνσή του στο APP_PROXIES: χωρίς αυτό, το αρχείο ελέγχου και ο περιορισμός ρυθμού βλέπουν τη διεύθυνση του proxy στη θέση εκείνης των επισκεπτών. Η τεκμηρίωση επιφυλάσσει το APP_PROXIES="*" για τη διάγνωση.

Πού ζουν τα δεδομένα σας

Κρατήστε το ίδιο APP_KEY στη διάρκεια του χρόνου και φυλάξτε αντίγραφό του. Το BookStack το χρησιμοποιεί για να κρυπτογραφεί μεταξύ άλλων τα μυστικά του ελέγχου ταυτότητας δύο παραγόντων: η αλλαγή του μπορεί να χαλάσει τις λειτουργίες αυτές, και από την έκδοση 26.09 η εφαρμογή επιστρέφει σφάλμα αν λείπει.

Οι εικόνες είναι δημόσιες εξ ορισμού

Με την προεπιλεγμένη αποθήκευση, ο διακομιστής ιστού σερβίρει απευθείας τις εικόνες, κάτι που είναι γρήγορο, και όποιος γνωρίζει τη διεύθυνσή τους μπορεί να τις ανοίξει. Για μια εσωτερική τεκμηρίωση, η επιλογή γίνεται στο STORAGE_TYPE:

Για τα βαριά αρχεία, τρεις ρυθμίσεις πρέπει να συμφωνούν: το FILE_UPLOAD_SIZE_LIMIT στο .env, τα post_max_size και upload_max_filesize στο php.ini, και το client_max_body_size στο Nginx, που ισούται με 1 MB εξ ορισμού.

Δύο ρυθμίσεις μετρούν επίσης για μια ζωντανή τεκμηρίωση: κάθε σελίδα κρατά 100 αναθεωρήσεις εξ ορισμού (REVISION_LIMIT), και ο κάδος ανακύκλωσης διατηρεί τα διαγραμμένα στοιχεία για 30 ημέρες (RECYCLE_BIN_LIFETIME).

Τα email: SMTP και ουρά

Το BookStack στέλνει email για την επιβεβαίωση των διευθύνσεων, τη λήθη του κωδικού πρόσβασης, τις προσκλήσεις και τις ειδοποιήσεις. Από ένα VPS της Simafri, η αποστολή περνά από ένα πιστοποιημένο relay SMTP, στη θύρα 587: τη διεύθυνση ενός λογαριασμού email που έχετε ήδη, ή το Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Ελέγξτε το αποτέλεσμα στα «Settings», «Maintenance», με την ενέργεια «Send a Test Email», που εμφανίζει τα σφάλματα που προέκυψαν. Μια αποτυχία κατά την πρόσκληση εμφανίζεται στην οθόνη, ενώ μια αποτυχία ειδοποίησης μένει στο αρχείο καταγραφής της εφαρμογής.

Αποστολή στο παρασκήνιο

Εξ ορισμού, το BookStack στέλνει email και webhooks κατά τη διάρκεια του αιτήματος, κάτι που μπορεί να επιβραδύνει τις σελίδες. Για να περάσετε στο παρασκήνιο, γράψτε QUEUE_CONNECTION=database στο .env και τρέξτε μια υπηρεσία, με το παράδειγμα που δίνει η τεκμηρίωση για μια εγκατάσταση Ubuntu με σενάριο:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Ασφάλεια του στιγμιοτύπου BookStack

Η τεκμηρίωση ασφαλείας δίνει μια λίστα που πρέπει να εφαρμόσετε από την εγκατάσταση:

1. Αλλάξτε τη διεύθυνση και τον κωδικό πρόσβασης του πρώτου διαχειριστή.
2. Ελέγξτε ότι ο διακομιστής ιστού σερβίρει μόνο τον φάκελο public, ιδίως αν το BookStack ζει κάτω από το /var/www.
3. Περιορίστε τον χρήστη της βάσης στη μόνη βάση του BookStack.
4. Συμπληρώστε το APP_URL, ώστε οι διευθύνσεις που παράγει το σύστημα να μη μπορούν να χειραγωγηθούν.
5. Ξαναδιαβάστε τις ρυθμίσεις εγγραφής και δημόσιας πρόσβασης, και έπειτα τους ρόλους.

Ο έλεγχος ταυτότητας δύο παραγόντων επιβάλλεται έπειτα ανά ρόλο. Εγγραφείτε επίσης στη λίστα αλληλογραφίας ασφαλείας του έργου, για να λαμβάνετε τις ειδοποιήσεις του. Η διεύθυνση /status εξυπηρετεί μια επιτήρηση: απαντά 200 όταν όλα πάνε καλά, και έναν κωδικό σφάλματος ίσο ή μεγαλύτερο του 400 διαφορετικά.

Η PHP μετρά όσο και το BookStack. Το έργο δημοσίευσε στις 21 Οκτωβρίου 2026 μια ειδοποίηση για μια κρίσιμη ενημέρωση της PHP, που διορθώθηκε στις 8.5.12, 8.4.27, 8.3.36 και 8.2.35. Το Ubuntu δημοσιεύει τις διορθώσεις αυτές με δικούς του αριθμούς πακέτων, όπως το 8.3.6-0ubuntu0.24.04.13 για το Ubuntu 24.04.

Για τα περιεχόμενά σας, κρατήστε ενεργό το προεπιλεγμένο φιλτράρισμα, και επιφυλάξτε τη χαλάρωσή του για στιγμιότυπα όπου γράφουν μόνο έμπιστα πρόσωπα. Αν χαθεί ένας λογαριασμός διαχειριστή, το php artisan bookstack:create-admin δημιουργεί έναν άλλον, και το php artisan bookstack:reset-mfa αφαιρεί τον έλεγχο ταυτότητας δύο παραγόντων ενός χρήστη.

Αντίγραφα ασφαλείας και ενημερώσεις

Ένα πλήρες αντίγραφο ασφαλείας συγκεντρώνει τη βάση και τις τέσσερις τοποθεσίες αρχείων που ανήκουν στο στιγμιότυπό σας. Οι εξαγωγές περιεχομένου εξυπηρετούν κάτι άλλο: η τεκμηρίωση διευκρινίζει ότι δεν αντικαθιστούν ένα αντίγραφο ασφαλείας.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

Η πρώτη γραμμή αφορά μια εγκατάσταση με σενάριο, όπου ο root της MySQL συνδέεται μέσω sudo· αλλού, γράψτε mysqldump -u bookstack -p bookstack. Φυλάξτε τα δύο αυτά αρχεία χωριστά, κατά προτίμηση σε άλλο μηχάνημα. Το αρχείο περιέχει το .env, άρα το APP_KEY και τους κωδικούς πρόσβασής σας: αντιμετωπίστε το ως μυστικό.

Επαναφορά

Σε ένα νέο μηχάνημα, εγκαταστήστε το BookStack χωρίς να εκτελέσετε το php artisan migrate, ένα βήμα που πρέπει να βάλετε σε σχόλιο στο σενάριο αν το χρησιμοποιείτε, και επαναφέρετε έπειτα τη βάση και τα αρχεία, κρατώντας το αρχικό APP_KEY:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Αν η εγκατεστημένη έκδοση είναι νεότερη από το αντίγραφο ασφαλείας, εκτελέστε έπειτα php artisan migrate. Επαναφέρετε τα δικαιώματα εγγραφής του διακομιστή ιστού στους φακέλους που επαναφέρθηκαν. Αν η διεύθυνση άλλαξε, διορθώστε το APP_URL και εκτελέστε το bookstack:update-url.

Ενημέρωση

Κρατήστε αντίγραφο της βάσης και των αρχείων πριν από κάθε ενημέρωση και, έπειτα, από τον φάκελο του BookStack:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Το σενάριο για το Ubuntu 26.04 εγκαθιστά το BookStack χωρίς Composer. Η σελίδα των ενημερώσεων προτείνει τότε, σε beta, το ./bookstack-system-cli download-vendor στη θέση του composer install --no-dev. Το ίδιο εργαλείο ξέρει να κρατά αντίγραφα και να επαναφέρει, αλλά το έργο δεν το θεωρεί ακόμη έτοιμο για την παραγωγή: δοκιμάστε το πριν το εμπιστευτείτε.

Η τεκμηρίωση τηρεί μια λίστα οδηγιών ιδιαίτερων για κάθε έκδοση, που πρέπει να διαβάσετε για την έκδοση που στοχεύετε. Μερικά παραδείγματα:

• Έκδοση 26.09: το APP_KEY γίνεται υποχρεωτικό.
• Έκδοση 26.05: ο φάκελος storage/fonts πρέπει να μένει εγγράψιμος για τον διακομιστή ιστού, αλλιώς οι εξαγωγές PDF μπορεί να αποτύχουν.
• Έκδοση 26.03: δοκιμάστε την αποστολή email μετά την ενημέρωση.
• Έκδοση 25.11: μεγάλες αλλαγές στη βάση, των οποίων η μετατροπή μπορεί να πάρει αρκετά λεπτά σε ένα μεγάλο στιγμιότυπο.

Τα ελαττώματα διορθώνονται σε εκδόσεις συντήρησης, όπως η 26.09.3 της 11ης Νοεμβρίου 2026: οι εικόνες και τα σχέδια μιας σελίδας σε πρόχειρο ή στον κάδο ανακύκλωσης έμεναν προσβάσιμα και τροποποιήσιμα, και το προσωπικό πρόχειρο ενός συντάκτη μπορούσε να γίνει ορατό σε άλλα πρόσωπα.

Ποιος κάνει τι σε ένα Managed VPS

Το self-hosting απαιτεί να φροντίζετε τον διακομιστή εκτός από την εφαρμογή. Σε ένα Managed VPS, οι ομάδες μας αναλαμβάνουν τον διακομιστή και παρακολουθούν προληπτικά το στιγμιότυπό σας· το BookStack μένει δικό σας λογισμικό, με τις ρυθμίσεις και τα δεδομένα του.

Αν προτιμάτε να παρεμβαίνουν οι ομάδες μας μέσα στην ίδια την εφαρμογή, η υπηρεσία αυτή χρεώνεται ανά ώρα ή κατ’ αποκοπή, με κοστολόγηση που σας ανακοινώνεται πριν από την παρέμβαση.