前言

很多時候我們寫完 Code 必須再寫一份文件，讓你的客戶或是接手專案的人看得懂程式碼的運作方式。除了註解在程式碼上，也很常看到寫一份 Markdown 文件的。甚至台灣很多公司更扯用 PDF，每次看完腦袋都很像被炸過。

今天介紹的這款 Bookstack 就是專門讓這些文件們放的地方，這裡是他的 官方網站。

預先準備

在我們開始之前，你必須先自己準備 SQL。建立一個資料庫及使用者，供 Bookstack 使用。

關於 SQL 這裡不多贅述，若有需要可以參考 在 Linux 上安裝 MySQL 或 MariaDB。

安裝必要套件

由於他的 安裝方法 有很多，甚至有自動安裝的 Shell 檔。所以這篇文章會使用手動安裝的方式，這樣當你在過程中發生什麼錯誤，回頭除錯應該會更容易理解一些。

首先，我們必須先為我們的 Linux 安裝一些套件。

sudo apt-get install -y nginx nginx-extras git php-fpm php-mysql php-curl php-dom php-gd php-xml php-zip

安裝 PHP 的套件管理程式 Composer。

sudo php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sudo php composer-setup.php
sudo php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

設定 Bookstack

建立一個目錄 /var/www/bookstack 並進入他。

sudo mkdir -p /var/www/bookstack && cd /var/www/bookstack

使用 git 將檔案們 clone 進來。

sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch .

使用 Composer 安裝依賴的套件。

sudo composer install --no-dev

將 .env.example 重新命名為 .env，並修改裡面的內容

sudo mv .env.example .env && sudo vim .env

在這個檔案中，你必須修改這些內容：網站網址、資料庫帳號密碼、Email 發信細節

讓 storage、bootstrap/cache 以及 public/uploads 有正確的權限。

sudo chown -R www-data: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
sudo chmod 640 /var/www/bookstack/.env

產生一個金鑰（他會自己寫入 .env 檔案）

sudo php artisan key:generate

執行以下命令更新資料庫。

sudo php artisan migrate

設定 Nginx

接著我們必須設定我們的 Nginx。前往 /etc/nginx/sites-enabled 並建立一個檔案 bookstack。

cd /etc/nginx/sites-enabled && sudo vim bookstack

貼上以下內容並適當更改。

server {
    listen 80;
    listen [::]:80;

    server_name your.domain.com;

    root /var/www/bookstack/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        # 更改成你正在使用的 PHP 版本
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

驗證並重啟 Nginx。

sudo nginx -t && sudo systemctl restart nginx

訪問網站

接著，你就可以打開你的網站，並使用帳號 admin@admin.com 及密碼 password 登入進系統囉。

你可以進到 Settings > Users 來變更預設帳號 Admin 的信箱及密碼。

編輯畫面可以根據你的喜好，選擇這種所見及所得，也可以選用 Markdown 語法。

結語

你成功架設了 Bookstack。現在你可以運用這個平台，來書寫你的文件囉！