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.
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:
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).
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.
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!
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.
gem install theme-juice
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.
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
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
tj
will executetj init
if the VM is uninitializedtj
will clone the selected starter templatetj
will run the starter template'sJuicefile
install commandtj
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
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!
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
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
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 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
.
- Is Windows supported?
- Can I use another VM instead of Graft?
- So, does that mean I can use any Vagrant box?
- What is a
Customfile
? - What is a
Juicefile
? - Does
tj
support subdomain multi-sites? - Can I access a project from another device (i.e. mobile)?
- Can I add my starter template, ________?
- Can I integrate my deployments with Slack?
- Can I use a self-signed SSL cert?
- Can I define my own Capistrano tasks?
- Can I run
wp-cli
commands on my deployment stages? - Troubleshooting
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 make sure that nothing breaks.
I don't regularly develop on Windows, so if you encounter any bugs, please let me know through a well-documented issue and I'll try my best to get it resolved.
Definitely. If you want to use tj
with Nginx and say, VVV, it's as simple as running tj
with a few flags:
tj new --vm-box git@github.com:Varying-Vagrant-Vagrants/VVV.git --vm-ip 192.168.50.4 --nginx
To use these permanently, set the appropriate ENV
variables through your .bashrc
or similar, i.e. export TJ_VM_BOX=git@github.com:Varying-Vagrant-Vagrants/VVV.git
, export TJ_VM_IP=192.168.50.4
and export TJ_NGINX=true
.
Note: Before running this, you might want to either choose a new vm-path
, or destroy and remove any existing VMs inside of your ~/tj-vagrant
directory. If tj
detects that a VM already installed, it will skip installing the new box.
Yes and no; in order for tj
to properly create a project, the Vagrant box needs to follow the same directory structure as Graft, and include logic for a Customfile
. Here is the required structure that tj
needs in order to be able to create new projects:
├── config/
| |
| ├── {apache,nginx}-config/
| | |
| | ├── sites/
| | | |
| | | ├── site-1.conf
| | | ├── site-2.conf
| | | ..
| | ..
| ├── database/
| | |
| | ├── init-custom.sql
| | ..
| ..
├── www/
| |
| ├── site-1/
| | |
| | ├── index.php
| | ..
| ├── site-2/
| | |
| | ├── index.php
| | ..
| ..
├── Customfile
├── Vagrantfile
...
It's a file that contains custom rules to add into the main Vagrantfile
, without actually having to modify it. This allows us to easily modify the Vagrant box without causing merge conflicts if you were to update the VM source via git pull
. Every file that tj
modifies is meant to be modified, so at any time you may update your installation of Graft with a simple git pull
without getting merge conflicts out the wazoo.
A YAML configuration file called a Juicefile
can be used to store commonly-used build scripts, similar to npm scripts. Each command can be mapped to any build script you like, allowing you to define a set of commands that can be used across all of your projects. If you plan to deploy using tj
, this file will also house your deployment configuration.
For reference, below is an example config: (see the config for our starter template, Sprout)
# Project configuration
project:
name: example
url: example.dev
# Manage command aliases for the current project
commands:
# Run project install scripts
install:
- npm install
- grunt build
# Manage build tools
dev:
- grunt %args%
# Manage front-end dependencies
asset:
- npm %args%
# Manage back-end dependencies
vendor:
- composer %args%
# Create a backup of the current database with a nice timestamp
backup:
- mkdir -p backup
- wp @development db export backup/$(date +'%Y-%m-%d-%H-%M-%S').sql
# Manage deployment settings for the current project
deployment:
# …
stages:
# …
Each command within the above example can be run from the command-line via tj <command>
. For example, we can run the tj dev
command, which will in turn run the command grunt
. Pretty simple, right?
If you happened to have noticed in the example above, there are a few sub-commands that contain %args%
; these are called placeholders. Each sub-command list is run within a single execution via joining: cmd1 && cmd2 && cmd3 && ...
, with all placeholders (%args%
/%argN%
) replaced with their corresponding argument index, when available.
Here's a few example commands utilizing placeholders:
commands:
example-command-1:
# Will contain all arguments joined by a space
- echo "%args%"
example-command-2:
# Will contain each argument mapped to its respective index
- cat '%arg1% %arg2% %arg3%'
# Will only map argument 4, while ignoring 1-3
- pbcopy < "%arg4%"
To clarify a little bit more using our first example config, we could run tj dev build
(notice the build
argument), and since our dev
command contains %args%
, that will in turn run the command grunt build
; if we run tj dev
command with the arguments some:other task
, that would be interpreted and run as grunt some:other task
.
You can specify an unlimited number of commands with an unlimited number of arguments within your Juicefile
; however, you should be careful with how this is used. Don't go including sudo rm -rf %arg1%
in a command, while passing /
as an argument. Keep it simple. These are meant to make your life easier by helping you manage build tools, not to do fancy scripting.
You may define ERB template strings within a project starter template's Juicefile
. These will be replaced when creating a new project.
For example,
# Project configuration
project:
name: <%= name %>
url: <%= url %>
will be replaced with,
# Project configuration
project:
name: example-project
url: example-project.dev
if those were the options chosen during a project creation.
name
: Project namelocation
: Project locationurl
: Project URLxip_url
: Project xip.io URLtemplate
: Project template repository URLrepository
: Initialized repository URL, if availabledb_host
: Project database hostdb_name
: Project database namedb_user
: Project database userdb_pass
: Project database passworddb_import
: Path to imported database filevm_box
: Virtual machine box URLvm_ip
: Virtual machine IP addressvm_revision
Revision hash or branch of VMvm_path
: Virtual machine location on the host machinevm_root
: Web root of the VM on the host machinevm_location
: Project location within the VM on the host machinevm_srv
: Project location within the VM on the guest machinevm_prefix
: Virtual machine project location prefix
If you're able to use Landrush for your DNS, then yes. All subdomains will resolve to their parent domain. Landrush comes pre-installed when you create your first project with tj
. Having said that, unfortunately, if you're on Windows you'll might have to manually add the subdomains to your /etc/hosts
file due to Landrush not being fully supported yet. If you have the Windows chops, head over there and contribute to Landrush by squashing that bug. I'm sure he would appreciate it!
Yes! Every project created with tj
will automatically be set up to support using xip.io. If you're using OSX, then everything should work out of the box. If you're not using OSX, then you'll need to point port 80
on your host machine to 8080
; Vagrant cannot do this by default for security reasons.
Once everything is good to go, you can access a project from another device on the same network by going to <project-name>.<your-hosts-ip-address>.xip.io
e.g. themejuice.192.168.1.1.xip.io
.
If you're familiar with forwarding host ports on operating systems other than OSX, check out this file and make a pull request so that everybody else can benefit from your smarts.
You can also use a service like ngrok, if you prefer that over xip.io:
ngrok http -host-header project.dev 80
Yes! Just update the TEMPLATES
constant inside commands/create.rb and make a pull request. I'll verify that the template includes a Juicefile
(not required, but preferred to automate build steps), and that everything looks solid. Until then (or if your template is private), just run the command below to clone your template.
tj create --template git@your.repo:link/goes-here.git
Yes, you can integrate deployment notifications with your teams Slack account by adding the following template to your Juicefile
:
deployment:
# ...
slack:
url: https://hooks.slack.com/services/your-token
username: Deploybot
channel: "#devops"
emoji: ":rocket:"
# ...
Check out capistrano-slackify for more information.
Yes, unless you used the --no-ssl
flag, tj
will set up each new site to support SSL, and the VM will generate a new self-signed certificate. In order to take advantage of it, you'll need to accept the self-signed certificate on your host machine.
Yes. Any file within a directory called deploy/
in your project with extensions .rb
, .cap
or .rake
will be automatically loaded by Capistrano.
For example, within our starter template, you will find a deploy/
directory, inside is a few example tasks. Open one of them and you'll see an example task invokable by tj remote <stage> <namespace:task>
.
To learn more about Rake and how you can define your own Capistrano tasks, check out the official Rake repository as well as the official Capistrano tasks documentation.
If you're interested in checking out tj
's predefined tasks, head over here. You may override any task with custom functionality by using the same namespace/task name as outlined below,
# encoding: UTF-8
Rake::Task["db:push"].clear # Clear previous task
namespace :db do
desc "Overridden database push task"
task :push do
# Your new task here
end
end
Sure can, and without the help of tj
! As of version 0.24
, wp-cli
does this out of the box. Whenever you create a new site, tj
will add a file to your project's root directory called wp-cli.local.yml
that contains something along the lines of:
@development:
ssh: vagrant@example.dev/srv/www/tj-example
You can then run wp
commands like this,
wp @development plugin list
Feel free to add your other stages into that file as well!
- Help! It won't let me
git clone
anything! - What the heck is an
invalid multibyte char (US-ASCII)
?! - Why are my
.dev
domains resolving to127.0.53.53
?!
If you're hitting issues related to git clone
, either cloning the VM or a starter template, then you most likely don't have SSH-keys for GitHub set up correctly. Either go through that article and assure that you can use Git with the git@
(ssh://git@
) protocol, or else you can manually run tj
with the appropriate flags corresponding to the problem-repository, swapping out git@github.com:
for https://github.com/
. For example:
tj create --template https://github.com/starter-template/repository.git --vm-box https://github.com/vm-box/repository.git
The flag duo above replaces the URLs for the starter template and VM box repositories so that they use https
instead of the git
protocol.
Or, you can globally update git
to always swap out git@github.com:
with https://github.com/
by modifying your git config
with this command:
git config --global url."https://github.com/".insteadOf "git@github.com:"
For one reason or another, your terminal probably doesn't support UTF-8, so it's throwing a fit. Use the --no-unicode
flag to disable the unicode characters. If the problem still persists, try running it with the --boring
flag. That should disable all unicode characters and coloring.
tj create --no-unicode # Or: tj create --boring
Google has applied for control of the .dev
TLD (top level domain). To fix it, you'll need to periodically flush your local DNS cache (I'm honestly not entirely sure why). In the future, we'll probably switch to something like .localhost
. Here are a few commands to flush your cache on OSX:
# Yosemite:
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# Mountain Lion:
sudo discoveryutil mdnsflushcache; sudo discoveryutil udnsflushcaches
Still having issues? Yell at me!
- First, create a well documented issue for your proposed feature/bug fix
- After getting approval for the new feature, fork the repository
- Create a new feature branch (
git checkout -b my-new-feature
) - Write tests before pushing your changes, then run Rspec (
rake
) - Commit your changes (
git commit -am 'add some feature'
) - Push to the new branch (
git push origin my-new-feature
) - Create a new Pull Request
Please see LICENSE for licensing details.
Ezekiel Gabrielse, @ezekkkg, http://ezekielg.com