Näin hostaatte BookStackin Managed VPS:llä: dokumentaationne omalla palvelimella

Mitä BookStack tekee

BookStack on dokumentaatioalusta, joka on suunniteltu pysymään yksinkertaisena: sen README tähtää välittömään käyttöönottoon pelkillä tekstinkäsittelyn perustaidoilla. Tiiminne kirjoittavat siihen menettelynsä, dokumentaationsa ja tietopankkinsa selaimessa, halutessaan suomeksi.

• Neljä järjestystasoa: hyllyt kokoavat kirjoja, kirjoissa on lukuja ja sivuja, luvut ovat valinnaisia, ja sisältö elää sivuilla.
• Kaksi editoria: oletuksena visuaalinen editori ja Markdown-editori suoralla esikatselulla, joiden lisäksi diagrams.net-kaaviot.
• Haku: yhdestä kirjasta tai kaikista kirjoista, luvuista ja sivuista.
• Oikeudet: roolit koko järjestelmälle sekä hyllyn, kirjan, luvun tai sivun omat käyttöoikeudet.
• Kirjautumiset: sähköposti ja salasana, OpenID Connect, SAML 2.0, LDAP sekä kaksivaiheinen tunnistautuminen sovelluksella tai varakoodeilla, jonka voi pakottaa rooleittain.
• Seuranta ja vaihto: jokaisen sivun versiohistoria, REST-rajapinta sekä vienti HTML-, PDF-, teksti-, Markdown- tai siirrettävänä ZIP-muodossa.

Projekti ottaa valintansa omakseen: sen README täsmentää, ettei BookStackia ole suunniteltu laajennettavaksi alustaksi muihin käyttötarkoituksiin, ja se pysyy dokumentaatiossa. Sen PDF-renderöinti kulkee dompdf:n kautta ilman lisäasennusta, rajoitetuin ominaisuuksin; projekti dokumentoi muita moottoreita muuttujalla EXPORT_PDF_COMMAND.

Mitä MIT-lisenssi sallii

BookStack julkaistaan MIT-lisenssillä Dan Brownin ja projektin kehittäjien toimesta. Se sallii kaiken käytön, muokkauksen ja jakelun yhdellä ehdolla: tekijänoikeusmerkintä ja lisenssin teksti säilytetään ohjelmiston jokaisessa kopiossa. Projektin UKK täsmentää, että tämä tekijänosoitus koskee koodia, jonka jaatte: mikään ei velvoita näyttämään BookStackin nimeä tai logoa instanssissanne.

Projekti ylläpitää yhtä, vapaata ja maksutonta versiota: se ei tarjoa yritysversiota, eikä sillä ole virallista hostausta tai aikomusta avata sellaista. Se myy sen sijaan tukipaketteja, jotka rahoittavat sitä lahjoitusten ja tukijoiden rinnalla. BookStack asennetaan siis palvelimellenne ilman ostettavaa lisenssiä.

BookStackin vaatimukset

Docker on edelleen valinnainen. Projekti ei julkaise virallista imagea: konttiasennukset tulevat yhteisöprojekteista, LinuxServer.io:sta ja solidnerdiltä. Tämä opas noudattaa virallista tietä, PHP ja MySQL suoraan palvelimella, joka ei vaadi mitään enempää.

Dokumentaatio sulkee pois jaetun PHP-hostauksen: BookStack vaatii palvelimen, jota itse ylläpidätte. Se ei ilmoita tarvittavaa muistia eikä suoritinta. Managed VPS -palvelimella kuvailkaa meille käyttötarkoituksenne, käyttäjien määrä sekä kuvien ja liitteiden tilavuus, niin suosittelemme sopivaa kokoa.

BookStackin asennus

Projekti tarjoaa kaksi tietä: skriptin Ubuntulle, lyhin uudella palvelimella, ja käsin tehtävän asennuksen kaikkiin muihin tapauksiin.

Projektin skriptillä, aivan uudella Ubuntulla

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

Nämä skriptit on varattu juuri asennetulle järjestelmälle: ne voivat ylikirjoittaa olemassa olevan verkkopalvelinasetuksen. Ne jättävät myös kaksi asiaa käsittelemättä, sähköpostiasetukset ja järjestelmän tietoturvan, jotka on suunniteltava erikseen.

Skripti asentaa BookStackin kansioon /var/www/bookstack. Ubuntu 26.04:n skripti kysyy verkkotunnuksen ja ylläpitäjän tilin osoitteen ja näyttää lopuksi satunnaisesti arvotun salasanan, joka ei ole sen lokissa: kirjoittakaa se muistiin. Toisella skriptillä ottakaa talteen lopuksi näytetyt tunnukset ja vaihtakaa kaikki oletustunnukset ensimmäisellä kirjautumiskerralla.

Käsin, millä tahansa muulla koneella

Aloittakaa tietokannasta: yksi tietokanta ja käyttäjä, joka on rajattu vain tähän tietokantaan. Projektin skripti toimii näin, valitsemallanne salasanalla kohdan change-me tilalla:

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;"

Hakekaa sitten haara release, asettakaa oikeudet, jotka dokumentaatio antaa kansiolle /var/www/bookstack, ja asentakaa riippuvuudet:

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

Täyttäkää tietokanta ja osoite tiedostoon .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

Osoittakaa lopuksi verkkojuuri kansioon public: DocumentRoot Apachella, root Nginxillä. Ilman Apachea tai kun .htaccess-tiedostot on poistettu käytöstä, lisätkää osoitteiden uudelleenkirjoitussäännöt: projekti julkaisee esimerkkejä Apachelle ja Nginxille.

Käsin tehty asennus avautuu tilillä admin@admin.com ja salasanalla password. Vaihtakaa osoite ja salasana ensimmäisellä kirjautumiskerralla.

HTTPS ja APP_URL

Kävijät saapuvat portteihin 80 ja 443 palvelimen verkkotunnuksella. Luokaa tälle nimelle A- ja AAAA-tietueet ja pyytäkää sitten varmenne: Ubuntu 26.04:n skripti määrittää Apachen vain porttiin 80, ja asennussivu jättää HTTPS:n teidän huolehdittavaksenne. Certbot asentaa Let’s Encrypt -varmenteen, mukauttaa Apachen ja uusii varmenteen itse. Nginxillä korvatkaa --apache valinnalla --nginx.

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

Vaihtakaa sitten osoite HTTPS:ään tiedostossa .env. APP_URL-arvon on vastattava täsmälleen vierailuosoitetta, etuliite mukaan lukien: poikkeama näkyy puuttuvina tyyleinä, ylimitoitettuina kuvakkeina ja rikkinäisinä valikkoina. https-muotoinen osoite ottaa suojatut evästeet käyttöön itsestään.

APP_URL=https://docs.example.com

Jos sivuja on jo olemassa, niiden linkeissä on vanha osoite tietokannassa. Varmuuskopioikaa tietokanta ja ajakaa sitten projektin komento:

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

BookStack tarjotaan verkkotunnuksen tai aliverkkotunnuksen juuressa, ja dokumentaatio kuvaa myös asennuksen alikansioon, kuten example.com/bookstack. Jos Apachen eteen lisätään käänteinen välityspalvelin, ilmoittakaa sen osoite muuttujassa APP_PROXIES: ilman sitä auditointiloki ja nopeusrajoitus näkevät välityspalvelimen osoitteen kävijöiden osoitteen sijaan. Dokumentaatio varaa arvon APP_PROXIES="*" vianmääritykseen.

Missä tietonne elävät

Säilyttäkää sama APP_KEY pitkään ja varmuuskopioikaa se. BookStack käyttää sitä muun muassa kaksivaiheisen tunnistautumisen salaisuuksien salaamiseen: sen vaihtaminen voi rikkoa nämä toiminnot, ja versiosta 26.09 alkaen sovellus palauttaa virheen, jos se puuttuu.

Kuvat ovat oletuksena julkisia

Oletustallennuksella verkkopalvelin tarjoaa kuvat suoraan, mikä on nopeaa, ja jokainen, joka tuntee niiden osoitteen, voi avata ne. Sisäiselle dokumentaatiolle valinta tehdään muuttujalla STORAGE_TYPE:

Raskaita tiedostoja varten kolmen asetuksen on sovittava yhteen: FILE_UPLOAD_SIZE_LIMIT tiedostossa .env, post_max_size ja upload_max_filesize tiedostossa php.ini sekä client_max_body_size Nginxillä, joka on oletuksena 1 Mt.

Kaksi asetusta on tärkeää myös elävälle dokumentaatiolle: jokainen sivu säilyttää oletuksena 100 versiota (REVISION_LIMIT), ja roskakori säilyttää poistetut kohteet 30 päivää (RECYCLE_BIN_LIFETIME).

Sähköpostit: SMTP ja jono

BookStack lähettää sähköposteja osoitteiden vahvistukseen, unohtuneeseen salasanaan, kutsuihin ja ilmoituksiin. Simafrin VPS:ltä lähetys kulkee todennetun SMTP-releen kautta portissa 587: käyttöön sopii jo omistamanne sähköpostitilin osoite tai 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

Tarkistakaa tulos kohdassa ”Settings”, ”Maintenance” toiminnolla ”Send a Test Email”, joka näyttää kohdatut virheet. Kutsun epäonnistuminen näkyy ruudulla, kun taas ilmoituksen epäonnistuminen jää sovelluksen lokiin.

Lähetys taustalla

Oletuksena BookStack lähettää sähköpostit ja webhookit pyynnön aikana, mikä voi hidastaa sivuja. Siirtyäksenne taustalle kirjoittakaa QUEUE_CONNECTION=database tiedostoon .env ja ajakaa palvelua dokumentaation esimerkillä, joka on annettu skriptillä tehdylle Ubuntu-asennukselle:

[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-instanssinne suojaaminen

Tietoturvadokumentaatio antaa luettelon, joka kannattaa käydä läpi heti asennuksessa:

1. Vaihtakaa ensimmäisen ylläpitäjän osoite ja salasana.
2. Varmistakaa, että verkkopalvelin tarjoaa vain kansion public, etenkin jos BookStack on kansion /var/www alla.
3. Rajatkaa tietokannan käyttäjä vain BookStackin tietokantaan.
4. Täyttäkää APP_URL, jotta järjestelmän luomia osoitteita ei voi manipuloida.
5. Lukekaa rekisteröitymis- ja julkisen pääsyn asetukset ja sen jälkeen roolit läpi.

Kaksivaiheinen tunnistautuminen pakotetaan sen jälkeen rooleittain. Tilatkaa myös projektin tietoturvapostituslista saadaksenne sen hälytykset. Osoite /status palvelee valvontaa: se vastaa 200, kun kaikki on kunnossa, ja virhekoodilla 400 tai sitä suuremmalla muuten.

PHP on yhtä tärkeä kuin BookStack. Projekti julkaisi 21. lokakuuta 2026 hälytyksen PHP:n kriittisestä päivityksestä, joka korjattiin versioissa 8.5.12, 8.4.27, 8.3.36 ja 8.2.35. Ubuntu julkaisee nämä korjaukset omilla pakettinumeroillaan, kuten 8.3.6-0ubuntu0.24.04.13 Ubuntu 24.04:lle.

Sisällöillenne pitäkää oletuksena käytössä oleva suodatus ja varatkaa sen höllentäminen instansseille, joissa kirjoittavat vain luotetut henkilöt. Jos ylläpitäjän tili katoaa, php artisan bookstack:create-admin luo uuden, ja php artisan bookstack:reset-mfa poistaa käyttäjän kaksivaiheisen tunnistautumisen.

Varmuuskopiot ja päivitykset

Täydellinen varmuuskopio kokoaa yhteen tietokannan ja instanssinne neljä tiedostosijaintia. Sisällön viennit palvelevat muuta: dokumentaatio täsmentää, etteivät ne korvaa varmuuskopiota.

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

Ensimmäinen rivi koskee skriptillä tehtyä asennusta, jossa MySQL:n root kirjautuu sudolla; muualla kirjoittakaa mysqldump -u bookstack -p bookstack. Säilyttäkää nämä kaksi tiedostoa erillään, mieluiten toisella koneella. Arkisto sisältää tiedoston .env, siis APP_KEY-avaimen ja salasananne: käsitelkää sitä salaisuutena.

Palauttaminen

Uudella koneella asentakaa BookStack ajamatta komentoa php artisan migrate, vaihe, joka kommentoidaan skriptistä, jos käytätte sitä, ja palauttakaa sitten tietokanta ja tiedostot säilyttäen alkuperäisen APP_KEY-avaimen:

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

Jos asennettu versio on varmuuskopiota uudempi, ajakaa sen jälkeen php artisan migrate. Palauttakaa verkkopalvelimen kirjoitusoikeudet palautettuihin kansioihin. Jos osoite on muuttunut, korjatkaa APP_URL ja ajakaa bookstack:update-url.

Päivittäminen

Varmuuskopioikaa tietokanta ja tiedostot ennen jokaista päivitystä ja ajakaa sitten BookStackin kansiosta:

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:n skripti asentaa BookStackin ilman Composeria. Päivityssivu ehdottaa silloin, betana, komentoa ./bookstack-system-cli download-vendor komennon composer install --no-dev tilalle. Sama työkalu osaa varmuuskopioida ja palauttaa, mutta projekti ei vielä pidä sitä tuotantokelpoisena: testatkaa se, ennen kuin luotatte siihen.

Dokumentaatio ylläpitää luetteloa kunkin version omista ohjeista, luettavaksi tavoiteltavaa versiota varten. Joitakin esimerkkejä:

• Versio 26.09: APP_KEY tulee pakolliseksi.
• Versio 26.05: kansion storage/fonts on pysyttävä verkkopalvelimen kirjoitettavana, muuten PDF-viennit voivat epäonnistua.
• Versio 26.03: kokeilkaa sähköpostin lähetystä päivityksen jälkeen.
• Versio 25.11: suuria tietokantamuutoksia, joiden migraatio voi kestää useita minuutteja suurella instanssilla.

Haavoittuvuudet korjataan ylläpitoversioissa, kuten 11. marraskuuta 2026 julkaistussa 26.09.3:ssa: luonnoksena tai roskakorissa olevan sivun kuvat ja piirrokset olivat yhä saatavilla ja muokattavissa, ja muokkaajan henkilökohtainen luonnos saattoi näkyä muille henkilöille.

Kuka tekee mitä Managed VPS:llä

Oma hostaus vaatii palvelimen ylläpitoa sovelluksen lisäksi. Managed VPS -palvelimella tiimimme huolehtivat palvelimesta ja seuraavat instanssianne proaktiivisesti; BookStack pysyy teidän ohjelmananne asetuksineen ja tietoineen.

Jos haluatte tiimiemme toimivan itse sovelluksessa, tämä palvelu laskutetaan tuntiveloituksella tai kiinteällä hinnalla, ja arvio annetaan ennen toimenpidettä.