Lando is the official Conifer development environment, and comes highly recommended. It's the best local dev tool in the galaxy!
We also support Varying Vagrant Vagrants, although much of the tooling around testing etc. may require some tweaking depending on your setup.
Using Lando (Recommended)
First, install Lando if you haven't already. Your future self will thank you.
git clone email@example.com:sitecrafting/conifer.git
Note: Lando setups are self-contained, so it doesn't matter where you clone it to (as it would if using Vagrant, MAMP, or similar).
cd conifer lando start
The first time you start the app, it will install WordPress, Timber, and the Groot starter theme for you. Then it will expose your local Conifer dev site at https://conifer.lndo.site (or similiar).
WP Admin username: conifer
Yup, that's pretty much all there is to it.
Recommended next steps:
- If you're new to Lando, we suggest reading the Overview, and then the WordPress recipe tutorial. Conifer uses the WordPress recipe under the hood, so it's useful to know what's going on.
landowith no arguments to see/verify custom tooling commands (also see Custom Lando Tooling, below)
- Log in to /wp-admin to verify the credentials you set up
- Explore the testing setup
- Start hacking on Conifer! 🌲 🚀 🎉
Custom Lando Tooling
Conifer's Lando environment comes with several goodies for making local development a breeze.
Along with the universal Lando commands, we get these commands for free from Lando's built-in WordPress recipe:
lando wp: run WP-CLI commands
lando composer: run composer commands
lando db-import <file>: Import a WordPress database from a .sql or .sql.gz file. The file must be inside your Conifer directory tree!
lando php: run arbitrary PHP commands
lando mysql [wordpress]: drop into a MySQL shell (
wordpressis the name of the database Lando installs for us)
Conifer's Lando setup also provides these commands:
lando unit: run Conifer's PHPUnit test suite
lando e2e: run Conifer's end-to-end Cypress test suite
lando cypress: run arbitrary
lando sniff: run PHPCS on the Conifer codebase
tailthe WP debug.log in real time
lando yarn: run arbitrary yarn commands
lando docs: build the Conifer doc site being served from the
docsservice (https://docs.conifer.lndo.site or similar)
lando gitbook: Run arbitrary gitbook commands.
Serving a local documentation site
If you're working on docs, it's helpful to see the doc site as compiled from your exact copy of the Markdown files.
To that end, you can run
lando docs to build the docs site once.
It's annoying to do that over and over, though. To rebuild the docs automatically whenever a Markdown file changes, run
lando gitbook serve. This will start a process and block your current shell session; press
Ctrl-C to exit the process.
Warning: The localhost URL in the output is misleading
gitbook serve command starts a web server at
localhost:4000, but this is actually the
localhost inside the
docs service container, meaning you can't actually view the doc site at that address. Go to the proxy URL output by
lando start or
lando info instead. This will be something like https://docs.conifer.lndo.site.
Other development tools
Conifer's Lando environment also includes:
- a phpMyAdmin installation at https://phpmyadmin.conifer.lndo.site or similar
- a Mailhog instance for catching and managing outgoing mail at https://mailhog.conifer.lndo.site or similar
These URLs may be different depending on which ports are already take on your computer. Tun
lando info to see the actual URLs.
Using Varying Vagrant Vagrants (VVV)
NOTE: We are happy to support Vagrant as a secondary/backup environment if for some reason you can't run Lando/Docker on your machine. However, please do us a favor and try the Lando setup first. It is drastically simpler to maintain and the tooling is much more tightly integrated.
Pre-requisite: setup VVV
You will obviously want to have VVV installed and configured before you start. If you run into trouble with this, check your system against the VVV requirements, or take a look at the troubleshooting guide.
Non-standard VVV setups are not supported. GitHub issues about custom VVV configurations will be closed immediately. You have been warned.
xvfb core utility
Cypress, the CLI tool used for Conifer end-to-end tests, requires xvfb for running its headless browser. Tell VVV to install it by adding it as a core utility in
# the core utilities install tools such as phpmyadmin utilities: core: # ...existing utils... - xvfb
Provision the dev site
Add this to your
sites block in
conifer: repo: https://github.com/sitecrafting/conifer.git - conifer.wordpress.test
vagrant reload --provision per usual.
The provisioning scripts within Conifer will install composer dependencies.
Install front-end tooling
Front-end tooling for VVV is a work in progress and is currently low-priority. For now, you can run:
sudo npm install -g yarn newman
Cypress tests are currently unsupported in VVV. If you are willing and able to fix this, please submit a PR against this issue. Thanks!