Deploy WordPress theme code to your server with git push

Here’s the setup. You’re a good little developer and you’re building your latest WordPress Theme using git to track your changes. You’ve got a local environment where you develop and test edits to your theme file but you don’t have a good way to push those changes to the server. Yesterday I was doing my development using git but using FTP to send updated files to the server, today I simply use git push. Here’s how: 

First I’d like to thank Philip Brown for this tutorial which got me started and this GIST by noelboss which also helped.

Overview

I assume you know a bit about git, aren’t confused by the term SSH, and can work on the command line. What we’ll be doing here is setting up a remote repository on your server, setting it as a remote on your local git project, and configuring a git “hook” to move files to a particular directory on your server when you use git push.

When we are done your workflow will look like this:

git commit -m "latest changes"
git push dev-server master

Then your remote server will have the latest changes! Here are the steps:

  • Create a folder on your server where you’ll keep “bare” git repositories
  • Init a “bare” repository for your project
  • Configure the post-receive git hook to send the latest files to the deployment directory

For the purpose of this example let’s assume the project I’m working on is call “goodgoodproject” and it’s a wordpress theme. I have a local development environment I’ll refer to as “local” and a server that I’ll refer to as “remote”.

If you run into problems, I’ve added a “gotcha” section at the bottom.

Set up the remote server

First thing you’ll need to do is get SSH access to your server. Once you have that I would recommend setting up your ~/.ssh/config it saves so much time, read more about that here. I’ll use normal syntax throughout the tutorial though.

Connect to your server, it would look something like this:

ssh username@hostname.com

If you use a port that command might look like this:

ssh -p 22000 username@hostname.com

Once you’re on your server create a folder in your home directory where your git repositories will live, I called my folder git/ but you could call it anything. We’ll make a empty directory using the mkdir (make directory) command.

mkdir git

Now we want to make a repository for the “goodgoodproject”, let’s change directories using cd (change directory) command.

cd git

This leaves us in our new folder at ~/git/. Next we will use the git init command to initialize a new git repository, but pay attention to what I do here:

git init --bare goodgoodproject.git

I’m initializing a “bare” repository, this means that there aren’t working files just the bare essentials that make up a git repo. I’ve also added goodgoodproject.git to the end, this tells git to initialize a bare repository in a directory of that name. I use the dot git ending just so I can indicate that this directory contains a git repo, you can names yours anything.

Create your deployment directory

This is the directory (on your remote server) where you want your code to end up. In our example I’m working on a WordPress theme called goodgoodproject. So I want it to be in the wp-content/themes/ folder in my web directory on my remote server. Your server might be different so be aware of where you want to write your files! My public html file is where I’ve install WordPress so to create my deployment directory I’m going to use the make directory command like so:

mkdir ~/public_html/wp-content/themes/goodgoodproject

Now there is an empty folder where the files from my git repo will be placed when I deploy them from my local machine!

Setup the post-receive hook

Git has these “hooks” which allow you do perform special action based on actions taken by or upon the git repo. The post-receive hook is activated when git push is done on the repo. This will become more clear as we go on.

First let’s change directory to the hooks folder of our new repository on our remote server.

cd ~/git/goodgoodproject.git/hooks

We are going to create a file in this directory called “post-receive” and put some content in it. To do this we simply have to open the file with a text editor from the command line. I like using nano but you could use vim or anything else. nano is the program on my server (and most UNIX servers) that allows me to edit text, so we’ll use this command:

nano post-receive

We are now in the nano program, it should be mostly black, no text on the inside. We are going to write this simple little sh script. I’ve added comments after # hashtags, these aren’t read by the script, they are for your reference. Except for the first line, the #!/bin/sh is called a hashbang, it tells the computer how to run the following file.

#!/bin/sh
# the target is the deployment directory we created earlier 
TARGET=$HOME/boomtown.goodgoodwork.io/wp-content/themes/wp-theme-boomtown
# the GIT_DIR is the directory where our git repo we made is
GIT_DIR=/home/goodgood/git/boomtown.git
# this is the command we want to run when this hook is fired
git --work-tree=$TARGET --git-dir=$GIT_DIR checkout -f
# finally anything we echo will show up as a message on our local machine when we push to our server!
echo "latest files moved to $TARGET"

A quick note, the $HOME variable is the same as ~ it expands to the home directory of the user. The above code is for a sh script, or shell script. This means that when the post-receive hook files we are simply running a shell script on the server, this means you could do loads of cool stuff when you push to the repo. Right now we are simply running the following command:

git --work-tree=$TARGET --git-dir=$GIT_DIR checkout -f

This is simply using the git checkout -f (force checkout) to put files from the git-dir HEAD into the work-tree path. I’ve used the variable $TARGET and $GIT_DIR to make the code a bit more readable and easy to edit.

Nano editor

Now we save our file. With nano you will press Ctrl+V it will ask you if you want to write, press y then return. Finally we need to make sure our new file can be executed! We are going to run the chmod or Change Mode command on our new file and set it so it can be executed.

chmod +x post-receive

That’s it, now we are ready to go back to our local environment.

Setup the local git repo

I’ll assume you’ve already got your local git repo set up, navigate to that folder. We are going to add a remote repository! From our git repo on our local machine we are adding a remote named server you can, however, name it what ever makes sense to you!

git remote add server ssh://username@hostname.com:22000/git/goodgoodproject.git

This looks a bit complicated, let’s break it down. The first part is a normal git command to add a remote repo, you’ve probably done this with a service like github.com, that’s the git remote add server part.

Let’s look now at the remote url we are using. It starts with ssh:// this simply tells git to use SSH as the protocol for connecting to the server. Next comes the username this is what ever your SSH account’s user name is. Then we have @hostname.com, typically this is the server’s web address, but it might be the IP address. Followed by :22000, this is the port, sometimes you need a port, sometimes you don’t, I just wanted to make sure you knew what it looked like. After that we have /git/goodgoodproject.git you should recognize this as the path to the git folder you initialized earlier!

Because I use an ssh config alias my remote url is much easier:

git remote add server goodgoodwork:git/goodgoodproject.git

Just remember that you need a colon between the SSH address and the path to your remote git repo.

Great, now the local repo has a new remote called server. All you’ve got to do now is push to it!

git push server master

This will push the master branch to the server url! Once it lands on the server a program called git-receive-pack will trip the post-receive hook and fire the shell script to add the files to our deployment directory!

Gotchas!

There are a few places where things could go awry, let’s look at them:

git-receive-pack: command not found

You do your git push from the local machine and get the following error:

bash: git-receive-pack: command not found
fatal: Could not read from remote repository.

This means that the git-receive-pack command couldn’t be found on the remote server. I use Namecheap hosting (and so should you) which for what ever reason do not add this command to the PATH by default. They provide a simple fix where you add the folder where 3rd party programs live on their server to your PATH file via .bashrc file. I won’t go into that, but you should be able to figure out a solution to your environment based on this.

You need to test if git push works

When I was setting this up I kept running into the problem where I’d do a git push, something wouldn’t work, I’d fiddle around on the server then want to test again but when I did another git push I’d get:

“Everything up-to-date”

There was an easy way to get around this, just add a dummpy commit:

git commit --allow-empty -m 'push to execute post-receive'

It adds useless commits to your history, but who’s paying that any mind?

Conclusions

I hope you found this helpful, if you learn of any more gotcha’s I’ll add them. I would love to hear how other people use this and other hooks.

Oh yeah! I also wrote a little bash script that you can put on your server to generate these git repos with ease.

Building a Custom Ticketing System with Free Tools

The People’s Summit 2017 asked Good Good Work to develop a ticketing system that could circumvent third-party websites such as Eventbrite while making the event more inclusive and diverse. While helping them save a pretty large sum of money, we also saved them a lot of time by automating parts of the system they didn’t think they could.

There were three main parts to this system:

  1. Applications system – We needed to create a step in the application process that would involve partner organizations first, before moving accepted applications on to the registration process, starting with the gateway.
  2. Registration Gateway – Once an applicant was approved, the website needed a way to verify their acceptance before letting them buy a ticket. We also needed to be sure that the applicant’s data—such as a registration code—hadn’t already been used to buy a ticket before.
  3. Sales system – Once an accepted applicant was through the gateway, we needed a way for them to purchase their ticket.

Step 1: The Application System

The first step in the process was to develop an application system. To do so, we created a Google Form for each partner organization, giving their staff access to it. Google Form results flowed into a Google Spreadsheet—called the form results spreadsheet—that had an additional column for marking entries as accepted. Columns can be added to a form results spreadsheet without impacting the attached form.

A form response spreadsheet with a row being marked as "TRUE"
A form response spreadsheet with a row being marked as “TRUE”

We knew organizers and staff would be familiar with spreadsheets, which is why we used such a tool.  Additionally, we used data validation and protected cells to make errors even less likely.

This system was not in the original scope. As we were working closely with organizers and talking to them about the system in a holistic way, we learned about their plans to do much of the following by hand. Alerted to the inefficiency of their plan, we developed systems that saved countless staff and volunteer hours.

Once these forms were prepared, we set to work on the master spreadsheet. This Google Spreadsheet would ingest all other partner organization spreadsheets and pull out names, emails, location, and other data of applicants who had been marked as accepted on the corresponding application results spreadsheet. It would then assign them registration codes.

Summit organizers would gather batches of emails to send—via their existing email marketing platform—to applicants who had been accepted. Applicants would find in the email their registration code and a link to the registration gateway (which used a URL parameter to automatically populate the gateway input).

Some clarification about sheets and spreadsheets: a spreadsheet can contain multiple “sheets” that will show up as tabs on the open spreadsheet.

The workflow looks like this:

  • User fills out the application of a summit partner organization, for example Food and Water Watch.
  • The form results show up as a row of data on Food and Water Watch’s form result spreadsheet.
  • A staff member from Food and Water Watch marks the user’s application as “accepted” by setting the cell under the “accepted” column as TRUE.
  • On the Food and Water Watch sheet (or tab) within the master spreadsheet, the rows marked accepted would be imported automatically.
  • All the accepted applicants records would automatically flow into another sheet (tab) within the master spreadsheet called the “feed” sheet.
  • Staff would copy entries from the feed sheet and paste them into the master sheet within the master spreadsheet.
  • Once the rows of accepted applicants were placed into the master sheet (tab) they would automatically be assigned registration codes.
  • Staff would then send an email to the accepted applicant’s email with that registration code.
  • Once the registration code was used to purchase a ticket it would be marked as used on the master sheet (tab) of the master spreadsheet.

Importing data from one Google Spreadsheet into another

There is a function in Google Spreadsheets called IMPORTRANGE(). It accepts two parameters, a spreadsheet “key” and a range (e.g. A2:C5). The key is the alphanumeric string within any spreadsheet’s URL:

docs.google.com/spreadsheets/d/1Kwiz0eiY_ADysLMrPqycty2CcH-cBjsl7XodVB2v02g

Using IMPORTRANGE inside the QUERY function allowed us to pull and sort the data. There was a sheet for each partner organization’s spreadsheet of applicants within the master spreadsheet. The QUERY function looked like this:

"SELECT Col2, Col3, Col4, Col5, Col6, Col7, Col8, Col9, Col13, Col14 WHERE Col1 = TRUE and Col2 is not null"

The Col# refers to the data column of the range of spreadsheet data selected by IMPORTRANGE. For example, if one imported C:Q (columns C through Q) Col1 would be C, Col2 B, and so on. As such, the SELECT section is “selecting” only the listed columns of data to display.

The WHERE clause tells the QUERY which rows of data to pull in. Only data where Col1 is true and Col2 is not null is pulled in. Col1 was the “accepted” column, meaning that only records that a staff member had marked “TRUE” would match the query. Col2 related to the timestamp column. We did this to limit the results to only the rows of data that contained actual data in them, knowing rows with data were sure to have a timestamp.

Within the master spreadsheet was another sheet called “feed.” It used the QUERY function to pull all accepted entries into a single list.

The feed list used conditional formatting to mark duplicate entries. From here, organizers would copy and paste rows of data into the master sheet. This part, and marking a particular applicant as “accepted,” were the only direct human intervention in this whole process.

The Master Sheet

This is where the real magic happened.

Once blocks of data were pasted in (starting at row E in the above image) a formula would generate a unique “regcode” by combining the name and timestamp of the rows data. This code would then be used by the registration gateway plugin installed on the summit’s WordPress website.

The Registration Gateway

We decided to use a WordPress plugin to manage ticket sales. The challenge was that it would have to handle our gateway on the Summit’s WordPress website. To accomplish this, we locked anyone without a valid registration code out of the ticket sales pages. To gain access, a visitor would have to input a registration code that would need to be checked against the master spreadsheet.

We had to get a form on WordPress to talk to a Google Spreadsheet. To do this, we created a custom WordPress plugin that used the Google Sheets API to check the input value of a form.

The gateway plugin also handled the logic for marking registration codes as used on the master sheet. Watching a spreadsheet magically fill in data as users purchased tickets was a cool sight.

Furthermore, it would block users from using the same code twice while simultaneously pulling data – like a name and email address – into WordPress to auto-fill form fields. It made life easier for the user.

Ticket Sales

The final step, once the accepted user had entered their registration code, was the actual purchase of the ticket. We opted for the WordPress Plugin Tickera. It was not only able to handle credit card payments but also generated printable tickets, and had tools for registration on the day of – such as a downloadable app that would allow organizers to scan tickets either printed or off people’s phones.

By using Tickera’s WordPress hooks, we were able to fire functions within our gateway plugin when tickets were successfully purchased. This marked the corresponding registration code as used.

While the plugin worked out-of-the-box, we spent a considerable amount of time to fit it into the existing theme used by the Summit’s website. I thoroughly enjoyed the challenge of it.

Putting it all together

Building the system is just the beginning. Once we had everything in place, we tested for all kinds of edge cases, made on-the-fly updates as the requirements changed, and produced a load of documentation for organizers so that they could use the system effectively. Bonus: organizers were also were able to spit out real-time demographic reports!

In the end, we were able to solve some complex problems with elegant solutions in a short time frame. We hit a constantly moving target, for which I am very proud. By stepping back from the problem and taking our time to thoroughly examine the solutions we were able to save many hours of labor as well as thousands of dollars.

I’ve only touched on the technical detail of how this was implemented. If you’re interested in other details about any parts of this process please leave a comment below.

The post Building a Custom Ticketing System with Free Tools appeared first on Good Good Work.