jamesmorrison/apollo

Vagrant for WordPress development

Apollo

Apollo is designed to quickly and effortlessly run any PHP / HTML application locally - specifically Apollo was designed for WordPress development.

Features

• Nginx (1.10.0)
• PHP 7.0 (7.0.22)
• MySQL (5.7)
• Mailcatcher
• WP CLI

Installation

The installation guide can be found here: Apollo Installation Guide

Optionally, you can setup Dnsmasq to forward traffic to Apollo, this can be found here: Setting up Dnsmasq

Usage

Once the installation is complete, you'll see a sites folder has been created in the apollo directory. Within this sites directory, you'll see 2 folders: 000-default and 000-template.

000-default

This directory contains a simple HTML file; this is the "fallback" used if you attempt to navigate to a URL on Apollo that hasn't been configured correctly. Assuming you haven't changed the primary IP, going to http://10.10.10.10 will show you this file.

000-template

You should see a copy of WordPress core here, including a wp-config.php file that is setup to work with Apollo. All you need to do with the wp-config.php file is change the DB_NAME and optionally, enable the multisite section if required.

Creating a new site

To create a site, duplicate the 000-template folder and rename to the domain you'd like to access the site with e.g. site.dev

Requests passed to Apollo will look for a corresponding folder - i.e. if you create a folder called site.dev you would load this folder using http://site.dev; a request to http://bob.dev will look for a folder called bob.dev etc.

Multisite support

Sub-domain WordPress multisite setups are fully supported out the box; requests to sub-domains are mapped to the parent folder. e.g. assuming you've created your site.dev folder; a request to http://sub.site.dev will load content from the site.dev folder.

Sub directory setups are also fully supported, including specific rewrite rules in the default Nginx configuration to handle rewrites for wp-* files to look in the parent folder. e.g. a request to http://site.dev/sub/wp-includes/file.css will load from http://site.dev/wp-includes/file.css if the file does not exist.

Hosts

You will need to update your hosts file for each site you add, or (more conveniently) use Dnsmasq to automate this - e.g. point all .dev domains to Apollo.

A guide to setting up Dnsmasq for Aoollo can be found here: Dnsmasq For Apollo

Other Notes

Restarting system services

Every time you run vagrant up, 3 system services are restarted through inline scripts. These are Nginx, MySQL and PHP-FPM. If you find that a process has stopped working, you can restart these by running vagrant up, even when the box is running.

Mailcatcher

Mailcatcher (as the name suggests) "catches" all email sent through Apollo. You can access this through port 1080 on any URL configured to point to Apollo (maybe just use http://10.10.10.10:1080 for simplicity).

This is automatic and starts every time Apollo is booted through vagrant up.

HTTPS

Apollo has full support for HTTPS, however the certificate is not signed by a valid root certificate. This means that all sites you host locally will show as a security exception in your browser. Simply accepting this security exception will allow you to use https with your local sites with no issues.

Multiple TLD's

Apollo supports all single level top level domains (TLD's) out the box (e.g. .dev / .test / .local etc.), as long as the DNS resolves to the Vagrant box. See the above guide for setting up Dnsmasq - change .dev to your custom extension as required.

Only the .co.uk multi-level TLD is supported out the box, however others can be added upon request - please raise an issue here

Multiple local instances of Apollo

As Apollo can support any TLD, it's possible to have multiple Apollo instances running on your system simultaneously.

If you wish to have multiple instances running, you'll need to change the IP in the VagrantFile for the second (or subsequent) instance.

As long as the correct domain resolves to the correct IP, the Apollo instances will work seamlessly together.

apollo's Issues

SSL fails on .dev domains in Chrome 63

Fix the SSL message

Message shows as setting up SSL, even when it's not.

Move the echoed message to within the conditional block and add a "skipping" message if skipped.

Disable all browser caching where possible

Consider commanding all browsers to no-cache such that local asset caching (css/js) does not confuse/delay developers.

see: [https://serverfault.com/questions/269420/disable-caching-when-serving-static-files-with-nginx-for-development](Link for disabling browser cache in nginx)

Some sort of progress indicator

Re-provisioning has errors where folders exist

• Establish whether a folder exists before trying to create it
• Check if files (e.g. SSL crt / key) are present and skip steps to create them (or remove / recreate?)

Mailcatcher not working with PHP 7.2

Document MySQL with Sequel Pro

Add mail server

No mail server results in 5xx errors when attempting to send emails

Add PHP My Admin

Switch sites to use the Vagrant folder

The vagrant folder is linked by default; can this be used as the default site root?

Add sample Customfile

Update README and Wiki to include notes on PHP My Admin

Mime Type Not Correct: non-postfixed html file 'downloaded as binary file'

To reproduce from apollo root directory (not in vagrant ssh):

cd sites

mkdir bugtest.apo

cd bugtest.apo

echo '<h1>/</h1> <p>subdir: <a href="/subdir/"> Click Here For subdir </a></p>' > index.html

mkdir subdir

cd subdir

echo '<h1>/subdir/</h1> <p>subfile: <a href="/subdir/subfile"> Click Here For Bug </a></p>' > index.html

echo '<h1>/subfile/</h1>' > subfile

Then:
Visit: bugtest.apo (change host file / DNSMasq to access)
follow link to subdir, you will see the index.html from the subdir
follow link to sub file.

Expected: The browser visits the subfile as a normal html navigation
Actual: I get prompted to download the file. Screenshot:

Symlink NGINX and PHP logs to the `logs` folder

Use Vagrant triggers plugin or similar to backup DB's

On:

• halt
• destroy

Update README and Wiki to include notes on database backups

Update wp-config

Update to: https://gist.github.com/jamesmorrison/71dea4e664ee51b9d31f62169cfe4749

Backup databases on `vagrant halt`

Better 404 page

404 page is dry and uninformative.

It needs to look more 'systemy' so that users don't confuse it with a sites default 404

WP Config - get fresh salts and keys on install

• Update the wp-config.php file with a placeholder
• Update the new site provisioning script with a call to get new keys from https://api.wordpress.org/secret-key/1.1/salt

Log files

Should end up in the "logs" folder for each site

Backup DB's on re-provision where MySQL is already installed

When Vagrant is re-provisioned, before doing anything else check if MySQL is installed; if so, run the db-backup.sh script to make sure that if everything goes to shit, no work is lost.

Merge the 2 Nginx configs

Currently 2 nginx config files are setup:

1. non-SSL
2. SSL

Merge these.

wp cli download - intermittent fail

wp cli doesn't always download core WordPress into the template folder, needs some kind of check for a file thats expected in that folder. If its not there - system should try to download it again. Alternatively please add this as a known issue to the documentation and that the workaround is to manually download WordPress and put it into this folder

Add xdebug

Not installed, needs doing

PHP 5.6 option

Add PHP 5.6 (and dependencies), have option (on a domain by domain basis) to elect to use PHP 5.6.

Default would still be PHP 7.0