Cách cài đặt BookStack với Nginx trên Ubuntu 20.04

[theanh]

BookStack là một nền tảng tự lưu trữ, mã nguồn mở, dễ sử dụng để tổ chức và lưu trữ thông tin. Nó có thể được sử dụng cho nhiều mục đích như Wiki, trang web Tài liệu và ứng dụng ghi chú. Nó được xây dựng bằng cách sử dụng khung Laravel PHP và sử dụng MySQL để lưu trữ dữ liệu. Đối với mục đích chỉnh sửa, nó cung cấp cho bạn tùy chọn giữa việc sử dụng trình soạn thảo WYSIWYG hoặc Markdown. Nó hỗ trợ xác thực đa yếu tố và chế độ tối và đa ngôn ngữ.

Hướng dẫn này sẽ hướng dẫn bạn cách cài đặt BookStack trên máy chủ chạy Ubuntu 20.04.

Điều kiện tiên quyết​

1. Máy chủ chạy Ubuntu 20.04
2. Tên miền đủ điều kiện (FQDN) trỏ đến máy chủ.
3. Người dùng không phải root có quyền sudo.
4. Phiên bản PHP 7.3 trở lên.
5. MySQL>=5.6 và MariaDB>=10.0
6. Git và Composer.

Bước 1 - Cấu hình tường lửa​

Bước đầu tiên là cấu hình tường lửa. Ubuntu đi kèm với ufw (Uncomplicated Firewall) theo mặc định.

Kiểm tra xem tường lửa có đang chạy không.

$ sudo ufw status

Bạn sẽ nhận được kết quả sau.

Status: inactive

Cho phép cổng SSH để tường lửa không làm gián đoạn kết nối hiện tại khi bật nó.

$ sudo ufw allow OpenSSH

Cũng cho phép các cổng HTTP và HTTPS.

$ sudo ufw allow 80
$ sudo ufw allow 443

Bật Tường lửa

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Kiểm tra trạng thái của tường lửa một lần nữa.

$ sudo ufw status

Bạn sẽ thấy kết quả tương tự.

Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
80 ALLOW Anywhere
443 ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
80 (v6) ALLOW Anywhere (v6)
443 (v6) ALLOW Anywhere (v6)

Bước 2 - Cài đặt Git​

Bước đầu tiên là cài đặt Git. Bạn sẽ cần tải xuống và cập nhật BookStack. Chạy lệnh sau để cài đặt Git.

$ sudo apt install git

Xác minh cài đặt.

$ git --version

Bước 3 - Cài đặt PHP và tiện ích mở rộng​

Vì BookStack phụ thuộc vào PHP, bạn cần cài đặt PHP và tiện ích mở rộng của nó phần mở rộng.

Ubuntu đi kèm với phiên bản PHP đã lỗi thời. Đầu tiên, chúng ta cần thêm kho lưu trữ PHP của Ondrej.

$ sudo add-apt-repository ppa:ondrej/php

Tiếp theo, cài đặt PHP và các phần mở rộng của nó theo yêu cầu của BookStack.

$ sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql

Xác minh cài đặt.

$ php --version
PHP 7.4.25 (cli) (built: Oct 22 2021 12:34:33) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies with Zend OPcache v7.4.25, Copyright (c), by Zend Technologies

Bước 4 - Cài đặt và cấu hình MariaDB​

Ubuntu đi kèm với phiên bản MariaDB cũ hơn. Để cài đặt phiên bản mới nhất, hãy thêm kho lưu trữ MariaDB chính thức. Chạy các lệnh sau để thêm kho lưu trữ.

$ curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
$ sudo bash mariadb_repo_setup --mariadb-server-version=10.6

Chạy lệnh sau để cài đặt máy chủ MariaDB.

$ sudo apt install mariadb-server

Bảo mật MariaDB cài đặt.

$ sudo mysql_secure_installation

Bạn sẽ thấy nhiều lời nhắc khác nhau. Trả lời chúng như sau.

Enter current password for root (enter for none): Press Enter
Switch to unix_socket authentication [Y/n] Type y
Change the root password? [Y/n] Type n
Remove anonymous users? [Y/n] Type y
Disallow root login remotely? [Y/n] Type y
Remove test database and access to it? [Y/n] Type y
Reload privilege tables now? [Y/n] Type y

Kết nối với shell MariaDB bằng lệnh sau.

$ sudo mysql

Tạo cơ sở dữ liệu mới cho Bookstack.

$ create database bookstack;

Tạo người dùng cơ sở dữ liệu mới.

$ CREATE USER 'bookstackuser'@'localhost' identified by 'bookstackpassword';

Chọn mật khẩu mạnh.

Cấp quyền truy cập vào cơ sở dữ liệu cho người dùng.

$ grant CREATE,ALTER,SELECT,INSERT,UPDATE,DELETE on `bookstack`.* to 'bookstackuser'@'localhost';

Thoát khỏi shell MySQL.

$ exit

Bước 5 - Cài đặt Composer​

Composer là một công cụ quản lý phụ thuộc cho PHP và được yêu cầu bởi Laravel, nơi BookStack dựa trên.

Tải xuống tập lệnh cài đặt Composer.

$ curl -sS https://getcomposer.org/installer -o composer-setup.php

Chạy các lệnh sau để xác minh trình cài đặt.

$ HASH=`curl -sS https://composer.github.io/installer.sig`
$ echo $HASH
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Các lệnh trên sẽ lấy giá trị băm của trình cài đặt và khớp với tập lệnh bạn đã tải xuống. Bạn sẽ thấy đầu ra sau nếu trình cài đặt an toàn để chạy.

Installer verified

Cài đặt Composer.

$ sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Xác minh cài đặt bằng cách kiểm tra phiên bản.

$ composer --version
Composer version 2.1.9 2021-10-05 09:47:38

Bước 6 - Tải xuống và cài đặt BookStack​

Tạo thư mục gốc cho ứng dụng BookStack.

$ sudo mkdir -p /var/www/bookstack

Thay đổi quyền sở hữu của /var/www/bookstack thư mục đến người dùng hiện đang đăng nhập.

$ sudo chown -R $USER:$USER /var/www/bookstack

Sao chép nhánh phát hành của kho lưu trữ BookStack Github vào kho lưu trữ mới tạo thư mục.

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

Đừng bỏ lỡ dot ở cuối Lệnh clone. Nó đảm bảo rằng tất cả các tệp được tải xuống trong thư mục hiện tại thay vì tạo một tệp mới.

Chạy trình cài đặt Composer từ thư mục /var/www/bookstack.

$ composer install --no-dev

Sao chép .env.example tệp vào .env để lưu trữ các biến môi trường cho cài đặt.

$ cp .env.example .env

Mở tệp để chỉnh sửa.

$ sudo nano .env

Điền URL ứng dụng và thông tin chi tiết về cơ sở dữ liệu. Nếu bạn định sử dụng các tính năng email, hãy điền thông tin SMTP hoặc xóa chúng khỏi tệp.

APP_URL=https://example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=bookstackpassword

Lưu tệp bằng cách nhấn Ctrl + X và nhập Y khi được nhắc sau khi hoàn tất. Có rất nhiều cài đặt khác mà bạn có thể định cấu hình. Để biết thêm thông tin về chúng, hãy mở tệp .env.example.complete và sao chép những thông tin bạn cần vào tệp .env của bạn.

Tạo khóa ứng dụng duy nhất. Giá trị này được tự động điền vào tệp .env. Nhập yes để tiếp tục lệnh.

$ php artisan key:generate
**************************************
* Application In Production! *
************************************** Do you really wish to run this command? (yes/no) [no]: > yes
Application key set successfully.

Cập nhật Cơ sở dữ liệu.

$ php artisan migrate
**************************************
* Application In Production! *
************************************** Do you really wish to run this command? (yes/no) [no]: > yes
Migration table created successfully.
Migrating: 2014_10_12_000000_create_users_table
Migrated: 2014_10_12_000000_create_users_table (0.12 seconds)
.......

Bước 7 - Cài đặt Let's Encrypt SSL​

Để cài đặt chứng chỉ SSL bằng Let's Encrypt, chúng ta cần cài đặt công cụ Certbot.

Chúng ta sẽ sử dụng trình cài đặt gói Snapd cho việc đó. Hầu hết các máy chủ Ubuntu không được cung cấp kèm công cụ Snap. Để khắc phục điều đó, hãy cài đặt Snap.

$ sudo apt install snapd

Đảm bảo rằng phiên bản Snapd của bạn được cập nhật.

$ sudo snap install core
$ sudo snap refresh core

Cài đặt Certbot.

$ sudo snap install --classic certbot

Sử dụng lệnh sau để đảm bảo lệnh Certbot có thể chạy được bằng cách tạo liên kết tượng trưng đến /usr/bin thư mục.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Xác minh cài đặt.

$ certbot --version
certbot 1.20.0

Tạo chứng chỉ SSL.

$ sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m [emailprotected] -d example.com

Lệnh trên sẽ tải xuống chứng chỉ vào thư mục /etc/letsencrypt/live/etherpad.example.com trên máy chủ của bạn.

Tạo nhóm Diffie-Hellman chứng chỉ.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Tạo thư mục gốc web thử thách để tự động gia hạn Let's Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Tạo Cron Job để gia hạn SSL. Nó sẽ chạy hàng ngày để kiểm tra chứng chỉ và gia hạn nếu cần. Để thực hiện việc đó, trước tiên, hãy tạo tệp /etc/cron.daily/certbot-renew và mở tệp đó để chỉnh sửa.

$ sudo nano /etc/cron.daily/certbot-renew

Dán nội dung sau mã.

#!/bin/sh
certbot renew --cert-name bookstack.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Lưu tệp bằng cách nhấn Ctrl + X và nhập Y khi được nhắc.

Thay đổi quyền trên tệp tác vụ để làm cho tệp có thể thực thi được.

$ sudo chmod +x /etc/cron.daily/certbot-renew

Bước 8 - Cài đặt và Cấu hình Nginx​

Ubuntu đi kèm với phiên bản Nginx cũ hơn. Để cài đặt phiên bản mới nhất, bạn cần tải xuống kho lưu trữ Nginx chính thức.

Thêm kho lưu trữ cho phiên bản ổn định của Nginx.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \ | sudo tee /etc/apt/sources.list.d/nginx.list

Cài đặt Nginx.

$ sudo apt install nginx

Xác minh cài đặt.

$ nginx -v
nginx version: nginx/1.20.1

Kích hoạt dịch vụ Nginx.

$ sudo systemctl enable nginx

Cấu hình PHP-FPM​

Mở tệp /etc/php/7.4/fpm/pool.d/www.conf.

$ sudo nano /etc/php/7.4/fpm/pool.d/www.conf

Chúng ta cần đặt người dùng/nhóm Unix của các quy trình PHP thành nginx. Tìm các dòng user=www-data và group=www-data trong tệp và thay đổi chúng thành nginx.

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
; will be used.
user = nginx
group = nginx
...

Ngoài ra, hãy tìm các dòng listen.owner=www-data và listen.group=www-data trong tệp và thay đổi chúng thành nginx.

listen.owner = nginx
listen.group = nginx

Lưu tệp bằng cách nhấn Ctrl + X và nhập Y khi được nhắc.

Khởi động lại PHP-fpm quá trình.

$ sudo systemctl restart php7.4-fpm

Cấu hình Nginx​

Tạo và mở tệp /etc/nginx/conf.d/bookstack.conf cho chỉnh sửa.

$ sudo nano /etc/nginx/conf.d/bookstack.conf

Dán mã sau vào đó.

server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name bookstack.example.com; access_log /var/log/nginx/bookstack.access.log; error_log /var/log/nginx/bookstack.error.log; ssl_certificate /etc/letsencrypt/live/bookstack.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/bookstack.example.com/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem; ssl_session_timeout 5m; ssl_session_cache shared:MozSSL:10m; ssl_session_tickets off; ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384; ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1; ssl_stapling on; ssl_stapling_verify on; ssl_dhparam /etc/ssl/certs/dhparam.pem; root /var/www/bookstack/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_split_path_info ^(.+\.php)(/.+)$; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_pass unix:/run/php/php7.4-fpm.sock; }
}
# enforce HTTPS
server { listen 80; listen [::]:80; server_name bookstack.example.com; return 301 https://$host$request_uri;
}

Lưu tệp bằng cách nhấn Ctrl + X và nhập Y khi được nhắc sau khi hoàn tất.

Mở tệp /etc/nginx/nginx.conf để chỉnh sửa.

$ sudo nano /etc/nginx/nginx.conf

Thêm dòng sau vào trước dòng include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size 64;

Lưu tệp bằng cách nhấn Ctrl + X và nhập Y khi được nhắc. Xác thực Nginx một lần nữa.

Xác minh cú pháp tệp cấu hình Nginx.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Cuối cùng, khởi động dịch vụ Nginx để kích hoạt cấu hình mới.

$ sudo systemctl start nginx

Thay đổi quyền sở hữu thư mục thành người dùng nginx để máy chủ web có thể truy cập và ghi vào thư mục.

$ sudo chown -R nginx:nginx /var/www/bookstack

Bước 9 - Chạy BookStack​

Bookstack của bạn đã sẵn sàng để sử dụng. Mở URL https://bookstack.example.com trong trình duyệt của bạn và bạn sẽ nhận được trang đăng nhập.


data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%22750%22%20height=%22390%22%3E%3C/svg%3E


Đăng nhập bằng tài khoản quản trị viên mặc định [emailprotected] với mật khẩu là password. Mở Cài đặt >> Trang Người dùng và nhấp vào nút THÊM NGƯỜI DÙNG MỚI.


data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%22750%22%20height=%22358%22%3E%3C/svg%3E


Điền thông tin người dùng, đánh dấu vào ô Quản trị viên trong Vai trò người dùng và bỏ chọn Gửi email mời người dùng vì chúng tôi không thiết lập thông tin SMTP. Chọn mật khẩu mạnh. Nhấp vào Lưu khi hoàn tất.


data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%22730%22%20height=%22750%22%3E%3C/svg%3E


Tiếp theo, nhấp vào người dùng Quản trị viên mặc định và xóa người dùng bằng cách nhấp vào nút Xóa người dùng.


data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%22584%22%20height=%22750%22%3E%3C/svg%3E


Chuyển quyền sở hữu của người dùng Quản trị viên cho người dùng mới tạo của bạn bằng cách chọn người dùng đó từ menu thả xuống trước khi xóa. Nhấp vào Xác nhận để hoàn tất. Nếu bạn đã đăng nhập bằng người dùng đó, bạn sẽ tự động được đăng xuất. Bạn sẽ cần phải đăng nhập lại bằng người dùng mới tạo.


data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%22750%22%20height=%22315%22%3E%3C/svg%3E

Sao lưu và khôi phục BookStack​

Sao lưu BookStack​

Bạn cần sao lưu cơ sở dữ liệu và các tệp riêng biệt. Để sao lưu cơ sở dữ liệu, hãy sử dụng công cụ mysqldump.

$ sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql

Bạn cũng cần sao lưu các tệp và thư mục sau.

1. .env - tệp chứa cấu hình quan trọng.
2. public/uploads - thư mục chứa các tệp đã tải lên hình ảnh.
3. storage/uploads - thư mục chứa các tệp đính kèm trang đã tải lên.

Chạy lệnh sau để tạo tệp lưu trữ nén của các tệp và thư mục trên.

$ sudo tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads

Khôi phục BookStack​

Chạy lệnh sau để khôi phục cơ sở dữ liệu.

$ sudo mysql -u bookstack < bookstack.backup.sql

Nếu bạn đang khôi phục về phiên bản mới của BookStack, bạn sẽ phải chạy lệnh sudo php artisan migrate.

Để khôi phục các tệp nén đã tạo ở trên, hãy sử dụng lệnh sau lệnh.

$ sudo tar -xvzf bookstack-files-backup.tar.gz

Bạn cũng sẽ cần thay đổi quyền.

Cập nhật BookStack​

Trước khi cập nhật BookStack, hãy đảm bảo bạn sao lưu đúng cách bằng quy trình đã đề cập trước đó.

Để cập nhật BookStack, hãy kéo các tệp gốc từ kho lưu trữ Git của nó.

$ cd /var/www/bookstack
$ sudo git pull origin release

Chạy các lệnh sau để tiếp tục quá trình cài đặt.

$ sudo composer install --no-dev
$ sudo php artisan migrate

Bạn cũng sẽ cần chạy các lệnh sau để xóa bộ nhớ đệm.

$ sudo php artisan cache:clear
$ sudo php artisan config:clear
$ sudo php artisan view:clear

Kết luận​

Bài hướng dẫn cài đặt BookStack trên máy chủ Ubuntu 20.04 của chúng tôi đã kết thúc. Nếu bạn có bất kỳ câu hỏi nào, hãy đăng chúng trong phần bình luận bên dưới.