Development Setup

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.

First, install Lando if you haven't already. Your future self will thank you.

Clone

git clone git@github.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).

Start

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

Password: conifer

That's it

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.
  • Run lando with 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.

CLI commands

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 (wordpress is 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 cypress commands
  • lando sniff: run PHPCS on the Conifer codebase
  • lando debug: tail the WP debug.log in real time
  • lando yarn: run arbitrary yarn commands
  • lando docs: build the Conifer doc site being served from the docs service (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

The 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:

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.

Add the 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 vvv-custom.yml:

# the core utilities install tools such as phpmyadmin
utilities:
  core:
    # ...existing utils...
    - xvfb

Provision the dev site

Add this to your sites block in vvv-custom.yml:

  conifer:
    repo: https://github.com/sitecrafting/conifer.git
      - conifer.wordpress.test

Run 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!

results matching ""

    No results matching ""