This repo contains a "VVV" Vagrant / VirtualBox based local development environment setup for jkl.hacklab.fi site. It supports modern theme and plugin development workflow with popular PHP/WP development tools set up on a regular LEMP stack on Ubuntu:

• PHP error logs at www/hacklab-jkl/wp-content/debug.log
• WP-CLI tool
• PhpMyAdmin and readiness to connect external SQL clients like DBeaver CE etc.
• IDE features
  • LSP (go-to-declaration etc. just start editor in www-root),
  • XDebug (see notes on later section for config)
  • Profiling tools, mail diagnostics, etc...
• Automatic hosts file config for development domain, access via http://jkl.hacklab.test
• Composer etc.

VVV is long running project and has nearly everything required for development while it can seem a bit heavy and monolithic (and more tied to AMD64). It's still a very active open source project with developers keeping it up to date and responding to guestions in support channels.

Other development environment tools can be leveraged also with some minor changes in the pull-production.sh sync script written to be run in VVV root path.

Apple Silicon Mac would need to use commercial version of Parallels to be able to run Vagrant. Better options may be to run Vagrant on a separate AMD64 laptop or to use LocalWP app with modified sync script. Container based WP-ENV tool and plain container images are available also.

Setup with existing VVV environment

Add to config.yml:

hacklab-jkl:
  skip_provisioning: false
  description: "Hacklab Jyväskylä"
  repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
  php: 8.2
  hosts:
    - jkl.hacklab.test
  custom:
    wpconfig_constants:
      WP_DEBUG: true
      WP_DEBUG_LOG: true  # logs to wp-content/debug.log

Then run vagrant reload --provision and site should be initialized in few minutes. Skip over the next "Setup from scratch" section.

Setup from scratch

By default the VVV stock configuration is set to create http://jkl.hacklab.test site at www/hacklab-jkl/public_html. Additionally http://one.wordpress.test and http://two.wordpress.test stock WP sites are available for testing.

Clone repo to a drive with few gigabytes of free space and provision Vagrant (first run takes ~15 minutes):

git clone git@github.com:HacklabJKL/VVV.git
cd VVV
vagrant plugin install --local
vagrant up --provision

Pulling live site to development environment

After finishing initial setup, make sure you have working server credentials with public key authentication set up to Hacklab Jkl WordPress server "Jonne" to be able to pull production files and database to the local development environment.

Add "jonne" into local development machine's SSH config eg. with vi ~/.ssh/config:

Host jonne
hostname jkl.hacklab.fi
user <ssh_login_user_name_here>
port 22

Validate that ssh jonne commands connects to server correctly and then then run sync script to pull files and database from production site:

./pull-production.sh

After which http://jkl.hacklab.test site should be available for logging in with production credentials.

If using existing VVV environment, copy the pull-production.sh script into VVV root path and make it executable with chmod +x pull-production.sh before running it.

HTTPS setup

By default the local site is set up to use HTTP instead of HTTPS, which should be fine for most local development tasks and installs with least problems.

VVV supports HTTPS however and to enable it, refer to https://varyingvagrantvagrants.org/docs/en-US/references/https/ on how to setup CA and accept self-signed certs in browser.

Then comment out following line in the end of ./pull-production.sh and run script again to keep https-urls intact.

vagrant ssh -c "wp --path=/srv/www/hacklab-jkl/public_html search-replace \"https://\" \"http://\" --dry-run"  # comment this to use https

Notes about pushing changes to production

Changes in themes or plugins should be versioned in separate GIT repositories, pushed to remote (eg. Github) and then pulled on production server.

This should work fine for low volume collaboration as a starting point.

Local GIT repo state will be overridden when running pull-production.sh, so it's best to keep it clean.

Pushing changes that are saved in database or filesystem (eg. page content, customizer settings, widgets, wp settings etc.) from local to production is not supported. It is theoretically possible however.

Note about uploads folder

All server pictures and media files are downloaded to local development environment, which can be turned off in script with rsync --exclude 'uploads' that is commented out as example.

After that all upload folder pictures will give 404's which can be annoying. Nginx can be set to provide placeholder jpg's in place of actual images via some url rewrite config trickstery.

XDebug step debugger

Map /home/<local_username>/<path_to>/vvv/www/ path to /srv/www/ and it should work. Run xdebug_on command in Vagrant if it doesn't enable XDebug for some reason (eg. vagrant ssh -c "xdebug_on").

Example NeoVim config:

  local dap = require("dap")

  -- Config for a VVV (Vagrant) WordPress site
  dap.configurations.php = {
    {
      type = "php",
      request = "launch",
      name = "Listen for VVV Xdebug",
      port = 9003,
      localSourceRoot = "/home/user/sites/vvv/www/",
      serverSourceRoot = "/srv/www/",
    },
  }

Refer to VVV XDebug docs for more examples etc.

Usage with existing VVV setup etc.

WordPress www-root can be also symlinked as ./public_html to same folder as pull-production.sh script, and it will use it if it's found. This way the script can be used independently, also with other setups.

It was simply embedded with this VVV repository as convenience for someone who has not ran WordPress before and is interested in developing Hacklab Jkl WordPress web site with least hassle.

Original VVV repository readme continues...

VVV

VVV is a local developer environment, mainly aimed at WordPress developers. It uses Vagrant and VirtualBox/Parallels/HyperV to create a linux server environment for building sites, and contributing to WordPress itself.

VVV stands for Varying Vagrant Vagrants.

How To Use

To use it, download and install Vagrant and a provider such as VirtualBox, Docker, or Parallels Pro. Then, clone this repository and run:

vagrant plugin install --local
vagrant up --provision

When it's done, visit http://vvv.test.

The online documentation contains more detailed installation instructions.

• Web: https://varyingvagrantvagrants.org/
• Contributing: Contributions are more than welcome. Please see our current contributing guidelines. Thanks!

Minimum System requirements

For system requirements, please read the system requirements documentation here

Software included

For a comprehensive list, please see the list of installed packages.