v21.08.3 to v21.12
Version v21.0812 brought some importantmore serious security updates and addeda acouple of nice featurefeatures. –Let's 2FA.update 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.
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: 2228,4106, done.
remote: Counting objects: 100% (1129/1129)2414/2414), done.
remote: Compressing objects: 100% (134/134), done.
remote: Total 22284106 (delta 1129)2280), reused 11292405 (delta 1129)2278), pack-reused 10991692
Receiving objects: 100% (2228/2228)4106/4106), 982.791.82 KiBMiB | 883.0010.86 KiB/MiB/s, done.
Resolving deltas: 100% (1740/1740)3333/3333), completed with 501554 local objects.
From https://github.com/BookStackApp/BookStack
* branch release -> FETCH_HEAD
926abbe7.fa855383..fa85538309436836 release -> origin/release
Updating 926abbe7.fa855383..fa85538309436836
Fast-forward
.env.example | 2 +-
.env.example.complete | 632 +-
.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 | 1924 +-
.github/workflows/phpstan.yml | 41 +
.github/workflows/phpunit.yml | 8 +-
.github/workflows/test-migrations.yml | 6 +-
.gitignore | 3 +-
LICENSE | 2 +-
app/Actions/Activity.php | 102 +-
app/Actions/ActivityLogger.php | 115 +
app/Actions/ActivityQueries.php | 112 +
app/Actions/ActivityService.php | 19197 +--
app/Actions/ActivityType.php | 712 +-
app/Actions/Comment.php | 811 +-
app/Actions/CommentRepo.php | 1911 +-
app/Actions/Favourite.DispatchWebhookJob.php | 4112 +-
app/Actions/Tag.php | 109 +-
app/Actions/TagRepo.php | 1055 +-
app/Actions/View.Webhook.php | 575 +-
app/Actions/WebhookTrackedEvent.php | 18 +
app/Api/ApiDocsGenerator.php | 2621 +-
app/Api/ApiToken.php | 132 +-
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 | 94 +-
app/Auth/Access/ExternalBaseUserProvider.php | 3019 +-
app/Auth/Access/Guards/ExternalBaseSessionGuard.{ExternalAuthService.php => GroupSyncService.php} | 476 +-
.../Guards/{Saml2SessionGuard.php => AsyncExternalBaseSessionGuard.php} | 2 +-
app/Auth/Access/Guards/LdapSessionGuard.php | 28 +-
app/Auth/Access/Guards/Saml2SessionGuard.php | 62 +-
app/Auth/Access/Ldap.php | 3419 +-
app/Auth/Access/LdapService.php | 3417 +-
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 | 62 +-
...
...
...
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%)
...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: 520 installs, 2142 updates, 010 removals
- Downloading dasprid/enumcomposer/package-versions-deprecated (1.0.3)11.99.4)
- Downloading bacon/bacon-qr-codeaws/aws-crt-php (2.v1.0.4)2)
- Downloading voku/portable-ascii (1.5.6)
- Downloading phpoption/phpoption (1.8.0)
...1)
- UpgradingDownloading aws/aws-sdk-phpgraham-campbell/result-type (3.187.2 => 3.191.8): Extracting archivev1.0.4)
- InstallingDownloading league/html-to-markdownvlucas/phpdotenv (5.0.0): Extracting archivev5.4.1)
- InstallingDownloading paragonie/constant_time_encodingsymfony/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.4.5.0): Extracting archive
- InstallingDownloading pragmarx/google2fasymfony/routing (8.0.v5.4.0): Extracting archive
Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover
- Downloading symfony/process (v5.4.0)
-ansi DiscoveredDownloading Package:symfony/mime barryvdh/laravel-dompdf(v5.4.0)
Discovered- Package:Downloading 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!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$