bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Added post about new download-vendor system CLI command

Browse source
This commit is contained in:
Dan Brown 2025-03-17 18:02:30 +00:00
commit f033a41cdb
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
4 changed files with 83 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

2
content/blog/2025/bookstack-in-2024.md
View file

@ -140,4 +140,4 @@ Tim, randi65535, Script, B1t5murf, ibanez450, root-node and thedoctor0814 are ex
---
<span style="font-size: 0.8em;opacity:0.8;">Header Image Credits: &nbsp;<span>Photo by <a href="https://commons.wikimedia.org/wiki/File:001_Wild_Golden_Eagle_and_Majinghorn_Pfyn-Finges_Photo_by_Giles_Laurent.jpg">Giles Laurent (CC-BY-4)</a> - Image Modified</span></span>
<span style="font-size: 0.8em;opacity:0.8;">Header Image Credits: &nbsp;<span>Photo by <a href="https://commons.wikimedia.org/wiki/File:001_Wild_Golden_Eagle_and_Majinghorn_Pfyn-Finges_Photo_by_Giles_Laurent.jpg">Giles Laurent (CC-BY-SA-4)</a> - Image Modified</span></span>

73
content/blog/2025/php-dependency-improvements.md Normal file
View file

@ -0,0 +1,73 @@
+++
categories = ["News"]
tags = ["News"]
title = "Testing Better Dependency Management"
image = "/images/blog-cover-images/cc-by-sa-4/mountain-stream-agnes-monkelbaan.jpg"
author = "Dan Brown"
slug = "php-dependency-improvements"
draft = false
date = 2025-03-17T18:00:00Z
+++
Yesterday I released [BookStack v25.02.1](https://github.com/BookStackApp/BookStack/releases/tag/v25.02.1)
which included a range of updates to [the system CLI](https://www.bookstackapp.com/docs/admin/system-cli/),
one of which being a new command:
```bash
./bookstack-system-cli download-vendor
```
This new command will download the required PHP dependency packages for a BookStack instance,
and is intended to replace the existing `composer install --no-dev` install & update
step with a more efficient system which relies on fewer external sources.
The existing `composer install --no-dev` command will continue to work, and will remain the default advised
approach until this new option has had greater testing.
*Note: If you don't run our standard install steps (For example, you run via a maintained docker image) then this
is not something you'd use yourself or need to worry about.*
### How This Works
As part of the BookStack release process the `vendor/` folder, which contains PHP dependencies,
is now compressed to a ZIP archive and then uploaded to our https://files.bookstackapp.com/vendor/
site, with the resulting ZIP file name matching the BookStack version.
A sha256 checksum is saved as part of the core code-base to a [`dev/checksums/vendor` file](https://github.com/BookStackApp/BookStack/blob/release/dev/checksums/vendor), which is committed as part of a release.
When running `./bookstack-system-cli download-vendor`, the CLI will look up to our https://files.bookstackapp.com/vendor/
site for the ZIP of version matching the BookStack instance, download that ZIP, then verify the file against
the checksum stored in the code-base. If this passes, the ZIP is extracted to `vendor/` in the target BookStack
instance, removing any existing `vendor/` directory first.
The process has been designed to be fairly simple, in a way that can easily be replicated via other means
outside of our CLI, while also ensuring a level of trust & security by performing the checksum
against a value provided via a different source to the downloaded file.
### Why This Has Been Introduced
There's a few reasons as to why this process has been implemented:
Firstly, it reduces requirements for a production environment.
Right now [composer](https://getcomposer.org/) is considered a BookStack requirement,
but this process can be used instead of composer in standard production use.
Secondly, it can be a lot more efficient than the existing `composer install --no-dev` step.
That existing method will download & extract multiple ZIP files, one for each dependency to install/update.
This new command/process packages up all dependencies for a BookStack version within a single ZIP to download & extract.
Thirdly, it reduces reliance on external services & platforms.
The existing process via composer will download files from GitHub (Microsoft) and Codeberg (and any other repository sources that might be used in future).
This new process only relies on a single host that's under the BookStack domain: https://files.bookstackapp.com.
This can be particularly helpful in environments where connections to external locations are strictly controlled, and also helps avoid issues that can occur with downloading from third-party sites like rate-limiting and access filtering.
This also works towards our wider goal of [reducing our reliance on GitHub](https://github.com/BookStackApp/BookStack/issues/4551) within the project.
### Providing Feedback
I welcome any feedback regarding this system [on the GitHub issue here](https://github.com/BookStackApp/BookStack/issues/5538).
Once we've had some feedback, and the system is proven stable & working, I'll look to update our docs, guidance and scripts
to use this new system by default instead of using composer.
---
<span style="font-size: 0.8em;opacity:0.8;">Header Image Credits: &nbsp;<span>Photo by <a href="https://commons.wikimedia.org/wiki/File:S-charl_richting_Alp_Sesvenna._12-10-2024._(actm.)_03.jpg">Agnes Monkelbaan (CC-BY-SA-4)</a> - Image Modified</span></span>

7
static/images/blog-cover-images/cc-by-sa-4/attribution.txt
View file

@ -36,4 +36,9 @@ Image modified in usage (Cropped, resized, sharpened).
eagle-giles-laurent.jpg
Copyright Giles Laurent
Source: https://commons.wikimedia.org/wiki/File:001_Wild_Golden_Eagle_and_Majinghorn_Pfyn-Finges_Photo_by_Giles_Laurent.jpg
Image modified in usage (Cropped, resized, sharpened).
Image modified in usage (Cropped, resized, sharpened).
---
mountain-stream-agnes-monkelbaan.jpg
Copyright Agnes Monkelbaan
Source: https://commons.wikimedia.org/wiki/File:S-charl_richting_Alp_Sesvenna._12-10-2024._(actm.)_03.jpg
Image modified in usage (Cropped, resized, sharpened).

BIN
static/images/blog-cover-images/cc-by-sa-4/mountain-stream-agnes-monkelbaan.jpg (Stored with Git LFS) Normal file
View file

Binary file not shown.