pressbooks / local-dev-environment

This repository uses Lando/Docker to provision a local instance of Pressbooks for testing and development by open source contributors.

Pressbooks

Contributors: Pressbooks [email protected] Tags: ebooks, publishing, webbooks Requires at least: 6.5.0 Tested up to: 6.5.0 Stable tag: 6.18.1 Requires PHP: 8.1 License: GPL v3.0 or later License URI: https://github.com/pressbooks/pressbooks/blob/production/LICENSE.md

Pressbooks is an open source book publishing tool built on a WordPress multisite platform.

Description

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS. Pressbooks is free software, released under the GPL v3.0 or later license.

Our webbooks and EPUB/PDF exports are all driven by HTML + CSS. XML outputs have no styling.

Requirements

Pressbooks works with PHP 8.1 and WordPress 6.5.0. Lower versions are not supported.

Installing the Plugin

Pressbooks is not for use on an existing blog. Instead it should be used with a fresh, multisite WordPress installation.

To install Pressbooks on your site, download the latest release and follow our installation instructions.

You may want to try Pressbooks.com before deciding whether or not you wish to host and maintain your own instance of Pressbooks. We can also host and maintain an instance of Pressbooks for you.

Contributor guidelines

Developers who are interested in contributing to our project should consult our "Contributing" guidelines and the developer guides published on our documentation website.

Disclaimers

The Pressbooks plugin is supplied "as is" and all use is at your own risk.

Changelog

6.18.1

• See: https://github.com/pressbooks/pressbooks/releases/tag/6.18.1
• Full release history available at: https://github.com/pressbooks/pressbooks/releases

Upgrade Notices

6.18.0

• Pressbooks 6.18.0 requires WordPress 6.5.0

6.17.0

• Pressbooks 6.17.0 requires WordPress 6.4.3

6.15.2

• Pressbooks 6.15.2 requires WordPress 6.4.2

6.15.1

• Pressbooks 6.15.1 requires WordPress 6.3.1

6.12.0

• Pressbooks 6.12.0 requires WordPress 6.2.2

6.10.0

• Pressbooks 6.10.0 requires WordPress 6.2

6.9.0

• Pressbooks 6.9.0 requires PHP >= 8.1

6.4.0

• Pressbooks 6.4.0 requires PHP >= 8.0
• Pressbooks 6.4.0 requires WordPress 6.1.1

6.0.0

• Pressbooks 6.0.0 requires WordPress 6.0.2

5.34.1

• Pressbooks 5.34.1 requires WordPress 5.9.3
• Pressbooks 5.34.1 requires McLuhan >= 2.18.1

5.34.0

• Pressbooks 5.34.0 requires McLuhan >= 2.18.0
• Pressbooks 5.34.0 requires PHP >= 7.4

5.33.0

• Pressbooks 5.33.0 requires McLuhan >= 2.17.0

5.32.0

• Pressbooks 5.32.0 requires WordPress 5.9
• Pressbooks 5.32.0 requires McLuhan >= 2.16.0

5.31.0

• Pressbooks 5.31.0 requires McLuhan >= 2.15.0

5.30.0

• Pressbooks 5.30.0 requires WordPress 5.8.2
• Pressbooks 5.30.0 requires McLuhan >= 2.14.0

5.27.0

• Pressbooks 5.27.0 requires WordPress 5.8.1
• Pressbooks 5.27.0 requires McLuhan >= 2.13.0

5.25.0

• Pressbooks 5.25.0 requires WordPress 5.8

5.21.0

• Pressbooks 5.21.0 requires WordPress 5.7.2

5.20.1

• Pressbooks 5.20.1 requires WordPress 5.6.2

5.18.0

• Pressbooks 5.18.0 requires PHP >= 7.3
• Pressbooks 5.18.0 requires WordPress 5.5.3

5.16.0

• If you are using the plugin (Lord of the Files)[https://wordpress.org/plugins/blob-mimes/] version <=1.0.0, this upgrade will break your application. To fix this, you would need to update Lord of the files plugin to at least 1.1.0.

5.15.1

• Pressbooks 5.15.1 requires PHP >= 7.1.
• Pressbooks 5.15.1 requires WordPress 5.4
• Pressbooks 5.15.1 requires McLuhan >= 2.10.2

local-dev-environment's Issues

Issues encountered during fresh install on MacOS

I worked with Michelle to try to install Pressbooks locally using these instructions on her Apple M1 Pro running Sonoma 14.2.1 (23C71). Here are the issues we encountered:

SSH problems

No local SSH key and No SSH key in GitHub.

Resolved by creating SSH key locally: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent and adding it to GitHub: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account. See also this helpful video tutorial: https://youtu.be/8X4u9sca3Io?si=rdL3chT5ZPXEGPyO

cp: cannot stat '/user/.ssh/config': No such file or directory error when running lando start

This is because we try to run cp /user/.ssh/config ~/.ssh:

local-dev-environment/.lando.yml

Lines 33 to 34 in 8eb7536

	run:
	- cp /user/.ssh/config ~/.ssh

An open source developer who also got this message wrote:

I have SSH keys, of course 🙂, and the public ones are on github. I don't know in what context cp /user/.ssh/config ~/.ssh should be run, but I couldn't make sense of it (unless one has a global config for all users, but that should not overwrite the local users config). Should this copy the user's local SSH configuration into the lando context, so it can pull from github?

I think the recommended Lando method is described here: https://docs.lando.dev/core/v3/ssh.html#using-a-custom-ssh-config-file

Couldn't successfully run lando composer-login.

When running the command, we saw You should configure your credentials on config_services/.env message (because the composer.sh script doesn't find the expected PACKAGIST_USER env variable):

local-dev-environment/scripts/composer.sh

Line 2 in 8eb7536

if [ "$PACKAGIST_USER" ]; then

Repeated prompting for authorization token when running composer lando install.

When Michelle attempted to run composer lando install without successfully running composer-login first, she was repeatedly prompted for a token. We resolved by adding packagist.com config to global composer configuration inside Lando. Went to packagist.com and then ran composer composer config --global --auth http-basic.repo.packagist.com MichelleWeremczuk TOKEN

For first time user, what configuration is needed to successfully run composer lando install? Answer is probably here? https://docs.lando.dev/php/config.html#installing-composer

Missing dependencies error message for Pressbooks Network Catalog after install.

Resolved by running lando ssh && cd web/app/plugins/pressbooks-network-catalog/ && composer install

We should figure out how to ensure that the dependencies for pressbooks-network-catalog are correctly installed upon initial build.

Pressbooks Network Catalog missing composer dependencies

@SteelWagstaff — I saw your earlier issue comment about how composer install needs to be run for Pressbooks Network Catalog. I'm not sure why this is; it shouldn't be a requirement as all dependencies should be installed via Bedrock. I'd be interested in looking into this further if it would be helpful.

[Bug] - Fatal error: Uncaught Error: Class "Illuminate\Database\Capsule\Manager" not found

From one Open Source user:

Hi Steel!

Hope you're well. It was quite a bumpy start, but meanwhile I am working on the H5P rendering which BCCampus would like to see in Pressbooks. I have created a package and hooked it up to some minimal web frontend for demonstration purposes (https://snordian.de/bccampus-poc/)

I'd now want to use this package in Pressbooks, but I cannot get my local copy running despite having run just fine before. Unfortunately, since I myself don't have a paid Slack account, I lost access to your Slack channel after 90 days and now can't ask you there. Hopefully, this is a small issue that you could help me via email as well.

I am running the latest version of lando and pulled the latest version of the pressbooks repository.

When I now fire up 'lando start', then the tests that it runs fail. The local server that is set up seems to have an issue. The tests fails with a 500 HTTP error, and when I open the local start page to check, I am greeted with

Fatal error: Uncaught Error: Class "Illuminate\Database\Capsule\Manager" not found in /app/web/app/plugins/pressbooks/inc/class-serviceprovider.php:88 Stack trace: #0 /app/web/app/plugins/pressbooks/hooks.php(35): Pressbooks\ServiceProvider::init() #1 /app/web/app/plugins/pressbooks/pressbooks.php(114): require('/app/web/app/pl...') #2 /app/web/wp/wp-settings.php(462): include_once('/app/web/app/pl...') #3 /app/web/wp-config.php(9): require_once('/app/web/wp/wp-...') #4 /app/web/wp/wp-load.php(55): require_once('/app/web/wp-con...') #5 /app/web/wp/wp-blog-header.php(13): require_once('/app/web/wp/wp-...') #6 /app/web/index.php(5): require('/app/web/wp/wp-...') #7 {main} thrown in /app/web/app/plugins/pressbooks/inc/class-serviceprovider.php on line 88

Trying lando composer update or lando composer install yields

Fatal error: Uncaught Error: Class "Seld\Signal\SignalHandler" not found in /app/vendor/composer/composer/src/Composer/Console/Application.php:109
Stack trace:
#0 /app/vendor/composer/composer/bin/composer(93): Composer\Console\Application->__construct()
#1 /app/vendor/bin/composer(119): include('/app/vendor/com...')
#2 {main}
thrown in /app/vendor/composer/composer/src/Composer/Console/Application.php on line 109

To me as a PHP tool chain novice, this looks like something is missing that should be installed, but I cannot pinpoint this.

If you have any idea, please let me know. Otherwise I'll just give a clean install another shot.

Best,
Oliver