v21.08.3 to v21.12
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$