WordPress with Bedrock¶
WordPress is an open source blogging platform written in PHP and distributed under the GPLv2 licence.
WordPress was released in 2003 by Matt Mullenweg and Mike Little as a fork of b2/cafelog. It is maintained by the WordPress foundation.
Bedrock is a Wordpress-Boilerplate with an improved folder structure, easier configuration options and development. Dependencies like themes or plugins are managed with Composer. Since Bedrock separates the non-web files from the document root, it is also more secure.
It is maintained by roots.io and released and distributed under MIT Licence.
Note
For this guide you should be familiar with the basic concepts of
Prerequisites¶
We’re using PHP in the stable version 8.3:
[isabell@stardust ~]$ uberspace tools version use php 8.2
Selected PHP version 8.2
The new configuration is adapted immediately. Patch updates will be applied automatically.
[isabell@stardust ~]$
You’ll need your MySQL credentials. Get them with my_print_defaults
:
[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$
We suggest using an additional database. Create one with:
[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_wp"
Your blog domain needs to be setup:
[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$
Installation¶
cd
to the path above your document root and download bedrock with composer
:
[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ composer create-project roots/bedrock
Creating a "roots/bedrock" project at "./bedrock"
Installing roots/bedrock (1.23.1)
- Downloading roots/bedrock (1.23.1)
- Installing roots/bedrock (1.23.1): Extracting archive
Created project in /var/www/virtual/eatest/bedrock
Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Package operations: 18 installs, 0 updates, 0 removals
[...]
Generating optimized autoload files
No security vulnerability advisories found.
[isabell@stardust isabell]$
Configuration¶
Wordpress-Configuration is done using .env-Files. Copy the example and edit it with your favourite editor.
[isabell@stardust ~]$ cd /var/www/virtual/$USER/bedrock
[isabell@stardust bedrock]$ cp .env.example .env
[isabell@stardust isabell]$
In here you need to enter your MySQL credentials database connection parameters and the name of your database (e.g. isabell_wp
).
DB_NAME='isabell_wp'
DB_USER='isabell'
DB_PASSWORD='MySuperSecretPassword'
# Optionally, you can use a data source name (DSN)
# When using a DSN, you can remove the DB_NAME, DB_USER, DB_PASSWORD, and DB_HO$
# DATABASE_URL='mysql://database_user:database_password@database_host:database_$
# Optional variables
# DB_HOST='localhost'
# DB_PREFIX='wp_'
WP_ENV='development'
WP_HOME='https://isabell.uber.space'
WP_SITEURL="${WP_HOME}/wp"
# Generate your keys here: https://roots.io/salts.html
AUTH_KEY='generateme'
SECURE_AUTH_KEY='generateme'
LOGGED_IN_KEY='generateme'
NONCE_KEY='generateme'
AUTH_SALT='generateme'
SECURE_AUTH_SALT='generateme'
LOGGED_IN_SALT='generateme'
NONCE_SALT='generateme'
You can use Roots’ Salt-Creator to generate the Salts.
Note
You can leave the WP_ENV
Setting on development
for now, but don’t forget to set it on production
when launching your site.
See the Bedrock-Documentation for more Info on Environment-Settings
You now need to set your document root to the bedrock/web/
directory. To do this, we delete the standard document root folder and create a symlink instead.
[isabell@stardust ~]$ rm -f /var/www/virtual/$USER/html/nocontent.html
[isabell@stardust ~]$ rmdir /var/www/virtual/$USER/html
[isabell@stardust ~]$ ln -s /var/www/virtual/$USER/bedrock/web /var/www/virtual/$USER/html
[isabell@stardust ~]$
Point your browser to your domain, https://isabell.uber.space/wp/wp-admin
in this example, to start the wordpress installation process. Here you will
Set a language
Choose a Site title
Set a administrative account and password
Your site is now ready to use.
Note
Your Website will be available in your root-directory (e.g. https://isabell.uber.space/
). Unlike a standard WordPress-Installation, the Backend will be available in the /wp
subdirectory. To get there point your browser to https://isabell.uber.space/wp/wp-admin
.
Installing Plugins¶
Unlike a “normal” Wordpress-Installation, with bedrock, you cannot install Plugins or edit Code via the Wordpress-Backend. This is intended behaviour and part of the reason to use bedrock in the first place.
Instead you can use composer to manage Plugins. Every Plugin (or Theme) listed in on Wordpress.org is present as a Composer-Package in the WPackagist-Repository.
To install a plugin, find the exact plugin name (e.g. classic-editor
) from the Wordpress Plugin Directory and get it via composer:
[isabell@stardust ~]$ cd /var/www/virtual/$USER/bedrock/
[isabell@stardust bedrock]$ composer require wpackagist-plugin/classic-editor
./composer.json has been updated
Running composer update wpackagist-plugin/classic-editor
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
- Locking wpackagist-plugin/classic-editor (1.6.3)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
- Downloading wpackagist-plugin/classic-editor (1.6.3)
- Installing wpackagist-plugin/classic-editor (1.6.3): Extracting archive
Generating optimized autoload files
Using version ^1.6 for wpackagist-plugin/classic-editor
[isabell@stardust bedrock]$
You can do the same thing with themes, using wpackagist-theme
:
[isabell@stardust ~]$ cd /var/www/virtual/$USER/bedrock/
[isabell@stardust bedrock]$ composer require wpackagist-theme/twentytwenty
./composer.json has been updated
Running composer update wpackagist-theme/twentytwenty
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
- Locking wpackagist-theme/twentytwenty (2.4)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
- Downloading wpackagist-theme/twentytwenty (2.4)
- Installing wpackagist-theme/twentytwenty (2.4): Extracting archive
Generating optimized autoload files
Using version ^2.4 for wpackagist-theme/twentytwenty
[isabell@stardust bedrock]$
Updates¶
Warning
Whilst using Wordpress with bedrock it does not update itself automatically by default. Also updating via the wordpress Admin-Backend is not possible as soon as your environment is set to production
. Checkout the Wordpress-Blog for Updates.
Updating Plugins¶
For Plugins and themes installed with composer, you can simply use composer update
in the bedrock
directory:
[isabell@stardust ~]$ cd /var/www/virtual/$USER/bedrock/
[isabell@stardust bedrock]$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 0 installs, 3 updates, 0 removals
- Updating phpoption/phpoption (1.7.2 => 1.7.3): Downloading (100%)
- Updating vlucas/phpdotenv (v4.1.0 => v4.1.2): Downloading (100%)
- Updating roave/security-advisories (dev-master 0365bf2 => dev-master b81a572)
Writing lock file
Generating optimized autoload files
[isabell@stardust bedrock]$
Updating Wordpress core¶
To update Wordpress itself you have several options:
Requiring the new version with
composer require
. In this example we want to update to version6.4.2
:[isabell@stardust ~]$ cd /var/www/virtual/$USER/bedrock/ [isabell@stardust bedrock]$ composer require roots/wordpress 6.4.2
Editing
/var/www/virtual/$USER/bedrock/composer.json
to always update wordpress when runningcomposer update
.Change the line
"roots/wordpress": "6.4.2"
to"roots/wordpress": "^6.4.2"
(your version number might vary) and safe. Then runcomposer update
as for plugins. This will always update wordpress core until the next main version (7).
Tested with Bedrock 1.23.1, Wordpress 6.4.2, Uberspace 7.15.6, and PHP 8.2
Written by: Lukas Herzog <hallo@lukasherzog.de>