Installation

wp-deploy: Installation

A guide on getting setup with wp-deploy

This guide is broken down into two very similar, yet slightly different sections. Please refer to the section you require below:

Creating a new wp-deploy site
Working with an existing wp-deploy site

Creating a new wp-deploy site

NOTE: Please refer to the requirements section of the README before going through this installation.

Step 1 - Create new remote repository

First of all, create a new empty repository (This means no gitignore or license too!) where you host your git projects.

Step 2 - Clone wp-deploy

We now need to clone down wp-deploy locally into a directory which will be the name for our new project and cd into it. Here's how you do that in Terminal:

$ git clone git@github.com:Mixd/wp-deploy.git <NEW PROJECT DOMAIN> ; cd $_

Step 3 - Install dependencies

We need to install the ruby gems that wp-deploy comes bundled with. To do that, run this bundle command:

$ bundle install --path=.

If you prefer to install the ruby gems to your system instead of the project directory, then remove --path=. from your command

Step 4 - New setup of Git

As we cloned this new project from wp-deploy, we've still got a reference to that remote repository, so if we were to push we would see our changes override the wp-deploy repository, rather than our brand new empty one.

wp-deploy comes prepared with a quick bash script to help us out:

$ ./prepare.sh

Step 5 - Add reference to remote repository

We've now removed the reference to the remote repository for wp-deploy, created a new instance of git with a brand new commit. Lets add the reference to our brand new repository now.

$ git remote add origin <NEW PROJECT GIT URL>

Where is something like: git@github.com:myusername/my-new-project.git

You can give that a try now by pushing up to this repository:

$ git push -u origin master

By default wp-deploy comes equipped with two environments: production and staging. These are setup by default to correspond to the master and development branches respectively. So, when you deploy to staging, you'll be cloning down the development branch.

NOTE: Its recommended that you work within the development branch and then merge into master when 100% ready.

Lets create that development branch and push it up locally.

$ git checkout -b development
$ git push -u origin development

Step 6 - Generic & local config

We need to configure our project. Open config/deploy.rb in the text editor of your choice and edit the following information:

These are used for the WordPress installation:

wp_user: The username of your WordPress administration user.
wp_email: The email address of your administration user.
wp_sitename: The site title of your WordPress installation.
wp_localurl: The local URL of your site.

These are some others used by Capistrano:

application: The name of the temporary folder used by Capistrano when deploying the website.
repo_url: The SSH URL of the remote repository. Capistrano uses this to clone the repository onto the server. (You should not point your vhosts to this URL).

Step 7 - Environment config

Lets now setup our server details now. Within config/deploy/ you'll find two files for the environments we have to work with by default (You can add more). Go onto each of these and enter the following information:

stage_url: This is the URL of what the website will be under in that environment. This should always have the HTTP protocol (http://site.com, https://site.com, etc etc). You'll need to make sure your vhosts on the server are setup for this URL, followed by the current directory.
server: The IP address of the server to connect to via SSH. Each environment can be on a different server, think staging server vs production server, keeping things nice and compartmentalized.
user: The SSH server you'll be using to connect.
deploy_to: The folder on your server where the site will reside.

Step 8 - Database config

Next one is the database details. You'll need to make sure that you have a database locally, as well as for each of your other environments.

You'll see a file called database.yml. This is not stored in Git as it will contain your database details. Within that file, add in your database info and jobs a good un'.

Step 8.5 - Slack integration (optional)

If you don't want Slack integration then skip this step

If like us you work with Slack on a day to day basis, we'd recommend you use the Slack integration provided in wp-deploy. This allows you to setup notifications to a specific channel so that when you deploy it notifies that channel and more importantly, whether or not that deployment was successful. This is great for debugging, especially if you setup a Github integration too.

To go about setting this up, go to config/slack.rb and input the following:

slack_subdomain: The subdomain of your Slack team.
slack_url: The hook for the integration. To get this, you need to setup a new configuration in Slack's preferences.
slack_channel: The channel to show the notifications in. Must be prefixed with a '#' symbol. i.e. #general. At Mixd, we have separate channels for all our clients, i.e. #work_coolcompany, #work_uncoolcompany, this keeps all notifications relevant to that channel only.
slack_emoji: What emoji you'd like the notification to show. When in Slack, click to select an emoji and when you hover over each of them you'll see the code needed. i.e. :stuck_out_tongue:, :poop:. This works with any custom emojis you have setup for your team.

Slack integration is disabled by default, to enable it you need to:

Add this gem 'capistrano-slackify' in Gemfile
Add this require 'capistrano/slackify' in Capfile
Add this require './config/slack' in config/deploy.rb
And finally use this command to install dependancy

$ bundle install --path=.

Step 9 - Local install

We're ready to go! Run the following to set the site up locally:

$ bundle exec cap staging wp:setup:local

You may notice that we're saying staging in that command. Unfortunately Capistrano is only really used for deployment and so any and all tasks require an environment to be referenced, even if not used in this case.

Congrats, if you take a look at your local database you'll notice that the WordPress tables have been created based on your configuration we set earlier. You just need to setup your theme now.

Working with an existing wp-deploy site

NOTE: Please refer to the requirements section of the README before going through this installation.

This section refers to setting up an existing wp-deploy project locally on your computer.

Step 1 - Clone site

First lets clone down the existing repository. As WordPress will be a submodule of this project, we need to make sure to pull any submodules down too. To do this, run the following (notice the --recursive flag):

$ git clone --recursive <EXISTING PROJECT GIT URL>

Step 2 - Install dependencies

We need to install the ruby gems that wp-deploy comes bundled with. To do that, run this bundle command:

$ bundle install --path=.

Step 3 - Setup the configuration files

We need to set up the configuration files. To do that, run this command:

$ ./setup.sh

This will create a copy of the database.example.yml, config.example.rb, production.example.rb and staging.example.rb ready for you to edit. Please ensure these the newly created files are included within your .gitignore

Step 4 - Getting local URL

Go into the config/deploy.rb file and find the reference to wp_localurl. This is the URL you'll need to setup your local vhosts to. As there can be multiple developers working on a project, make sure to keep this consistent otherwise you'll need to keep overriding this everytime you want to do anything.

Step 5 - Database config