Skip to content
This repository has been archived by the owner on Jan 25, 2022. It is now read-only.

Latest commit

 

History

History
531 lines (370 loc) · 30 KB

FAQ.md

File metadata and controls

531 lines (370 loc) · 30 KB
Raw

WPLib Box FAQ

Table of Contents

Overview

Support

Troubleshooting

Technical Issues

Glossary

Business

Future

Overview

###What is WPLib Box? WPLib Box is designed the be the EASIEST to use professional solution for local WordPress development. WPLib Box leverages the open-source tool Vagrant and either Oracle's open-source VirtualBox or commercial products from VMware.

###How is WPLib Box Better? All other Vagrant boxes for WordPress (that we are aware of) start with a base Linux and then build the box "from ground up" during the provision cycle installing Nginx or Apache, PHP, MySQL, etc. Examples of this include VVV, V QuckStart and Trellis. This is both time consuming for provisioning, which you may need to do more than once, and also problematic if anything has changed that may break the provisioning process.

Instead WPLib Box pre-provisions our box so you can vagrant up or vagrant reload --provision in around 30 seconds (after the box is first downloaded), and almost eliminates the chance of our provisioning process breaking, unlike the other available solutions (that we know of).

So WPLib Box does not view our Vagrantfile and related provisioning scripts as our product, our scripts are just examples of how you can use our Box Image. Instead we treat our Box Image as our product, and our goal is to make it bulletproof and feature-rich with a goal that you will be able to get the web server stack you need with only configuration, and not with provisioning.

Support

Quick Help via Slack

PLEASE ask your questions in the #box channel.

CLICK HERE to add yourself to our Slack account at wplib.slack.com#box. Then use the #box channel in our Slack account to ask questions or get quick help on installing or using WPLib Box or WP-related workflow via chat and/or ScreenHero (we know that you cannot sign up for ScreenHero any more, but we can send you an invite; just direct message @mike via Slack and request a ScreenHero invite.)

But we still encourage you to submit bugs and feature requests via GitHub issues though you can first chat with us to verify the bug or flesh out the feature request via Slack if you want to.

Scheduled Help via Screen Sharing

We can also schedule a time with you to screen share using ScreenHero to help you get WPLib Box up and running successfully and/or about WP-related workflow. (We know that you cannot sign up for ScreenHero any more, but we can send you an invite; just direct message @mike via Slack and request a ScreenHero invite.)

Less Urgent Help via GitHub issues

Finally you can submit a GitHub issue with bugs and/or feature requests. Feel free to submit any issue about WPLib Box, especially feature requests or to discuss integrating other open-source software with the box. When you do please assign your issue the "question" label.

Troubleshooting/WPLib Box is not working

WPLib Box is not working

There are several reasons for this, and depending on what steps are failing there are different solutions:

VirtualBox will not install

Please first try Googling the error messages you get when trying to install.

VirtualBox is independent of WPLib Box and you will ofter find solutions from their support before you find solutions from us. But if you are still stuck after then please do contact us for support.

Vagrant will not install

Please first try Googling the error messages you get when trying to install.

VirtualBox is independent of WPLib Box and you will ofter find solutions from their support before you find solutions from us. But if you are still stuck after then please do contact us for support.

The required Vagrant plugins are not found or installing.

Please first try Googling the error messages you get when trying to install.

These Vagrant plugins are independent of WPLib Box and you will ofter find solutions from their support before you find solutions from us. But if you are still stuck after then please do contact us for support.

vagrant up is failing

Try running vagrant up --debug to see if it can reveal any issues with your system that you are able to correct. You may want to redirect to a debug log so you can read the output in your text editor: 

vagrant up --debug > vagrant.log 2>&1

If you can't find discover the problem and determine the solution using the --debug switch please provide your vagrant.log when requesting support.

wplib.box will not load in the browser / pinging wplib.box times out

First check to see what version of Vagrant you are running by running the following in your terminal/command line:

vagrant -v

If you are running Vagrant 1.8.6 upgrade your Vagrant; see Vagrant-1.8.6-bug to understand why. If not please run vagrant reload --debug and provide your vagrant.log when requesting support.

No Answer Here

If none of the items listed above nor any of the FAQs listed below or in the general README solve your problem please contact us for help either via Slack or by posting an issue here on GitHub. We really do want to make sure everyone can be successful with WPLib Box and are more than happy to help.

When requesting support please provide any information you can such as a debug log and/or anything else you can tell us about your computer setup.

Technical Issues

How do I Run WP-CLI?

WP-CLI is installed in the WPLib Box virtual machine so to use it you first SSH into the box and then run your wp-cli command, for example:

vagrant ssh
wp plugin install hello-dolly

Why is WPLib Box Caching Things?

WPLib Box installs Redis for persistent object caching. To disable this simply rename www/content/object-cache.php to something like object-cache.disabled.php. But we do have plans to add numerous ways to do this.

If you need to clear the cache the easiest way at the moment is to run vagrant reload from your development (host) computer.

How do I Flush the Redis Persistent Object Cache?

If you need to test with the persistent object cache, but you are running into the need to flush a corrupted cache you can simply run the following command from your host's command line:

vagrant ssh
redis-cli
flushall
exit

Technical Issues

How do I Deploy My Site from WPLib Box?

Deployment to a production or staging server is extremely simple. Just:

  1. Copy the entire contents of the www/ directory to the website root of the server where you are hosting your site.
  2. Using a SQL client tool such as Sequel Pro or Navicat export aka "dump" your database to a .sql file.
  3. Import your .sql file into your web host's MySQL or MariaDB server which may be referred to as "executing" your SQL file.
  4. Modify www/wp-config-local.php on your web host to use your web host's database credentials and any other configuration options that differ on your production or staging server.
  5. In future deployments be sure not to overwrite your web host specific www/wp-config-local.php file.

And except for the following NOTE, that is it.

NOTE: You will need to run whatever process you normally run to change the URLs from your local URLs to your production or staging URLs. There are many solutions to this although not one ideal solution thus explaining how to do this is out of the scope of this FAQ. But let us google it for you.

Why is the Directory Layout used Not "Standard?"

By default WPLib Box uses the WordPress Skeleton layout published by Mark Jaquith in 2011. We chose it because unlike the standard WordPress directory layout it is Composer-friendly which is almost a requirement these days for professional-level PHP development.

But if you are not yet using Composer or don't feel you have the need for it you can you the "Standard" WordPress directory layout instead. See the three (3) simple approaches that follow in the next FAQ.

Can I use the Standard WordPress Directory Layout?

Absolutely.

To be clear we assume you mean the directory layout that has the following subdirectories:

/wp-admin/
/wp-content/
/wp-includes/

(Those directories are the exact layout you'll see in a download of WordPress from WordPress.org.)

The Manual Approach

To use the Standard WordPress directory layout open up Mac Finder or Windows Explorer and navigate to your project's /www directory (the project directory is the one containing Vagrantfile and the /scripts folder.) Then do the following:

  1. Delete the /www/wp/wp-content directory; you don't need it. (Uh, after checking you did not store anything in /www/wp/wp-content by accident. If you did, move it out then delete the directorty.)

  2. Move all the remaining files and directories up one level in the directort hierarchy; from /www/wp to /www.

  3. Rename /www/content to /www/wp-content

  4. Delete /www/wp

  5. In your IDE/text editor open www/index.php and then change the code from '/wp/wp-blog-header.php' to '/wp-blog-header.php' (e.g. remove the leading /wp from the filepath.)

  6. Rename /www/../composer.json to /www/../composer.json.save and delete /www/../composer.lock (since you can no longer use Composer with this directory layout structure. Note: composer.* is in the project root directory.)

  7. That's it, you are done! WPLib Box now in "Standard" WordPress directory layout.

The Script Approach

Or you can run this script, if you feel confident in doing so. First vagrant ssh to enter the box and then run the following commands:

cd /var/www
mv wp/*.* .

mv wp/wp-admin/ .
mv wp/wp-includes/ .
mv content/ wp-content/

rm -rf wp/

sed -i "s#/wp/wp-blog-header.php#/wp-blog-header.php#" index.php

The CLI Approach (Experimental)

Or lastly you can try our experimental/alpha "Inside-the-Box" Box CLI. After you make sure you have the latest version of WPLib Box just run:

vagrant ssh
box set-directory-layout-standard

Even better, if you want to switch back to "Skeleton" layout, we have a command for that too:

vagrant ssh
box set-directory-layout-skeleton

How do I Use WPLib Box on New Projects?

To use WPLib Box on new projects just copy the Vagrantfile and the scripts/ directory from this repository to your new project and change the domain name to the local domain name for your project. The only ”constraint” (that we are currently aware of) is you will need to have your website root in a www/ directory that is a sibling to Vagrantfile and to scripts/ but otherwise it should all just work using vagrant up.

NOTE:: You do not have to organize the WordPress directory structures like we have with /www/content and /www/wp; you can easily use the standard directory layout used by WordPress core e.g. www/wp-content/ and www/, respectively.

How do I Use WPLib Box on Pre-Existing Projects?

To use for an existing project, you follow the same instructions as for new projects; copy the Vagrantfile and the scripts/ directory from this repository to your new project, change the domain name to the local domain name for your project and move your website root into a www/ directory that is a sibling to Vagrantfile and to scripts/ and then vagrant up.

If you cannot put your code into a www/ subdirectory for some reason you can put the Vagrantfile in your web root and change the line that starts with config.vm.synced_folder to be:

 config.vm.synced_folder ".", "/var/www"

If you cannot create a scripts/ directory in the same directory as your Vagrantfile you can name that directory something else — such as wplib-scripts/ — and then search for scripts/ in your Vagrantfile and replace it with whatever you named your directory, e.g. with wplib-scripts/ as in our example.

How do I Configure Composer to Work with WPLib Box?

Configure composer.json however you like; WPLib Box is agnostic with respect to Composer.

Yes, we do include a composer.json with our WPLib Box repository but only so that WPLib Box will just work, out-of-the-box (yeah, sorry for the pun!)

How do I Import a MySQL Database?

When the box is created, a default WordPress database is installed. If you need to import a different dataset or restore a backup of the data, you can simply vagrant ssh into the guest and perform a MySQL import.

To do this, first copy your MySQL database dump to a /sql sub directory in your project directory (your Vagrantfile is in your project directory.) Assuming you called your database dump my-db.sql then run the following commands in your host computer's command line/terminal window when in your project directory:

cd /your/project/directory
vagrant ssh
box import-db my-db.sql

Be sure to backup your database BEFORE you run the import-db command.

How do I backup the MySQL database in the box?

If you have a live database inside of WPLib Box you may want to backup the database to the /sql/ directory in your project root. You can do that like so:

cd /your/project/directory
vagrant ssh
box backup-db

The above commands will backup your database to /your/project/directory/sql/current.sql. If there already was a current.sql it will be renmed to previous1.sql and 1 will be incremented each time there is a new backup.

Which PHP Versions are Available?

Currently, the box has PHP 5.6, PHP 7.0 and PHP 7.1, with PHP 7.0 running by default. Versions 5.6 and 7.0 are each implemented using their own Docker container and the latter is installed directly into Ubunutu in our box. All modules installed are configured for both versions of PHP.

How do I Switch PHP Versions?

The PHP version in use by the site is set in the project.json file in the services section and the processvm property. This will set both the web version and the command line version.

To change both web and command line versions to PHP 7.1, SSH into the running Vagrant box from your project directory and then run the box php7.1 command:

cd /your/project/directory
vagrant ssh
box php7.1

To change to 7.0 or 5.6, use the same command but replace 7.1 with 7.0 or 5.6 from while SSHed into the box, e.g.:

box php7.0

or

box php5.6

How do I Install PhpMyAdmin?

We decided not to include phpMyAdmin in the core box image because it installs files for Apache that we don't need so we decided to make it optional.

To install phpMyAdmin look for the instructions here.

How do I Get a URL to Provide Access to My Box's Site From the Internet?

The WPLib Box image has localtunnel.me pre-installed in the box. Simply run these commands from your host's command line:

vagrant ssh
lt --port 80

This will provide you with a URL to share the local site until you exit the command by either terminating the program or shutting down the machine.

You can also use Vagrant Share.

How do I debug with Visual Studio Code?

The configuration file for Visual Studio Code is already included in the respository. Ensure that you have installed the PHP Debug extension for Visual Studio Code.

How do I access Adminer?

Adminer is a web front end to administer the MySQL server. End users can access Adminer at http://adminer.{your-domain}. If you have not changed the box domain name, that would be http://adminer.wplib.box.

The credentials are:

  • Host: 172.17.0.1
  • Username: wordpress
  • Password: wordpress
  • database: wordpress

How do I access MailHog?

MailHog is an email testing tool for development purposes. In WPLib Box, all outgoing emails are captured and available for inspection via the MailHog interface: http://mailhog.wplib.box. If you have changed the box domain, you can use http://mailhog.{your-domain}.

How do I fix the Vagrant 1.8.6 Bug?

Vagrant 1.8.6 appears to have an issue with auto-configuring its network. Until this is fixed by Vagrant there is a workaround which requires you to SSH into the box after vagrant up. It is not difficult — the instructions appear longer than the task itself — just follow these steps:

  1. Once your box is running (after a vagrant up) run vagrant ssh.

  2. Once "inside" WPLib Box type sudo nano /etc/network/interfaces to load the network config into the Nano editor.

  3. Look for the second (2nd) occurence of auth eth0 and change it to auth eth1.

  4. Also change the eth0 in the next line (iface eth0 inet static) to be eth1. The result should be iface eth1 inet static.

  5. Delete both lines that begin with #VAGRANT- by moving your cursor to those lines and pressing Ctrl-K once for each line.

  6. Save the file by pressing Ctrl-O then pressing [Enter].

  7. Exit the editor with Ctrl-X.

  8. Exit "inside" WPLib Box (the SSH session) by typing the exit command.

If you somehow mess up while editing you can exit Nano and start over by pressing Ctrl-X then pressing N (for "No") when it asks you if you want to "Save the buffer?".

In addition you need to make a simple change to Vagrantfile using whatever editor you normally use to edit code. Find the following line in Vagrantfile around line 264:

config.vm.network 'private_network', ip: IO.read('IP').strip

And add , auto_config: false to the end, like so:

config.vm.network 'private_network', ip: IO.read('IP').strip, auto_config: false

Then run vagrant reload. This should fix it.

Also you should not need to revert that after upgrading to a new version of Vagrant unless you need to change the box's IP address.

How do I switch from Nginx to Apache (or vice versa)?

By default, WPLib Box uses Nginx as its webserver. However, Apache is available and can be switched out with Nginx. The box CLI has a command, set-web-server to accomplish this.

For example, to switch from Nginx to Apache:

  • Log in to the box using vagrant ssh on your host machine.
  • Enter the following command: box apache to make Apache the running webserver.
  • Conversely, you can box nginx to switch from Apache to Nginx.

How do I switch from MySQL to MariaDB (or vice versa)?

The box runs MySQL as the default database, however MariaDB is available. To configure the box to use MariaDB instead, use the box command (which will dump the contents of the current database and import into the new database):

  • Log in to the box using vagrant ssh on your host machine.
  • Enter the following command: box mariadb to use MariaDB.
  • Conversely, you can box mysql to switch from MariaDB to MySQL.

How do I see the logs for Docker container Foo?

The logs for a Docker container can be viewed using the command docker logs foo, where foo is the name of the container whose logs you wish to view.

To get a list of containers you can run the following command:

docker container ls

To see just the names run this command:

docker container ls --format '{{.Names}}'

At the time of this writing the container names in WPLib Box were (though not all run all the time):

  • mailhog
  • mariadb
  • mysql
  • memcached
  • redis
  • php5_fpm
  • php7_fpm
  • apache
  • nginx
  • proxy

In the case of the webserver containers, these logs contain both the access and error log entries.

If you get 404 Not Found on Vagrant Up

If you get a 404 error from vagrant up chances are you are on a 1.x version of Vagrant and need to upgrade to a 2.x version. The 1.x version does not recognize the new Vagrant Cloud and still looks to atlas.hashicorp.com for our Vagrant image, which is obviously no longer there (not sure why Hashicorp does not support redirects here, but maybe Vagrant 1.x deoes not follow them?)

Upgrading Vagrant to 2.x then running vagrant plugin repair should resolve this issue.

Here is what this error looks like on the command line:

$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Box 'wplib/wplib' could not be found. Attempting to find and install...
    default: Box Provider: virtualbox
    default: Box Version: 0.16.0
The box 'wplib/wplib' could not be found or
could not be accessed in the remote catalog. If this is a private
box on HashiCorp's Atlas, please verify you're logged in via
`vagrant login`. Also, please double-check the name. The expanded
URL and error message are shown below:

URL: ["https://atlas.hashicorp.com/wplib/wplib"]
Error: The requested URL returned error: 404 Not Found

Glossary

What Do All These Terms Mean?

The following are terms we have decide to use in our FAQ and in other documents. If any of these terms conflict with broader industry terms please submit a pull request with any suggested corrects.

Otherwise, there they are:

  • Virtual Machine: A file, or more correctly a collection of files that together contain a bit-for-bit image of a physical computer to enable emulation of the computer using software running on another computer aka the "Host" computer. The host software that WPLib currently supports is VirtualBox (free and open-source) and VMware (commercial.) We may also support Parallels in the future; if that is important to you please let us know.
  • Host Computer: The (typically) physical computer with which a developer writes code and runs their IDE/editor to runs Vagrant that then "Hosts" WPLib Box inside of VirtualBox, which also runs on the Host Computer.
  • Guest Computer: The Virtual Machine running on the Host Computer.
  • Software Stack: The collection of software used by a (Virtual) Machine to perform its role. To host WordPress within a VM, even for local development the Software Stack might consist of a web server like Nginx or Apache, a database server like MySQL or MariaDB and a version of PHP such as 5.6 or 7.0. More advanced use cases — include WPLib Box — use a more conplex software stack.
  • Provisioning: To install and configure the Software Stack required for a specific use-case.
  • Box Image: A digital file containing the bits of a Virtual Machine and its hard disk(s). The Box Image may or may not have been "Provisioned" over and above what the Linux distribution provides by default. The WPLib Team pre-provisions the WPLib Box Software Stack which is why WPLib Box is so easy to use. And our Box Image is based on an Ubunutu image. You can see the history of WPLib Box Images at Hashicorp's Atlas repository of available Vagrant Boxes for download.
  • Vagrant Box: A Vagrantfile which is a specialized Ruby script that runs to download a "Box Image", possibly Provisions it beyond the base box, set the local IP address for the Virtual Machine.
  • Local Box Image Cache: Vagrant downloads pristine copies of Box Images to a local cache to allow it to quickly copy the box to a project directory the first time vagrant up is run for a project, or after a vagrant destroy is run. Your Local Box Image Cache is located at:
    • Mac OS X and Linux: ~/.vagrant.d/boxes
    • Windows: C:\Users\{username}\.vagrant.d\boxes
  • Project Box Image: Although Vagrant maintains pristine copies of Box Images in the Local Box Image Cache it makes a copy of that box for each of your projects and stores that copy in ~/VirtualBox VMs (on Mac & Linux) and in C:\Users\{username}\VirtualBox VMs (on Windows.) It also creates a vagrant directory in your project to maintain information about the copy of the Box Image used by the project. For example, if you vagrant ssh into a running Vagrant Box and make configuration changes those changes will be in the Project's Box Image, but not in the` pristine copies of Box Image nor in other projects that share the same named Box Image.

Suggest a New FAQ Question & Answer

If you have figured something out about WPLib that we have not documented, please help out your fellow developers fork this repo then submit a pull request.

##Business

What is our Business Model?

We are a consulting company that is transitioning to a product company that offers products and services for improving Developer Experience for PHP developers who have chosen to use WordPress as a platform.

If you have idea ahout how we could help your development organization with workflow please contact us with your ideas and we'll see if we can help.

What Services Can The WPLib Team Offer Your Company?

Do you think your company might benefit from:

  1. A Hosting-company Specific Vagrant Box for your Customers?
  2. A Customized Stack in a Vagrant Box for your company's developers?
  3. Delivering Your Plugins or Theme inside your own Vagrant Box?
  4. Sponsoring a Named Version of the WPLib box for public distribution?
  5. Demos of your WordPress-based Web Apps, Plugins or Themes without exposing source code?

If any of those ideas intrigue you, reach out and contact us.

##Future

What Are the Plans/Roadmap for WPLib Box?

We have a lot of ideas and some plans but do not yet have enough feedback to determine an appropriate roadmap. What we can say is that we plan to make many of the manual configuration processes be adjustable via:

  1. Command Line Interface (CLI)
  2. Admin Console at wplib.box
  3. Via the WordPress Debug Bar
  4. Via an RESTful API that will enable #1-#3 above