Tự host BookStack trên Linux

Mục Lục

BookStack là nền tảng wiki tự host để quản lý tài liệu HomeLab. Bài này biên tập đầy đủ quy trình cài đặt Linux từ tutorial của i12bretro, gồm Apache, MariaDB, PHP, Composer, file .env và virtual host. Các mật khẩu mẫu trong nguồn được thay bằng placeholder; hãy tự tạo secret riêng khi triển khai.

Nguồn tham khảo: i12bretro – Install BookStack on Linux . Video gốc thuộc kênh i12bretro trên YouTube .

Chuẩn bị

Một máy Linux có quyền sudo.
Hostname hoặc domain sẽ dùng cho BookStack.
MariaDB, Apache và PHP tương thích với phiên bản BookStack đang cài.
Một mật khẩu database riêng và app key được tạo bằng Artisan.

Cài package nền

Đăng nhập Linux host.
Cập nhật package list:

1
sudo apt update

Cài các bản cập nhật có sẵn:

1
sudo apt upgrade -y

Cài công cụ cần thiết:

1
sudo apt install git openssl curl wget zip composer -y

Cài Apache và MariaDB:

1
sudo apt install apache2 mariadb-server mariadb-client -y

Cài PHP và các extension BookStack thường cần:

1
sudo apt install php libapache2-mod-php php-curl php-tokenizer php-ldap php-cli php-json php-gd php-mbstring php-mysql php-xml php-zip php-bcmath -y

Khóa cấu hình MariaDB

Chạy trình bảo mật MariaDB:

1
sudo mysql_secure_installation

Khi được hỏi đăng nhập root, nhấn Enter nếu hệ thống chưa có root password.
Chọn Y để đặt root password và nhập lại password hai lần. Không ghi password thật vào bài, log hoặc Git.
Chọn Y để xóa anonymous users.
Chọn Y để không cho phép root login từ xa.
Chọn Y để xóa test database.
Chọn Y để reload privilege tables.
Đăng nhập MariaDB:

1
mysql -u root -p

Nhập root password vừa đặt.
Tạo database và user riêng cho BookStack. Thay [DB_PASSWORD] bằng password được lưu ở secret manager hoặc file ngoài repository:

1
2
3
4
CREATE DATABASE bookstack;
GRANT ALL ON bookstack.* TO 'bookstack_rw'@'localhost' IDENTIFIED BY '[DB_PASSWORD]';
FLUSH PRIVILEGES;
EXIT;

Thoát shell nếu vẫn còn ở trong đó:

1
exit

Tải BookStack và tạo file môi trường

Clone branch release vào /var/www/bookstack:

1
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch /var/www/bookstack

Copy file môi trường mẫu:

1
sudo cp /var/www/bookstack/.env.example /var/www/bookstack/.env

Mở file cấu hình:

1
sudo nano /var/www/bookstack/.env

Điều chỉnh các biến chính sau. Không dùng nguyên giá trị mẫu cho password, mail host hoặc app key:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
APP_ENV=production
APP_DEBUG=false
APP_KEY=
APP_URL=http://DNSorIP/bookstack
APP_TIMEZONE=Asia/Ho_Chi_Minh
APP_LOCALE=vi

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=bookstack
DB_USERNAME=bookstack_rw
DB_PASSWORD=[DB_PASSWORD]

MAIL_DRIVER=smtp
MAIL_HOST=[SMTP_HOST]
MAIL_PORT=25
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDR=bookstack@[YOUR_DOMAIN]
MAIL_FROM_NAME='BookStack'
MAIL_REPLYTO_ADDR=bookstack@[YOUR_DOMAIN]
MAIL_REPLYTO_NAME='BookStack'
MAIL_AUTO_EMBED_METHOD='attachment'

Đặt APP_URL đúng URL thật. Nếu dùng domain HTTPS, hãy dùng https:// thay vì HTTP.
Nhấn Ctrl+O, Enter, rồi Ctrl+X để lưu và đóng nano.

Cài dependency và tạo app key

Đặt owner cho thư mục BookStack:

1
sudo chown -R www-data:www-data /var/www/bookstack

Tạo Composer working directory và cấp quyền:

1
2
sudo mkdir /var/www/.composer
sudo chown -R www-data:www-data /var/www/.composer

Chuyển vào thư mục BookStack:

1
cd /var/www/bookstack

Cài dependency production:

1
sudo -u www-data composer install --no-dev --no-plugins

Tạo app key bằng Artisan, không tự chép key vào repository:

1
sudo php artisan key:generate --no-interaction --force

Chạy migration:

1
sudo php artisan migrate --no-interaction --force

Mở file Apache site configuration:

1
sudo nano /etc/apache2/sites-available/bookstack.conf

Thêm cấu hình sau, điều chỉnh path/domain nếu triển khai khác /bookstack:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Alias /bookstack "/var/www/bookstack/public"
<Directory /var/www/bookstack/public>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted

    <IfModule mod_rewrite.c>
        <IfModule mod_negotiation.c>
            Options -MultiViews -Indexes
        </IfModule>

        RewriteEngine On

        RewriteCond %{HTTP:Authorization} .
        RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_URI} (.+)/$
        RewriteRule ^ %1 [L,R=301]

        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^ index.php [L]
    </IfModule>
</Directory>

Nhấn Ctrl+O, Enter, Ctrl+X để lưu file.
Bật rewrite module, enable site và restart Apache:

1
2
3
sudo a2enmod rewrite
sudo a2ensite bookstack
sudo systemctl restart apache2

Hoàn tất trên Web Installer

Mở http://DNSorIP/bookstack.
Đăng nhập lần đầu bằng thông tin mặc định của phiên bản BookStack đang cài chỉ khi tài liệu chính thức xác nhận; đổi ngay sang tài khoản/password riêng, không đưa credential mặc định vào bài.
Mở user dropdown góc phải, chọn My Account.
Cập nhật username và email, rồi bấm Save.
Chọn Access & Security ở navigation bên trái.
Nhập và xác nhận password mới, bấm Update.
Mở user dropdown và chọn Logout.
Đăng nhập lại bằng email/password mới.
Kiểm tra BookStack đã đọc được database, ghi được file upload và mở được trang wiki.

Lưu ý vận hành: Bật HTTPS, backup database cùng thư mục /var/www/bookstack, khóa quyền .env, không cho MariaDB root login từ xa và kiểm tra compatibility trước khi cập nhật branch release.

Nguồn và video

Tutorial gốc: i12bretro 0919
Video gốc: Install BookStack on Linux
BookStack manual installation: bookstackapp.com/docs/admin/installation
Repository: BookStackApp/BookStack

AIoT.IO.VN