Updating BookStack
Updating proccess for BookStack.
v21.05.4 to v21.08.3
Version v21.08 brought some important security updates and added a nice feature – 2FA. That is enough to justify upgrading to the new version.
Before proceeding, make sure you have a proper backup of your BookStack instance. If you don't, follow the guide here.
Prerequisites
Web services usually store files in the /var/www
directory, in this case BookStack is in /var/www/BookStack
. Depending on your permissions configuration, the following steps might differ.
- If the owner of all files in the directory is
www-data
, you should run the update commands aswww-data
. - In case you have a separate user that owns the directory, execute the commands as this user.
Become www-data
(or another user) with sudo su
.
$ sudo su www-data
You will most likely run into this error:
This account is currently not available.
Service accounts that web apps use to run (like www-data
) do not usually have access to the shell. It should be that way. Unfortunately this means, you won't be able to run any commands under them with sudo su
, because they can't use shell. There are two way to get around this:
- Temporarily editing
/etc/passwd
and adding shell to www-data - Temporarily adding /bin/bash to www-data in the current shell
I will do the latter option because it's quicker. Use sudo
with -s
option to add /bin/bash
to www-data
$ sudo su www-data -s /bin/bash
This will open shell under www-data
so you can perform the management actions you want without messing up file ownerships.
www-data@hostname:~/
Download using git
Make sure you are in the correct directory (root of BookStack) /var/www/BookStack
with pwd
:
(www-data)$ pwd
/var/www/BookStack
Updates of BookStack are done using git
. Pull the latest version with this command:
(www-data)$ git pull origin release
Output should look something like this:
remote: Enumerating objects: 2228, done.
remote: Counting objects: 100% (1129/1129), done.
remote: Total 2228 (delta 1129), reused 1129 (delta 1129), pack-reused 1099
Receiving objects: 100% (2228/2228), 982.79 KiB | 883.00 KiB/s, done.
Resolving deltas: 100% (1740/1740), completed with 501 local objects.
From https://github.com/BookStackApp/BookStack
* branch release -> FETCH_HEAD
926abbe7..fa855383 release -> origin/release
Updating 926abbe7..fa855383
Fast-forward
.env.example.complete | 6 +
.github/translators.txt | 19 ++
app/Actions/Activity.php | 10 +-
app/Actions/ActivityService.php | 19 +-
app/Actions/ActivityType.php | 7 +-
app/Actions/Comment.php | 8 +-
app/Actions/CommentRepo.php | 19 +-
app/Actions/Favourite.php | 4 +-
app/Actions/Tag.php | 10 +-
app/Actions/TagRepo.php | 10 +-
app/Actions/View.php | 5 +-
app/Api/ApiDocsGenerator.php | 26 +-
app/Api/ApiToken.php | 13 +-
app/Api/ApiTokenGuard.php | 27 +-
app/Api/ListingResponseBuilder.php | 11 +-
app/Application.php | 6 +-
app/Auth/Access/EmailConfirmationService.php | 9 +-
app/Auth/Access/ExternalAuthService.php | 9 +-
app/Auth/Access/ExternalBaseUserProvider.php | 30 +-
app/Auth/Access/Guards/ExternalBaseSessionGuard.php | 47 +--
app/Auth/Access/Guards/LdapSessionGuard.php | 28 +-
app/Auth/Access/Guards/Saml2SessionGuard.php | 6 +-
app/Auth/Access/Ldap.php | 34 +-
app/Auth/Access/LdapService.php | 34 +-
app/Auth/Access/LoginService.php | 164 +++++++++
app/Auth/Access/Mfa/BackupCodeService.php | 62 ++++
app/Auth/Access/Mfa/MfaSession.php | 60 ++++
app/Auth/Access/Mfa/MfaValue.php | 76 +++++
app/Auth/Access/Mfa/TotpService.php | 72 ++++
app/Auth/Access/Mfa/TotpValidationRule.php | 37 ++
app/Auth/Access/RegistrationService.php | 13 +-
app/Auth/Access/Saml2Service.php | 67 ++--
app/Auth/Access/SocialAuthService.php | 48 ++-
app/Auth/Access/UserInviteService.php | 5 +-
app/Auth/Access/UserTokenService.php | 62 ++--
app/Auth/Permissions/EntityPermission.php | 6 +-
app/Auth/Permissions/JointPermission.php | 4 +-
app/Auth/Permissions/PermissionService.php | 60 +++-
app/Auth/Permissions/PermissionsRepo.php | 11 +-
app/Auth/Permissions/RolePermission.php | 6 +-
...
...
...
rename resources/views/books/{ => parts}/list-item.blade.php (100%)
rename resources/views/books/{ => parts}/list.blade.php (84%)
rename resources/views/books/{ => parts}/sort-box.blade.php (100%)
rename resources/views/chapters/{ => parts}/child-menu.blade.php (81%)
rename resources/views/chapters/{ => parts}/form.blade.php (92%)
rename resources/views/chapters/{ => parts}/list-item.blade.php (92%)
rename resources/views/{partials => common}/activity-item.blade.php (100%)
rename resources/views/{partials => common}/activity-list.blade.php (76%)
rename resources/views/{partials => common}/custom-head.blade.php (55%)
rename resources/views/{partials => common}/custom-styles.blade.php (100%)
rename resources/views/{partials => common}/dark-mode-toggle.blade.php (100%)
create mode 100644 resources/views/common/export-custom-head.blade.php
rename resources/views/{partials => common}/export-styles.blade.php (100%)
rename resources/views/{partials => common}/loading-icon.blade.php (100%)
...
Install with Composer
(www-data)$ composer install --no-dev
This will install or update required PHP dependencies in production mode (without dev dependencies) and produce similar output:
> @php -r "!file_exists('bootstrap/cache/services.php') || @unlink('bootstrap/cache/services.php');"
Installing dependencies from lock file
Verifying lock file contents can be installed on current platform.
Package operations: 5 installs, 21 updates, 0 removals
- Downloading dasprid/enum (1.0.3)
- Downloading bacon/bacon-qr-code (2.0.4)
- Downloading phpoption/phpoption (1.8.0)
...
- Upgrading aws/aws-sdk-php (3.187.2 => 3.191.8): Extracting archive
- Installing league/html-to-markdown (5.0.0): Extracting archive
- Installing paragonie/constant_time_encoding (v2.4.0): Extracting archive
- Installing pragmarx/google2fa (8.0.0): Extracting archive
Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover --ansi
Discovered Package: barryvdh/laravel-dompdf
Discovered Package: nunomaduro/collision
Discovered Package: socialiteproviders/manager
Package manifest generated successfully.
52 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
> @php artisan cache:clear
Application cache cleared!
> @php artisan view:clear
Compiled views cleared!
Update database with php artisan
Run php artisan
to update the database and make any required changes.
(www-data)$ php artisan migrate
Output (type in yes):
**************************************
* Application In Production! *
**************************************
Do you really wish to run this command? (yes/no) [no]:
> yes
Migrating: 2021_06_30_173111_create_mfa_values_table
Migrated: 2021_06_30_173111_create_mfa_values_table (0.03 seconds)
Migrating: 2021_07_03_085038_add_mfa_enforced_to_roles_table
Migrated: 2021_07_03_085038_add_mfa_enforced_to_roles_table (0 seconds)
Migrating: 2021_08_28_161743_add_export_role_permission
Migrated: 2021_08_28_161743_add_export_role_permission (0.01 seconds)
You could also just run the previous commands in one line with this git pull origin release && composer install --no-dev && php artisan migrate
Clear cache
It is also recommended to clean the cache:
(www-data)$ php artisan cache:clear
(www-data)$ php artisan config:clear
(www-data)$ php artisan view:clear
Exit the www-data shell
After you are done, exit the shell
(www-data)$ exit
user$
v21.08.3 to v21.12
Version v21.12 brought some more serious security updates and a couple of nice features. Let's update :)
Before proceeding, make sure you have a proper backup of your BookStack instance. If you don't, follow the guide here.
Always check the official Updates page before proceeding. Once in a while, there are some specific instructions for updating from/to certain versions.
Prerequisites
Web services usually store files in the /var/www
directory, in this case BookStack is in /var/www/BookStack
. Depending on your permissions configuration, the following steps might differ.
- If the owner of all files in the directory is
www-data
, you should run the update commands aswww-data
. - In case you have a separate user that owns the directory, execute the commands as this user.
Become www-data
(or another user) with sudo su
.
$ sudo su www-data
You will most likely run into this error:
This account is currently not available.
Service accounts that web apps use to run (like www-data
) do not usually have access to the shell. It should be that way. Unfortunately this means, you won't be able to run any commands under them with sudo su
, because they can't use shell. There are two way to get around this:
- Temporarily editing
/etc/passwd
and adding shell to www-data - Temporarily adding /bin/bash to www-data in the current shell
I will do the latter option because it's quicker. Use sudo
with -s
option to add /bin/bash
to www-data
$ sudo su www-data -s /bin/bash
This will open shell under www-data
so you can perform the management actions you want without messing up file ownerships.
www-data@hostname:~/
Download using git
Make sure you are in the correct directory (root of BookStack) /var/www/BookStack
with pwd
:
(www-data)$ pwd
/var/www/BookStack
Updates of BookStack are done using git
. Pull the latest version with this command:
(www-data)$ git pull origin release
Output should look something like this:
hint: Pulling without specifying how to reconcile divergent branches is
hint: discouraged. You can squelch this message by running one of the following
hint: commands sometime before your next pull:
hint:
hint: git config pull.rebase false # merge (the default strategy)
hint: git config pull.rebase true # rebase
hint: git config pull.ff only # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
remote: Enumerating objects: 4106, done.
remote: Counting objects: 100% (2414/2414), done.
remote: Compressing objects: 100% (134/134), done.
remote: Total 4106 (delta 2280), reused 2405 (delta 2278), pack-reused 1692
Receiving objects: 100% (4106/4106), 1.82 MiB | 10.86 MiB/s, done.
Resolving deltas: 100% (3333/3333), completed with 554 local objects.
From https://github.com/BookStackApp/BookStack
* branch release -> FETCH_HEAD
fa855383..09436836 release -> origin/release
Updating fa855383..09436836
Fast-forward
.env.example | 2 +-
.env.example.complete | 32 +-
.github/ISSUE_TEMPLATE/api_request.md | 17 -
.github/ISSUE_TEMPLATE/api_request.yml | 26 +
.github/ISSUE_TEMPLATE/bug_report.md | 29 -
.github/ISSUE_TEMPLATE/bug_report.yml | 62 +
.github/ISSUE_TEMPLATE/feature_request.md | 14 -
.github/ISSUE_TEMPLATE/feature_request.yml | 26 +
.github/ISSUE_TEMPLATE/language_request.md | 13 -
.github/ISSUE_TEMPLATE/language_request.yml | 32 +
.github/ISSUE_TEMPLATE/support_request.yml | 63 +
.github/SECURITY.md | 32 +
.github/translators.txt | 24 +-
.github/workflows/phpstan.yml | 41 +
.github/workflows/phpunit.yml | 8 +-
.github/workflows/test-migrations.yml | 6 +-
.gitignore | 3 +-
LICENSE | 2 +-
app/Actions/Activity.php | 2 +-
app/Actions/ActivityLogger.php | 115 +
app/Actions/ActivityQueries.php | 112 +
app/Actions/ActivityService.php | 197 --
app/Actions/ActivityType.php | 12 +
app/Actions/Comment.php | 11 +-
app/Actions/CommentRepo.php | 11 +-
app/Actions/DispatchWebhookJob.php | 112 +
app/Actions/Tag.php | 9 +
app/Actions/TagRepo.php | 55 +-
app/Actions/Webhook.php | 75 +
app/Actions/WebhookTrackedEvent.php | 18 +
app/Api/ApiDocsGenerator.php | 21 +-
app/Api/ApiToken.php | 2 +-
app/Api/ApiTokenGuard.php | 4 +-
app/Auth/Access/ExternalBaseUserProvider.php | 19 +-
app/Auth/Access/{ExternalAuthService.php => GroupSyncService.php} | 6 +-
.../Guards/{Saml2SessionGuard.php => AsyncExternalBaseSessionGuard.php} | 2 +-
app/Auth/Access/Guards/LdapSessionGuard.php | 2 +-
app/Auth/Access/Ldap.php | 19 +-
app/Auth/Access/LdapService.php | 17 +-
app/Auth/Access/LoginService.php | 2 +-
...
This time, I got a git hint at the beginning, which I will ignore for now and may come back to it in a separatate article later.
Install with Composer
(www-data)$ composer install --no-dev
This will install or update required PHP dependencies in production mode (without dev dependencies) and produce similar output:
> @php -r "!file_exists('bootstrap/cache/services.php') || @unlink('bootstrap/cache/services.php');"
Installing dependencies from lock file
Verifying lock file contents can be installed on current platform.
Package operations: 20 installs, 42 updates, 10 removals
- Downloading composer/package-versions-deprecated (1.11.99.4)
- Downloading aws/aws-crt-php (v1.0.2)
- Downloading voku/portable-ascii (1.5.6)
- Downloading phpoption/phpoption (1.8.1)
- Downloading graham-campbell/result-type (v1.0.4)
- Downloading vlucas/phpdotenv (v5.4.1)
- Downloading symfony/css-selector (v5.4.0)
- Downloading tijsverkoyen/css-to-inline-styles (2.2.4)
- Downloading symfony/var-dumper (v5.4.1)
- Downloading symfony/deprecation-contracts (v2.5.0)
- Downloading symfony/routing (v5.4.0)
- Downloading symfony/process (v5.4.0)
- Downloading symfony/mime (v5.4.0)
- Downloading symfony/http-foundati
Update database with php artisan
Run php artisan
to update the database and make any required changes.
(www-data)$ php artisan migrate
Output (type in yes):
**************************************
* Application In Production! *
**************************************
Do you really wish to run this command? (yes/no) [no]:
> yes
Migrating: 2021_06_30_173111_create_mfa_values_table
Migrated: 2021_06_30_173111_create_mfa_values_table (0.03 seconds)
Migrating: 2021_07_03_085038_add_mfa_enforced_to_roles_table
Migrated: 2021_07_03_085038_add_mfa_enforced_to_roles_table (0 seconds)
Migrating: 2021_08_28_161743_add_export_role_permission
Migrated: 2021_08_28_161743_add_export_role_permission (0.01 seconds)
You could also just run the previous commands in one line with this git pull origin release && composer install --no-dev && php artisan migrate
Search Index Update
According to the official Updates page, there have been some changes regarding search indexing and it is recommended to run
(www-data)$ php artisan bookstack:regenerate-search
to take advantage of these new changes.
Search Index Changes - Changes to search indexing and scoring were made in this release. It’s recommended to run php artisan bookstack:regenerate-search to ensure a consistent search experience and take advantage of these changes.
Clear cache
It is also recommended to clean the cache:
(www-data)$ php artisan cache:clear
(www-data)$ php artisan config:clear
(www-data)$ php artisan view:clear
Exit the www-data shell
After you are done, exit the shell
(www-data)$ exit
user$