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-dataYou 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/passwdand 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/bashThis 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/BookStackUpdates 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-devThis 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 migrateOutput (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:clearExit 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-dataYou 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/passwdand 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/bashThis 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/BookStackUpdates 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-devThis 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-foundatiUpdate database with php artisan
Run php artisan to update the database and make any required changes.
(www-data)$ php artisan migrateOutput (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-searchto 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:clearExit the www-data shell
After you are done, exit the shell
(www-data)$ exit
user$