Tự host BookStack trên Linux

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

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

sudo apt update

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

sudo apt upgrade -y

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

sudo apt install git openssl curl wget zip composer -y

5. Cài Apache và MariaDB:

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

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

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

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

sudo mysql_secure_installation

2. Khi được hỏi đăng nhập root, nhấn Enter nếu hệ thống chưa có root password.
3. 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.
4. Chọn Y để xóa anonymous users.
5. Chọn Y để không cho phép root login từ xa.
6. Chọn Y để xóa test database.
7. Chọn Y để reload privilege tables.
8. Đăng nhập MariaDB:

mysql -u root -p

9. Nhập root password vừa đặt.
10. 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:

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

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

exit

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

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

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

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

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

3. Mở file cấu hình:

sudo nano /var/www/bookstack/.env

4. Đ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:

APP_ENV=productionAPP_DEBUG=falseAPP_KEY=APP_URL=http://DNSorIP/bookstackAPP_TIMEZONE=Asia/Ho_Chi_MinhAPP_LOCALE=viDB_CONNECTION=mysqlDB_HOST=127.0.0.1DB_DATABASE=bookstackDB_USERNAME=bookstack_rwDB_PASSWORD=[DB_PASSWORD]MAIL_DRIVER=smtpMAIL_HOST=[SMTP_HOST]MAIL_PORT=25MAIL_USERNAME=nullMAIL_PASSWORD=nullMAIL_ENCRYPTION=nullMAIL_FROM_ADDR=bookstack@[YOUR_DOMAIN]MAIL_FROM_NAME='BookStack'MAIL_REPLYTO_ADDR=bookstack@[YOUR_DOMAIN]MAIL_REPLYTO_NAME='BookStack'MAIL_AUTO_EMBED_METHOD='attachment'

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

Cài dependency và tạo app key

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

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

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

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

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

cd /var/www/bookstack

4. Cài dependency production:

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

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

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

6. Chạy migration:

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

7. Mở file Apache site configuration:

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

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

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>

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

sudo a2enmod rewritesudo a2ensite bookstacksudo systemctl restart apache2

Hoàn tất trên Web Installer

1. Mở http://DNSorIP/bookstack.
2. Đă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.
3. Mở user dropdown góc phải, chọn My Account.
4. Cập nhật username và email, rồi bấm Save.
5. Chọn Access & Security ở navigation bên trái.
6. Nhập và xác nhận password mới, bấm Update.
7. Mở user dropdown và chọn Logout.
8. Đăng nhập lại bằng email/password mới.
9. 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