

NOT COMPLETE¶

When working with a new tool you can often be overwhelmed by new jargon. While WPLib Box is unfortunately no different our vision is to empower you to understand everything you need to know to use WPLib Box effectively, such as this glossary.

Note

We are defining these terms as they related to WPLib Box. Thus our definitions may differ somewhat from more the general definitions such as those you might find on Wikipedia.

Host Machine¶

The Host machine is your physical computer that typically runs Windows, Mac or Linux, and that "hosts" WPLib Box similar to how your computer hosts a Microsoft Word document or an Apple Keynote presentation.

Virtual Machine¶

A Virtual Machine is a full Linux operating system that runs "virtually" within your Windows, Mac or Linux host computer.

Or more clearly, a bit-for-bit image of what could have been a physical computer's file system to enable emulation of that "computer" using VirtualBox running within your "Host" computer.

VirtualBox¶

VirtualBox is open source software — recently acquired by Oracle — that is required by WPLib Box to enable the Linux virtual machine to run in your host Windows, Mac or Linux computer.

Guest¶

The WPLib Box Guest is the Linux-based virtual machine running within your host machine.

Provisioning¶

Provisioning is the process of installing and configuring the software stack on WPLib Box prior to your first use of WPLib Box.

Provisioning includes tasks like importing an initial WordPress database from /sql/provision.sql and adding permissions to the same database.

Components¶

Components in the context of WPLib Box are packages of software that collectively comprise your WPlib Box's software stack.

A component can be a container, a script, source code, or various other types of files. To learn more details about WPLib Box Components, click the preceding link.

Containers¶

Containers in the context of WPLib Box are used to package each service and executable component in its own sandbox to effectively eliminate the most common conflicts that occur between services and executables, and to be more flexible in terms of which services and executables can be incorporate into a project's software stack.

WPLib Box strives to use individual Docker containers for all service and executable components it needs. This architecture decision is in large part why WPLib Box is more powerful and more flexible than any other local development solution for WordPress today.

This architecture also empowers WPLib Box to more quickly support newer versions of services and executables, often enabling you — the WPLib Box user — to upgrade to a new version in the case we have not yet updated our official containers.

Box Image¶

A Box Image is a digital file containing the binary bits of WPLib Box's virtual machine.

Note

The box image format used by WPLib Box has been defined by Hashicorp's Vagrant.

WPLib Box's box image has been pre-provisioned with the WPLib Box software stack beyond what the default Linux distribution provides which is why in-part WPLib Box is so easy to get started (when compared to other solutions like VVV.)

You can see the history of (most) WPLib Box images at Hashicorp's VagrantCloud repository of Vagrant images available for download.

Note

We say "most" WPLib Box images because when Hashicorp moved from its old "Atlas" repository to the current VagrantCloud they neglected to transfer over some of our historical releases and thus they have been lost to the mists of time.

WPLib Box's current box image is based on Ubunutu, but we will soon be replacing it with a more streamlined Linux distribution.

Vagrant¶

Vagrant is software currently required by WPLib Box that reads a configuration file named Vagrantfile in your WordPress project's directory and it automates the creation and configuration of a virtual machine that is run using VirtualBox.

Vagrant is software written in the Ruby programming language and it reads information from a Vagrantfile found in your project's directory on your host computer and it uses that information to download and configure WPLib Box.

Note

We plan to eliminate the need to use Vagrant in the very near future. At that point WPLib Box will only be dependent on VirtualBox.

Vagrantfile¶

A Vagrantfile is a specialized Ruby language script that is run by Vagrant to automate the setup of WPLib Box.

Although a Ruby script, Vagrantfile is declarative in nature — more like a JSON file — as it was designed to allow you to "declare" the details needed by Vagrant to automate the creation and configuration of your virtual mahine using VirtualBox.

The "declarations" in the Vagrantfile tell Vagrant what it needs to know to:

(Initially) download the specified version of WPLib Box's box image "_ into Vagrant's local box image cache on your host computer,
Set the IP address for the WPLib Box virtual machine,
Add the host name used to reference WPLib Box — e.g. wplib.box or example.local — to your host computer's hosts file,
Mount your project directory on your host computer inside of WPLib Box so PHP and Nginx/Apache can access them,
Specify the username to be used for vagrant ssh; currently boxuser in WPLib Box's case and configure SSH agent forwarding,
And finally, specify the (lightweight, in the case of WPLib Box) scripts to run on vagrant up, both for initial install and subsequent uses.

Hosts file¶

Your hosts file is a plain text file found on your host computer that contains one of more IP addresses mapped to domain names.

The purpose of your hosts file is to allow you to override the entries found at your DNS server. In the case of WPLib Box with .local domain names, your DNS server has no knowledge of your local development. This WPLib Box needs to add entries to your hosts file to allow you to use domain names for local development instead of hard-to-remember ports and/or IP addresses; e.g. http:/localhost:8888 or http:/10.10.10.136.

Typically you at least have localhost defined in your hosts file:

127.0.0.1 localhost

After WPLib Box is installed and configured¹, your hosts file will look something like this (likely with a different IP address and Vagrant hash.) The following enables

127.0.0.1 localhost

10.10.10.136  wplib.box  # VAGRANT: c1906b61bcd8c3211d7426a8a3310413 (default) / 4fdce32d-d9b3-$
10.10.10.136  docs.wplib.box  # VAGRANT: c1906b61bcd8c3211d7426a8a3310413 (default) / 4fdce32d-$
10.10.10.136  www.wplib.box  # VAGRANT: c1906b61bcd8c3211d7426a8a3310413 (default) / 4fdce32d-d$
10.10.10.136  adminer.wplib.box  # VAGRANT: c1906b61bcd8c3211d7426a8a3310413 (default) / 4fdce3$
10.10.10.136  mailhog.wplib.box  # VAGRANT: c1906b61bcd8c3211d7426a8a3310413 (default) / 4fdce3$

A bit of hosts file history

Hosts files predate the Internet's Domain Name System (DNS) and were how early Internet users 
mapped hostnames to IP addresses. This meant every user had to know the IP address of every 
computer they wanted to visit on the internet, or at least the sysadmin for the computer needed 
to know the IP address. Clearly that quickly became overwhelming for everyone on the Internet 
and was why the DNS system was introduced.

Local Box Image Cache¶

The term Local Box Image Cache is a WPLib Box coined-term to name the pristine box image that Vagrant downloads to a local cache on your host computer to enable quick cloning for additional projects.

vagrant up will clone a copy of this cached image into the project box image the first time it in run for a given Vagrantfile, but running vagrant destroy followed by a vagrant up will clone the cached box image too.

Your local box image cache is located at:

MacOS and Linux: ~/.vagrant.d/boxes
Windows: C:\Users\{username}\.vagrant.d\boxes

Project Box Image¶

The term Project Box Image is another WPLib Box coined-term to name the project-specific copy of the pristine copy local box image cache that Vagrant makes for each project in the following project-specific subdirectory:

Mac or Linux:

{project}/.vagrant

Windows:

{project}\.vagrant

The upshot is if you vagrant ssh into a running Vagrant Box and make configuration changes those changes will be in the project box image, but not in the pristine copy of box image nor in other projects that share the same named Box Image.

Beyond the project box image VirtualBox will import these images into its own directory for each project:

Mac or Linux:

~/VirtualBox VMs

Windows:

C:\Users\{username}\VirtualBox VMs

Why we plan to stop using Vagrant

This extremely inefficent use of storage is but one of the many reasons we are planning to replace Vagrant with our own solution in the very near future.

Site Builder¶

Here at the WPLib Box team we define a "Site Builder" as someone who installs WordPress, plugins, and themes — who might tweak the HTML, CSS, JS or PHP from time to time — but for the most part is not and does not consider themselves a "programmer."

We love professional Site Builders and think they provide an invaluable service to their clients so we are just as excited to hear from site builders how we can make WPLib Box better to help them their do their jobs as we are to hear from front-end or even backend WordPress developers.

Front-end Developer¶

Here at the WPLib Box team we define a "Front-end Developer" as someone who minimally has HTML and CSS skills — especially for responsive design — and who may or may not have Javascript programming skills and/or front-end build system skills combined with a CSS preprocessor like SASS or LESS. In our experience front-end development and theme development go hand-in-hand, although front-end developers can be found building plugins as well.

And we love professional front-end developers as without them WordPress sites would never be as compelling nor as functional as so many WordPress sites and themes have become. So we are very interested to hear from front-end developers how we can make WPLib Box better to help them their do their jobs.

Backend Developer¶

Here at the WPLib Box team we define a "Backend Developer" as someone who focuses on the PHP, MySQL and possibly REST API aspects of a WordPress site. In our experience backend development and plugin development go hand-in-hand but that doesn't mean backend developers can't have significant sway over theme code as many back end developers do.

And finally we love professional backend developers because frankly we are backend developers too! Without us, WordPress sites would never have the deep level of functionality that requires server-side coding and database expertise. So we are also very interested to hear from backend developers whose workflow may differ from our own so that we can make WPLib Box better for you.

Project¶

Most everything in WPLib Box is organized around the "Project." A Project is identified by a primary local domain name e.g. example.local or example.test.

A Project is assigned a directory for its source packages and data and media files which will be a subdirectory of the name identified by the primary local domain contained within the base projects directory. Thus if the base projects directory is ~/Sites and the project's local domain is example.local then the the project subdirectory would be ~/Sites/example.local.

A Project also has a configuration file found in project subdirectory with the name project.json. It (should) contain all the information required for WPLib Box to completely recreate a working local development environment for its Project. As such, project.json files are typically version controlled and easily shared by team members.

More specifically, a Project has an Project Stack that identifies the Components that WPLib Box will run and/or make available when the project is activated. This project stack is declared in the project.json file.

Base Projects Directory¶

A directory on your host computer that is mapped to /projects/ within WPLib Box. A typical example Base Projects Directory might be ~/Sites or C:\Sites, if you are on MacOS/Linux or Windows, respectively.

!!! info The projects directory inside the box will soon change In a near future version of WPLib Bix the /projects directory will be changed to /home/box/projects.

(Software) Stack¶

In general a "(Software) Stack" is the collection of software used by a software application to do its job.

To host WordPress in WPLib Box the collection of software used consists of a web server like Nginx or Apache, a database server like MySQL or MariaDB, a version of PHP such as 5.6 or 7.2 and possibly a cache server like Memcached or Redis.

Software Stack On Wikipedia

A "Software Stack" on Wikipedia — such as LAMP, WIMP, and MEAN — is a name identifying sets of software needed to create a complete software solution.

In the first of these "L.A.M.P." identifies L)inux, A)pache, M)ySQL and P)HP, and LAMP is a well-known stack that supports the WordPress platform.

Stack¶

In the context of WPLib Box, a "Stack" is the collection of software components that turn a basic do-anything Linux virtual machine into a powerhouse tailor-made for the local development of WordPress websites, or the development of any other web solution, for that matter.

Stacks can also extend other Stacks, or said another way one Stack and inherit the attributes of another. Our "wordpress" stack inherits from our "lxmp" stack, for example.

For WPLib Box you have both Named Stacks and Project Stacks.

Named Stack¶

WPLib Box's "Named Stacks" specifies the "Type" of components required to support a web solution such as WordPress, or any other web solution. And a Named Stack also defines the number of each component(s) of a given type that are required, which is typically one each.

However, a Named Stack is abstract and never used directly; Project Stacks are used by WPLib Box instead.

The detailed specifications for the Named Stacks WPLib Box supports at any given time can be found in the JSON files located in /opt/box/etc/stacks.

Attention

The initial JSON files for specifiying Named Stacks have not yet been finalized as of version 0.17.0.

Project Stack¶

A WPLib Box "Project Stack" is specific to a Project, and is the collection of components specified in the "stack" property of a a project's project.json file.

Typically an Project Stack will include all the required components for at least one named stack, such as "wordpress", possibly its optional components, and then zero (0) of more general purposes components and/or components of other named stacks.

This is an example of the default Project Stack from the default project.json for 0.17.0:

{
    "stack" : {
        "wordpress/dbserver":    "wplib/mysql:5.5.60",
        "wordpress/webserver":   "wplib/nginx:1.14.0",
        "wordpress/processvm":   "wplib/php:7.1.18",
        "wordpress/cacheserver": "wplib/redis:4.0.9",
        "wordpress/cliapp":      "wplib/wp-cli:1.5.1",
        "mkdocs/webserver":      "wplib/mkdocs:0.15.3",
        "box/mailsender":        "wplib/mailhog:1.0.0",
        "box/webproxy":          "wplib/proxy:1.14.0",
        "box/sqladmin":          "wplib/adminer:4.6.2"
    }
}

Attention

As of version 0.17.0 Project stacks are only partially implemented, with some of the functionality being hard-coded into various aspects of WPLib Box. That however is planned to change in the near future.

Component Type¶

A "Component Type" is a specially-formatted name that identifies a set of component properties and behaviors that are required to support a given use-case within WPLib Box, for example a web server or database server.

Component Types are identified by its two-part name, e.g. wordpress/webserver or wordpress/dbserver. The first part of the name identifies the "Named Stack" and the second part identifies the "Interface" relative to that Named Stack.

The detailed specifications for the provided Component Types can be found inside of WPLib Box in the /opt/box/etc/types directory. In future versions of WPLib Box (beyond 0.17.0) you will be able to add your own Component Types.

Attention

The defining JSON files for Component Types have not yet been finalized as of version 0.17.0.

Component Type Interface¶

A "Component Type Interface" specifies the details neededs by WPLib Box to install and activate a component as part of a WPLib Box project. These details include the "Class" of component and then the details that the specific class of component requires.

Looking specifically at Service Containers the details needed for them include port number(s), IP address(es), volume(s), number and usage for mount points, etc.

The detailed specifications for the known component type interfaces can be found in JSON files within /opt/box/etc/interfaces.

Attention

The defining JSON files for Component Types Interfaces have not yet been finalized as of version 0.17.0.

Component Class¶

A "Component Class" is one of the following:

Service Container — Services like Nginx and MySQL.
Executable Container — Executables such as the PHP CLI.
Script Package — Scripts like WP CLI, Composer and PHPUnit
Source Package/Files — Source code such as WordPress core, plugins and themes
Data Files — Data like MySQL dumps, XML and JSON files.
Media Files — Media such as images, video and PDF files.

Suggestions for Improvement¶

If you have any terms to add or suggestions for improvement to our existing descriptions we welcome your suggestions. So please help out your fellow developers and fork this repo, make your fixes and then submit your pull request.

Unless you have changed your host name in the HOSTNAME file, which you will almost certainly have done. ↩

NOT COMPLETE¶

Glossary of Terms related to WPLib Box¶

Host Machine¶

Virtual Machine¶

VirtualBox¶

Guest¶

Provisioning¶

Components¶

Containers¶

Box Image¶

Vagrant¶

Vagrantfile¶

Hosts file¶

Local Box Image Cache¶

Project Box Image¶

Site Builder¶

Front-end Developer¶

Backend Developer¶

Project¶

Base Projects Directory¶

(Software) Stack¶

Stack¶

Named Stack¶

Project Stack¶

Component Type¶

Component Type Interface¶

Component Class¶

Suggestions for Improvement¶