tj

What is it?

The Theme Juice CLI, also known as tj, helps you create new local WordPress development sites, manage existing sites, and deploy them, all from the command line. It utilizes our Graft VM for the virtual machine to spin up new development sites in seconds.

Check out our getting started guide over at SitePoint, or view the documentation site.

What problems does tj help solve?

To get the most out of tj, it is recommended that you use our starter template. Why? Keep on reading and we'll tell you. tj is built on top of tried and true open source libraries such as Capistrano for deployment, Vagrant for local development, and even a little bit of WP-CLI for database migration. Some of the main pain points tj helps solve are:

1. Local development

Say goodbye to MAMP! With one command, tj create, you can have a new local development site up and running in under a minute. It uses Vagrant to create a robust development environment, and lets you create and manage multiple projects within a single virtual machine. It also handles deployments over SSH using Capistrano if you want to move away from FTP (more about that below).

2. Multi-environment projects

Oh, multi-environment development! Usually, you would have to ignore your entire wp-config.php file and create one for every single stage. These can get out of sync fast. Even worse, the config file actually gets checked into the project repo and so the credentials fluctuate from dev to staging to production. Not good. Not good at all.

Our starter template uses a .env file, and has support for an unlimited number of environments (we generally do development, staging and production). Since these settings are housed in a .env file, they are not checked into the repo. That means the codebase is 100% environment agnostic. The way it should be.

3. Multi-environment deployments

Really. Want to deploy to staging? Set up a staging environment inside of the Juicefile, make sure you can SSH in without a password (remember, best practices here!) and run tj deploy staging. Boom, you're done. Make a mistake? Run tj remote staging rollback. Crisis averted!

Want to pull the database from your production server to your development install? Run tj remote production db:pull and you're good to go; tj will automatically handle rewriting any URLs within the database.

How about pushing your development database and your local uploads folder? Run tj remote production db:push && tj remote production uploads:push and you're done. You can even send notifications to your teams Slack channel if you want to!

Requirements

tj requires Vagrant and VirtualBox to be able to create virtual machines for local development. Please download and install both of these before getting started. If you plan on using tj for deployments, you should also ensure that your remote servers have WP-CLI installed in order for tj to be able to handle database migration.

I recommend one of the latest versions of Ruby MRI (2.2, 2.1, 2.0). tj requires at least MRI 1.9.3. For the full report, check out the Travis CI build status, where I test against an array of Ruby interpreters.

I also recommend you set up SSH-keys for GitHub. Internally, tj uses git clone with SSH URLs, so things might break if you don't have your keys set up properly.

Installation

gem install theme-juice

Getting Started

If you're going to be using our starter template, then I recommend checking out it's dependencies before running your first create. That way, the build step doesn't fail.

Initialize the VM

This will install and configure the virtual machine. It will clone the VM into the vm-path, install the required Vagrant plugins (such as Landrush, unless disabled) and will also set up port forwarding if you're on OSX.

tj init

Create a new project

This will lead you through a series of prompts to set up required project information, such as name, location, template, database info, etc. Using the specified information, it will run the installation process and set up a local development environment, if one hasn't already been set up. It will sync your local project location with the project location within the VM, so you can run this from anywhere on your local system.

tj create

What happens on your first create?

1. tj will execute tj init if the VM is uninitialized
2. tj will clone the selected starter template
3. tj will run the starter template's Juicefile install command
4. tj will create all of the necessary project files, such as:

• Create/append to Customfile containing DNS and synced folder settings
• Create/append to init-custom.sql for database creation and setup
• Create $project.conf containing Apache server settings
• Create wp-cli.local.yml containing SSH settings

1. tj will provision the VM to put the new configuration into effect

If you've never used tj before, then that last step might take a little while. After that's done, you should be able to access your new project at the specified development url. It's that easy!

Set up an existing project

This sets up an existing local project within the development environment. You will go through a series of prompts to create the necessary files. This command is essentially an alias for tj create --bare.

tj setup

Remove a project

This will remove a project from your development environment. You will go through a series of prompts to delete a project. This will only remove files that were generated by tj i.e. the database setup, DNS setup, and other project configuration files.

It will not touch your local folders that were synced to the VM.

tj delete

Deploy a project

After configuring your Juicefile and setting up SSH keys for yourself, this will deploy a project to the passed <stage> using Capistrano. Head over to the docs to see all of the available commands. There's a quick getting started section there too for your first deployment!

tj deploy <stage>

Want more?

Want to check out all of the various flags and features tj offers? Just ask tj for help, and you'll be greeted with a nice man page full of information about how to use just about everything.

tj help

Or, you can also check out cli.themejuice.it for a pretty website chock-full of the same documentation provided by tj help.

FAQ

1. Is Windows supported?
2. Can I use another VM instead of Graft?
3. So, does that mean I can use any Vagrant box?
4. What is a Customfile?
5. What is a Juicefile?
6. Does tj support subdomain multi-sites?
7. Can I access a project from another device (i.e. mobile)?
8. Can I add my starter template, ________?
9. Can I integrate my deployments with Slack?
10. Can I use a self-signed SSL cert?
11. Can I define my own Capistrano tasks?
12. Can I run wp-cli commands on my deployment stages?
13. Troubleshooting

Is Windows supported?

Yes! But, since Windows doesn't support UTF-8 characters inside of the terminal, and is picky about ANSI color codes, you'll probably have to run tj with a couple flags.

Something that has worked for me on one of my Windows machines is to run all commands through git-scm with the --boring flags. This will disable all unicode characters and colors from being output. You may also use the --no-landrush flag to disable Landrush, which currently has experimental Windows support (at least try it first and help report any bugs!).

To set these globally via the ENV, set the following environment variables:

TJ_BORING=true
TJ_NO_LANDRUSH=true

In addition to that, tj uses the OS gem to sniff out your OS and it'll adjust a few things accordingly to