Introduction
Meet tj
, a tool that helps you create new local WordPress development sites, manage existing sites, and deploy them, all from the command line.
tj
handles all of the hard stuff: creation of a local development environment, managing local and remote WordPress sites, and the most annoying part of all, actually deploying those sites. Say goodbye to MAMP!
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.
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
NAME
tj
- WordPress development made easy
SYNOPSIS
tj
[command] [--flag=arg] [--flag]
GLOBAL OPTIONS
--vm-box
=repositoryForce vagrant(1) box for use as VM*
--vm-path
=pathForce path to VM*
--vm-ip
=ipForce IP address of VM*
--vm-prefix
=stringForce directory prefix for project in VM*
--vm-revision
=revisionRevision hash or branch to checkout for VM (default is master)
--from-path
,--in-path
=pathRun Juicefile(5) commands from the passed path instead of from the current directory.
--from-srv
,--in-srv
=pathRun Juicefile(5) commands from the passed srv path instead of from the current host directory path when using the
--inside-vm
flag.--inside-vm
,--in-vm
Run Juicefile(5) commands from inside of the virtual machine instead of your host machine.
--yolo
,--yes
Say yes to anything and everything, and maybe even get a few surprises
--boring
Prints all output without any fancy formatting
--no-unicode
Prints all output without unicode characters
--no-colors
,--no-color
Prints all output without color
--no-animations
Prints all output without animations**
--robot
Prints all output with absolutely no formatting
--no-landrush
Disable the landrush(1) gem for managing DNS*
--no-port-forward
,--no-port-forwarding
Disable automatic port forwarding*
--verbose
Prints out additional logging information
--quiet
,--shh
Suppresses all command output
--trace
Raises any exceptions caught during runtime
--dryrun
,--dry-run
Run a command without actually doing anything
--nginx
,--no-apache
*
Flag is really only applicable on init(1) before the VM has been created,
unless a new (unused) vm-path
is specified.
**
Coming soon (possibly)
PRIMARY COMMANDS
Run tj help
[command] to view an individual command's man page.
- init(1),
up
Initialize the VM
- create(1),
new
,mk
Create a new project (also runs init(1) if VM is uninitialized)
- setup(1)
Setup an existing project (alias for create(1)
--bare
)- delete(1),
rm
,remove
,trash
Delete a project
- deploy(1),
server
,remote
Deploy and manage a project
update
Update virtual machine and dependencies
SECONDARY COMMANDS
version
,--version
,-v
Print the current version
env
,--env
=[property]Print environment properties
list
,ls
,projects
,apps
,sites
List all projects
vm
,vagrant
,vvv
=[command[,command]...]Manage development environment via vagrant(1). Commands are proxied to your Vagrant installation so that they can be run from any directory.
CONFIG FILE
A YAML configuration file called a Juicefile(5) can be used to store commonly
used build scripts, similar to npm(1) 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 deploy(1) configuration.
For reference, below is an example config:
# 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
assets:
- 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 @dev db export backup/$(date +'%Y-%m-%d-%H-%M-%S').sql
# Manage deployment settings for the current project
deployment:
# ...
stages:
# ...
CONFIG COMMANDS
The commands within the commands
block can be run from the command line via
tj <command>
. For example, we can run the dev
command by running tj dev
,
which will in turn run the command grunt
.
If you noticed in the example above, there are a few commands that contain
%args%
; each command list is run within a single execution via joining:
cmd1 && cmd2 [&& cmd3...]
, with all %args%
/%argN%
being replaced with
the corresponding argument index, when available.
Here's a few example commands using placeholders:
example-command:
# Will contain all arguments joined by a space
- cmd1 %args%
# Will contain each argument mapped to its respective index
- cmd2 '%arg1% %arg2% %arg3%'
# Will only map argument 4, while ignoring 1-3
- cmd3 "%arg4%"
To clarify a little bit more, we could run tj dev build
, and since our dev
command contains %args%
, that will in turn run the command grunt build
; if
we run tj dev 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.
CONFIG TEMPLATE STRINGS
You may define ERB template strings within a project starter template's Juicefile(5). These will be replaced upon running create(1).
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 creation. The following variables are available for use:
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
ENVIRONMENT
All of the global options have a corresponding ENV
variable that can be set
to permanently use the specified value each time tj(1) is run. This is useful
if you're using an alternate vagrant(1) box, or if you need to disable certain
features due to limited support i.e. on Windows.
TJ_VM_BOX
=repositoryForce vagrant(1) box for use as VM
TJ_VM_PATH
=pathForce path to VM
TJ_VM_IP
=ipForce IP address of VM
TJ_VM_REVISION
=revisionRevision hash or branch to checkout for VM (default is master)
TJ_VM_PREFIX
=stringForce directory prefix for project in VM
TJ_FROM_PATH
=pathRun Juicefile(5) commands from the passed path instead of from the current directory.
TJ_FROM_SRV
=pathRun Juicefile(5) commands from the passed srv path instead of from the current host directory path when
TJ_INSIDE_VM
is enabled.TJ_INSIDE_VM
=boolRun Juicefile(5) commands from inside of the virtual machine instead of your host machine.
TJ_YOLO
=boolSay yes to anything and everything, and maybe even get a few surprises
TJ_BORING
=boolPrints all output without any fancy formatting
TJ_NO_UNICODE
=boolPrints all output without unicode characters
TJ_NO_COLORS
=boolPrints all output without color
TJ_NO_ANIMATIONS
=boolPrints all output without animations (coming soon)
TJ_NO_LANDRUSH
=boolDisable the landrush(1) gem for managing DNS
TJ_NO_PORT_FORWARD
=boolDisable automatic port forwarding
TJ_VERBOSE
=boolPrints out additional logging information
TJ_QUIET
=boolSuppresses all command output
TJ_TRACE
=boolRaises any exceptions caught during runtime
TJ_DRYRUN
=boolRun a command without actually doing anything
TJ_NGINX
=bool