Testing Better Dependency Management
Dan Brown posted on the 17th of March 2025
Yesterday I released BookStack v25.02.1 which included a range of updates to the system CLI, one of which being a new command:
|
|
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, 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 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 within the project.
Providing Feedback
I welcome any feedback regarding this system on the GitHub issue here.
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.
Header Image Credits: Photo by Agnes Monkelbaan (CC-BY-SA-4) - Image Modified
_03.jpg){kind=link}