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-deploy
- Deploy a project
SYNOPSIS
tj deploy
stage [command] [--flag=arg] [--flag]
DESCRIPTION
Deploys a project to the passed stage
. All commands are transformed and then
piped directly to capistrano(1) to handle deployment.
REQUIREMENTS
The remote
that is being deployed to needs to have wp-cli(1) installed in
order for tj(1) to be able to handle database migration.
SETUP
Follow these steps to quickly get up and running:
- Create a
deploy
user on thestage
server - Set up SSH keys for the new
deploy
user for password-less SSH access - Confirm the
deploy
user owns the deploy path - Run
tj deploy <stage> setup
to setup the required directories - Deploy!
GLOBAL OPTIONS
-b
,--branch
=branchUse an alternate git(1) branch for current deployment
--archive
,--tar
,--gzip
,--zip
Archive directories with tar(1) when performing file transfers
PRIMARY COMMANDS
If no command is passed, the default task to be executed is deploy
deploy
Deploy a project
rollback
Rollback a previous deployment
setup
,check
Run a preliminary deployment check, making sure that all necessary folders are created and accessible on the passed
stage
SECONDARY COMMANDS
db:backup
Back up the database on the passed
stage
and store it locally in thedeployment.stages.vagrant.backup
directorydb:pull
Pull the database from the passed
stage
and import it into the development environmentdb:push
Push the database from the development environment and import it into the passed
stage
env:pull
Pull the current
.env.<stage>
file from the passedstage
to the development environmentenv:push
Push the current
.env.<stage>
file from the development environment to the passedstage
uploads:pull
Pull the current
stage
's uploads folder from the passedstage
to the development environmentuploads:push
Push the uploads folder from the development environment to the passed
stage
's uploads folderfile:pull
=pathPull a relative file from the passed
stage
to the development environment.file:push
=pathPush a relative file from the development environment to the passed
stage
.dir:pull
=pathRecursively pull a relative directory from the passed
stage
to the development environment.dir:push
=pathRecursively push a relative directory from the development environment to the passed
stage
.
CONFIG FILE
The YAML Juicefile(5) configuration may be used to store deployment-related settings. Below you will find the various options you can use to define your project's deployment setup.
deployment
Deployment configuration
deployment.application
Application settings passed directly to capistrano(1)
deployment.settings
Deployment settings passed directly to capistrano(1)
deployment.repository
Repository settings passed directly to capistrano(1)
deployment.rsync
Optional settings passed to capistrano-rsync(1); mapped as
rsync_<setting>
during the deployment initializationdeployment.slack
Optional settings passed to capistrano-slackify(1); mapped as
slack_<setting>
during the deployment initializationdeployment.stages
Deployment stages
deployment.stages.<stage>.server
Domain or IP address of the server; can include an optional port number in the form of
<ip_or_domain>:<port>
deployment.stages.<stage>.path
Root path to the deployment directory
deployment.stages.<stage>.user
User account to deploy as (it is recommended not to use
root
)deployment.stages.<stage>.url
URL of the stage
deployment.stages.<stage>.uploads
Relative path from deploy path to the uploads folder
deployment.stages.<stage>.tmp
Relative path from deploy path to the tmp folder
deployment.stages.<stage>.shared
Sequence of relative files from application root to place inside of the shared folder. Files that end with a trailing forward slash are assumed to be a directory.
deployment.stages.<stage>.roles
Sequence of deployment roles for the stage
deployment.stages.vagrant
Required development environment settings; these are used for database and file migration
deployment.stages.vagrant.server
Domain or IP address of the development environment
deployment.stages.vagrant.path
Root path to the application directory within the VM
deployment.stages.vagrant.user
User account to deploy as (usually
vagrant
)deployment.stages.vagrant.pass
Password for the user (usually
vagrant
)deployment.stages.vagrant.url
URL of the project
deployment.stages.vagrant.uploads
Relative path from application root to the uploads folder
deployment.stages.vagrant.backup
Relative path from application root to the backup folder
deployment.stages.vagrant.tmp
Relative path from application root to the tmp folder
deployment.stages.vagrant.roles
Sequence of roles for the development environment
Below is an example deployment configuration:
# Project configuration
project:
name: example
# Deployment configuration
deployment:
# Repository settings
repository:
repo_url: git@github.com:example/example-app.git
branch: :master
scm: :rsync
# Other settings that will be passed directly to Capistrano
# @see http://capistranorb.com/
settings:
keep_releases: 5
format: :pretty
log_level: :verbose
use_sudo: false
ssh_options:
keys: ~/.ssh/id_rsa
forward_agent: true
paranoid: true
# Add additional directories to $PATH. This is useful if you're
# on a shared hosting environment (i.e. GoDaddy) and you need
# to use an executable such as wp-cli for database migration.
default_env:
path: /opt/wp-cli/bin:$PATH
# Capistrano rsync options and install procedure
# @see https://github.com/Bladrak/capistrano-rsync
rsync:
stage: tmp/deploy
cache: shared/deploy
scm: :git
depth: 1
# Options to pass to the rsync command
# @see http://linux.die.net/man/1/rsync
options:
- --recursive
- --delete
- --delete-excluded
- --include="vendor/**/*" # Overrides any excluded patterns
- --exclude="node_modules/"
- --exclude=".env.sample"
- --exclude=".git*"
- --exclude="Juicefile*"
- --exclude="composer.*"
- --exclude="package.json"
- --exclude="README.*"
# Run application install scripts
install:
- composer install --no-dev
- bundle install
- npm install
- bower install
- grunt build
# Run scripts before the deployment starts
pre_scripts:
- touch .maintenance
# Run scripts before the deployment finishes
post_scripts:
- rm .maintenance
- sudo service apache2 restart
# Slack integration
# @see https://github.com/onthebeach/capistrano-slackify
slack:
url: https://hooks.slack.com/services/your-token
username: Deploybot
channel: "#devops"
emoji: ":rocket:"
# Deployment stages
stages:
production:
server: 192.168.13.37:1234
path: /var/www/production
user: deploy
url: example.com
uploads: app/uploads
tmp: tmp
shared:
- .env.production
ignore:
- robots.txt
roles:
- :web
- :app
- :db
staging:
server: 192.168.13.37
path: /var/www/staging
user: deploy
url: staging.example.com
uploads: app/uploads
tmp: tmp
shared:
- .env.staging
roles:
- :web
- :app
- :db
# This is your development environment used to push/pull database files,
# uploads, the .env file, etc.
vagrant:
server: example.dev
path: /srv/www/tj-example
user: vagrant
pass: vagrant
url: example.dev
uploads: app/uploads
backup: backup
tmp: tmp
roles:
- :dev