‼️	This repository is no longer maintained. Setup still works, but does not receive any further updates. Included versions do become unsupported at some point. Consider our native LEMP server for macOS instead.

Marlin vagrant

Marlin vagrant is a WordPress optimized vagrant server created for local development environment for servers that use WordPress optimized software, reliable hardware, brilliant for your own virtual servers in production.

This Vagrant box is named after marlin which is one of the fastest animals in the world.

Marlin vagrant server can be used as plain local server for serving your files or testing static PHP, but it's also perfect for WordPress development.

Marlin is a strictly development VM and should be customized. Also works out of the box. Tweak as close as your production server to get the best results.

What's inside?

Feature	Version / Amount
Ubuntu	16.04 LTS (Xenial Xerus)
MySQL	MariaDB 10.4
PHP	7.2, 7.0, 5.6
nginx	1.10.3
Redis	5.0
Vagrant	NFS, provision.sh with pre-installed packages, speed optimizations
CPU cores	2 (if you need different amount, edit Vagrantfile)
RAM	8 GB (if you need different amount, edit Vagrantfile)

Background

This is originally based on jolliest-vagrant, our first Vagrant box with Apache, but modified heavily later on. Read the original background story about Dude's vagrant-servers here.

Usage

To start this vagrant box, always run vagrant up --provision, with provision -hook to ensure all the stuff are loaded up properly.

Table of contents

1. Installation on Mac/Linux
2. Installation on Windows
3. How to add new vhost
4. How to remove a project or vhost
5. Connecting with another computer in LAN
6. Port forwarding (optional)
7. Recommended post-installations
8. Create a self-signed SSL Certificate for marlin-vagrant
9. Sequel Pro settings for MySQL
10. Error logging in PHP
11. Troubleshooting and issues
12. WP-CLI alias
13. Tips to speed up performance

Recommendations

1. Mac OS X or Linux
2. Simple knowledge of web servers
3. WordPress projects under the same folder
4. dudestack in use

Installation on Mac/Linux

1. Install Virtualbox
2. Start Virtualbox, check updates and install all the latest versions of Virtualbox and Oracle VM Virtualbox Extension Pack, if asked
3. Install vagrant (Mac OS X Homebrew: brew install vagrant or brew cask install vagrant)
4. Install VirtualBox Guest Additions -updater vagrant-vbguest with command vagrant plugin install vagrant-vbguest
5. Clone this repo to your Projects directory (path ~/Projects/marlin-vagrant is depedant in dudestack)
6. (Optional, do this for example if you want to use other image or encounter problems with included Vagrantfile) If you don't know or don't care, don't do this step. Modify Vagrantfile: config.vm.box and config.vm.box_url to match your production server OS, config.vm.network for IP (I recommend it to be 10.1.2.4 to prevent collisions with other subnets) (For Linux you need to remove , :mount_options... if problems occur with starting the server. Please remove parts that give you errors). If you don't need to access server from LAN with co-workers to update WordPress for example, remove completely line with config.vm.network "public_network". You may also need to try different ports than 80 and 443 if your Mac blocks them. For example change the ports to 8080 and 443 (also change triggers accordingly)
7. If you store your projects in different folder than ~/Projects, change the correct path to config.vm.synced_folder
8. Edit or add packages to match your production server packages in provision.sh if needed (it's good out of the box though)
9. Add 10.1.2.4 somesite.test to your /etc/hosts
10. Run vagrant up --provision. This can take a moment.

If you make any changes to Vagrantfile, run vagrant reload or vagrant up --provision if the server is not running, or if you change provision.sh while running, run vagrant provision.

You can always see the server status by vagrant ssh'ing to your vagrant box and typing sudo service nginx status. If it's not started, run sudo service nginx start. Note: if your server doesn't start, please ensure you either have removed example.test from vhosts/ and /etc/nginx/sites-available and /etc/nginx/sites-enabled or created a directory called example to your Projects dir.

Installation on Windows

1. Install Virtualbox for Windows
2. Install Vagrant for Windows
3. Install Git for Windows
4. Right click My Computer (or This Compu ter on Windows 10), click Properties, click Advaned System Settings tab, click Environment Variables. Change VBOX_MSI_INSTALL_PATH to VBOX_INSTALL_PATH. In Windows 10, you can go to Advanced System Settings simply typing it when Start Menu is open.
5. Start cmd
6. Navigate to root of C:\ with double dots ..
7. mkdir Projects to create a project dir and cd Projects to enter it
8. Clone this repo to Projects with command git clone [email protected]:digitoimistodude/marlin-vagrant.git
9. Edit Vagrantfile with your favorite editor and rename ~/Projects to C:/Projects. Remove , :mount_options => ['nolock,vers=3,udp,actimeo=2']
10. Run vagrant up --provision, wait when box is installed and Allow access if it asks it. This can take a moment.
11. Add 10.1.2.4 somesite.test to your C:/Windows/system32/drivers/etc/hosts file and have fun!

How to add new vhost

It's simple to manage multiple projects with nginx's sites-enabled configs. If your project name is jolly, and located in ~/Projects/jolly, just add new config to vhosts. vhosts/jolly.test would then be:

server {
    listen 80;
    #listen [::]:80 default ipv6only=on;

    access_log /var/www/jolly/access.log;
    error_log /var/www/jolly/error.log;

    root /var/www/jolly;
    index index.html index.htm index.php;

    server_name jolly.test www.jolly.test;
    include hhvm.conf;
    include global/wordpress.conf;

    #  Static File Caching
    location ~* .(jpg|jpeg|png|gif|ico|css|js)$ {
       expires 365d;
    }
}

Run vagrant provision, add 10.1.2.4 jolly.test to /etc/hosts and boom! http://jolly.test points to your project file.

How to remove a project or vhost

If you remove a project from Projects folder, or rename it, you should also remove/rename vhosts/projectname.test correspondingly and make sure after vagrant ssh you don't have that conf to point nonexisting files in /etc/nginx/sites-enabled and /etc/nginx/sites-available. Otherwise the server wont' start!

For example, if we create test project to ~/Projects/test and then remove the folder, next time you are starting up nginx fails. You will have to vagrant ssh and sudo rm /etc/nginx/sites-enabled/test.test && sudo rm /etc/nginx/sites-available/test.test && sudo rm /vagrant/vhosts/test.test.

Connecting with another computer in LAN

You should be good to go after setting up /etc/hosts to 192.168.2.242 jolly.test (depending on your local subnet of course) on remote computer. If you have problems like I had, run this command on your vagrant host PC (not inside vagrant ssh!):

sudo ssh -p 2222 -gNfL 80:localhost:80 vagrant@localhost -i ~/.vagrant.d/insecure_private_key

This also helps in some cases where you are unable to open http://localhost in browser window.

Port forwarding (optional)

Vagrantfile has port forwarding included, but Mac OS X has some limitations. If .test-urls are not reachable from local area network, please add this to /usr/bin/forwardports by sudo nano /usr/bin/forwardports:

echo "
rdr pass on lo0 inet proto tcp from any to 127.0.0.1 port 80 -> 127.0.0.1 port 8080
rdr pass on lo0 inet proto tcp from any to 127.0.0.1 port 443 -> 127.0.0.1 port 8443
" | sudo pfctl -f - > /dev/null 2>&1;

echo "==> Fowarding Ports: 80 -> 8080, 443 -> 8443";

osascript -e 'tell application "Terminal" to quit' & exit;

Chmod it by chmod +x /usr/bin/forwardports and run forwardports. You have to do this every time after reboot, if you are co-working in LAN.

Recommended post-installations

Not everything is included to this box since we want it keep as minimal as possible, but here's some recommended pieces you should install especially on production:

• ngx_pagespeed - The PageSpeed modules are open-source server modules that optimize your site automatically.

Create a self-signed SSL Certificate for marlin-vagrant (optional)

1. Go to the directory you cloned this repo by cd ~/Projects/marlin-vagrant
2. SSH into your vagrant box: vagrant ssh
3. sudo mkdir /etc/nginx/ssl
4. sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/nginx.crt (press enter all the way through)
5. sudo nano /etc/nginx/sites-enabled/yourwebsitename.test and make sure it looks like something like this:

server {
    listen 443 ssl;

    access_log /var/www/yourwebsitename/access.log;
    error_log /var/www/yourwebsitename/error.log;

    root /var/www/yourwebsitename;
    index index.html index.htm index.php;

    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;

    server_name yourwebsitename.test www.yourwebsitename.test;
    include hhvm.conf;
    include global/wordpress.conf;
}

6. Restart nginx: sudo service nginx restart

WP-CLI alias

WP-Cli is included in dudestack per project within composer.json and won't work by default. You'll need this alias on your Mac or Linux .bashrc or .bash_profile file:

alias wp='ssh [email protected] "cd /var/www/"$(basename "$PWD")"; /var/www/"$(basename "$PWD")"/vendor/wp-cli/wp-cli/bin/wp"'

After restarting Terminal or running . ~/.bashrc or . ~/.bash_profile you will be able to use wp command directly on your host machine without having to ssh into vagrant.

Error logging in PHP

If you want to see php-fpm errors for example in php7.0-fpm, add this to the bottom of /etc/php/7.0/fpm/pool.d/www.conf:

catch_workers_output = yes
php_flag[display_errors] = on
php_admin_value[error_log] = /var/log/fpm7.0-php.www.log ; remember: touch /var/log/fpm7.0-php.www.log && chmod 775 /var/log/fpm7.0-php.www.log && sudo chown www-data /var/log/fpm7.0-php.www.log
php_admin_flag[log_errors] = on
;php_admin_flag[error_reporting] = E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_WARNING
php_admin_flag[catch_workers_output] = yes
php_admin_value[memory_limit] = 1024M
slowlog = /var/log/fpm7.0-php.slow.log ; remember: touch /var/log/fpm7.0-php.slow.log && chmod 775 /var/log/fpm7.0-php.slow.log && sudo chown www-data /var/log/fpm7.0-php.slow.log
request_slowlog_timeout = 10

If you alter these, you can check the config for errors by running sudo php-fpm7.0 -y /etc/php/7.0/fpm/pool.d/www.conf. Note that this means everything is right (you should see errors and lines if there's incorrect values):

[04-Oct-2016 22:03:06] ERROR: An another FPM instance seems to already listen on /run/php/php7.0-fpm.sock
[04-Oct-2016 22:03:06] ERROR: FPM initialization failed

Also remember to check sudo php-fpm7.0 -t just in case. Then run sudo touch /var/log/fpm7.0-php.www.log && sudo chmod 775 /var/log/fpm7.0-php.www.log && sudo chown www-data /var/log/fpm7.0-php.www.log and sudo touch /var/log/fpm7.0-php.slow.log && sudo chmod 775 /var/log/fpm7.0-php.slow.log && sudo chown www-data /var/log/fpm7.0-php.slow.log and then restart php7.0-fpm with sudo service php7.0-fpm restart.

To see log, run sudo tail -f /var/log/fpm7.0-php.www.log.

Troubleshooting and issues

Authentication failure

==> marlin: Booting VM...
==> marlin: Waiting for machine to boot. This may take a few minutes...
    marlin: SSH address: 127.0.0.1:2222
    marlin: SSH username: vagrant
    marlin: SSH auth method: private key
    marlin: Warning: Connection timeout. Retrying...
    marlin: Warning: Authentication failure. Retrying...
    marlin: Warning: Authentication failure. Retrying...
    marlin: Warning: Authentication failure. Retrying...
    marlin: Warning: Authentication failure. Retrying...
    ...

This is probably if you use jolliest-vagrant or another vagrant box with same ssh keypairs. This can be solved with cat ~/.ssh/id_rsa.pub, copying that key, then going to cd ~/Projects/marlin-vagrant && vagrant ssh, typing password, then adding the file to VM's known_hosts and authorized_keys with nano ~/.ssh/known_hosts and nano ~/.ssh/authorized_keys and saving the file while connecting.

Other issues

In any issue, error or trouble, please open an issue to issue tracker.

Sequel Pro settings for MySQL

Choose SSH tab and add following settings.

Setting	Input field
Name:	vagrant mysql
MySQL Host:	127.0.0.1
Username:	root
Password:	vagrant
Database:	optional
Port:	3306
SSH Host:	10.1.2.4
SSH User:	vagrant
SSH Password:	vagrant
SSH Port:	22

Tips to speed up performance

You can install following plugins to get more speed:

• vagrant-cachier
• vagrant-faster