Datadog php-fpm monitoring via nginx

It took me some time to get this set up properly, but here are my configs that finally worked to get php-fpm monitoring using datadog.

1. nginx vhost config

First, make sure you override your site’s hostname to localhost. For my site this is to make sure connections don’t go out to cloudflare but stay local on the server: /etc/hosts needs to contain this line.

127.0.0.1 www.karelbemelmans.com karelbemelmans.com

I use my port 80 vhost config for the status page. Cloudflare enforces SSL so this vhost never gets used for anything non-local on my server.

server {
  listen 80;
  listen [::]:80;
  server_name www.karelbemelmans.com karelbemelmans.com;
  server_name www.karelbemelmans.be karelbemelmans.be;
  access_log /var/log/nginx/www.karelbemelmans.com/access.log main;
  error_log /var/log/nginx/www.karelbemelmans.com/error.log error;
  location ~ ^/(status|ping) {
    access_log off;
    allow 127.0.0.1;
    deny all;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass php_www.karelbemelmans.com;
  }
}

I use “php_www.karelbemelmans.com” as fastcgi_pass value. This is defined in another file on the conf.d dir and matches the socket definition in the php-fpm pool config file.

/etc/nginx/conf.d/upstream-www.karelbemelmans.com.conf:

upstream php_www.karelbemelmans.com {
 server unix:/var/run/php-fpm/www.karelbemelmans.com.sock;
}

(This setup is inspired by Mattias’ config for the Nucleus customers)

2. php-fpm pool config

Make sure these 3 lines are present in your php-fpm pool config:

pm.status_path = /status
ping.path = /ping
ping.response = pong

Normally your acl should be fine as requests will come from localhost.

3. Datadog config file

So nginx and php-fpm are configured, all we have left is the datadog config file:

/etc/dd-agent/conf.d/php_fpm.yaml:

init_config:
instances:
 - # Get metrics from your FPM pool with this URL
   status_url: http://karelbemelmans.com/status
   # Get a reliable service check of your FPM pool with that one
   ping_url: http://karelbemelmans.com/ping
   # Set the expected reply to the ping.
   ping_reply: pong

Reload nginx, php-fpm and datadog-agent after that and your php-fpm tracking should now work. This tracks only 1 pool, it’s up to you to figure out how to track multiple pools now :)

Belgium for Dummies

For my Swedish friends: This is Belgium.

Useful bash one liners

Disclaimer: These are extremely simplified one liners that do not perform any form of input validation or character escaping. You should not use this in a ‘hostile’ environment where you have no idea what the input might be. You have been warned.

This is a list of some bash one liners I use on a daily basis during development and problem debugging. I made this list as a “you might not know this one yet” and will continue to update it every now and then.

Latest update: 2016/06/18.

Running a command on multiple files at once

This is a basic structure we will be re-using for the other examples. Run a command on all files in a directory:

for FILE in $(ls *); do command $FILE; done

Run a command for all lines in a file:

for LINE in $(cat file.txt); do command $LINE; done

Warning: As noted in the comments, this assumes there are no spaces in the lines in your file. If they do contain spaces, you need to add proper escaping using quotes.

Make certain things easier to read

Format a local XML file with proper indenting:

xmllint --format input.xml > output.xml

Run this script on all XML files in a directory:

for FILE in $(ls *.xml); do xmllint --format $FILE -o $FILE; done

Monitor new lines at the end of a log file and colorize the output (requires the package ccze):

tail -f /var/logsyslog | ccze

Find a specific text in a lot of files

Find a text inside a list of files and output the filename when a match occurs. Recurse and case-insensitive:

grep -irl foo*

Count the amount of files in a directory:

cd dir; ls -1 | wc -l

Find a filename that contains the string “foo”:

find ./ -name *foo*

Find all files modified in the last 7 days:

find ./ -mtime -7

And similar all files that have be modified more than 7 days ago:

find ./ -mtime +7

Modify files

chmod 644 all files in the current directory and below:

find . -type f -exec chmod 644 {} \;

chmod 755 all directories in the current directory and below:

find . -type d -exec chmod 755 {} \;

Commandline JSON formatting and parsing

The JQ command is a must-have for anything that returns JSON output on the command line:

curl url | jq '.'

I use this for finding the latest snapshot in a snapshot repository for elasticsearch:

curl -s -XGET "localhost:9200/_snapshot/my_backup/_all" | jq -r '.snapshots[-1:][].snapshot'

Actions against botnets and spammers

Find a list of all bots using a guestbook script to spam a site (that sadly has no captcha). I run this on the apache access_log file:

cat access_log | grep POST | grep guestbook | awk '{print $1}' | sort | uniq > ips.txt

The ips.txt file will now contain a list of unique ip addresses I want to ban with iptables:

for IP in $(cat ips.txt ); do iptables -I INPUT -s $IP -j REJECT; done

Cleanup stuff

Delete all but the 5 most recent items in a directory. I use this in Bamboo build scripts to clean up old releases during a deployment:

ls -1 --sort=time | tail -n +6 | xargs rm -rf -

That’s all for now!

Automated Drupal 7 deployments with Atlassian Bamboo

Update 2016/06/18: I finally fixed the markup of this post after migrating from WordPress to Hugo. I also fixed some typo’s and updated this post with some current information. Even though almost a year has passed since writing it, this post is still relevant for the current 5.12 version of Bamboo.

If you are reading this post you probably already know what automated deployment is and why it’s important. I’ll probably write a blog post about that subject in the near future but first I’m going to write this one about doing automated Drupal 7 deployments with Atlassian Bamboo.

This blog post is not going to be a discussion what the best deployment system is. Some people like capistrano, some people like jenkins, some people like Bamboo. For us at Nascom Bamboo works pretty well because it integrates perfectly with JIRA and Bitbucket, allowing us to view linked JIRA issues when making a build and see what on wich environment a JIRA issue has been deployed.

This is a pretty big blog post, so take your time to go through it.

Bamboo in action

Before I dive into the details about the setup I’ll first show you a 4 minute screencast with some minimal comments how the whole setup works. This gives a nice global picture so you have a better understanding of the steps that come next.

Prerequisites

For this blog post I’m going to make some assumptions about your development setup and Drupal site structure:

  • You have a running Bamboo server, either as a dedicated server or just running on your own computer. The version I’m using for this blog is 5.9.3 build 5918 - 28 Jul 15. You could also use the Bamboo On Demand service from Atlassion if you don’t want to setup your own server.
  • The Bamboo server can access your deployment target environment over an ssh connection.
  • Our Drupal source code is in a git repository that can be accessed by the Bamboo server. In my case it’s hosted on Bitbucket
  • Your Drupal site uses the env.settings.php structure I described in a blog post on the site
  • Drush has been installed on the target environment so we can run drush cc all and drush updatedb if needed.

Right, now let’s dive into the setup.

Bamboo concepts

First you need to get used with some Bamboo concepts (also see the official Atlassian Bamboo documentation):

Build plans and artifacts

A build plan is the process that generates a Bamboo artifact. An artifact is something that can be deployed later, most of the time an executable or a jar file when you are talking about software that compiles, but for our Drupal site this will simply be a compressed tar file called drupal.tar.gz that contains the Drupal source code.

Build plans are composed of three pieces: Stages, Jobs and Tasks. If you look at the graph below it should be clear how those three fit inside each other:

Bamboo Build Plan Anatomy

  • Stages execute sequentially (e.g. a Testing Stage, a Package Building stage). If phase x fails, the build process will halt and phases after x will not be executed.
  • A stage consists of jobs that can be executed in parallel (e.g. multiple types of tests in a testing stages that can run at the same time)
  • A job consists of multiple tasks that run sequentially. The first task will always be doign a source code checkout and then the next tasks use this checked out code to do some magic.

As I wrote above, the result of a build plan will be an artifact that we can use for deployment later on.

Releases, deployment plans & environments

Now that we have a build plan that produces an artifact, our drupal.tar.gz file, we need to get that deployed to our servers. We can use releases and deployments plans to achieve that:

  • Releases are simply tagged successful build plans. E.g. build #65 has been tagged as release-2.2.0.
  • A deployment plan is simply a list of environments.
  • An environment has a list of tasks that will be executed sequentally to deploy a release’s artifact to the environment.

A real life example project

I’m going to take my own Narfum IT Services website as an example deployment project. It’s a Drupal 7 site that will be deployed to a staging and a production environment.

Update 2016/06/18: This narfum.eu site is now offline, but the example is still valid.

A Drupal site can always be split into three pieces:

  • Drupal PHP source (Drupal core + all contrib and custom modules and themes)
  • Database
  • User uploaded content (sites/default/files)

If you follow my env.settings.php setup structure for Drupal 7, it’s easy to keep these 3 separated.

Our Bamboo deployment plan will only handle the first item, the Drupal PHP source. This codebase will be stored in our version control system.

The database will most of the time be deployed one time, and then updated via update hooks in Drupal. These update hooks will be run by our deployment plan (via drush updatedb), so it’s not needed to include an automated database deployment.

The user uploaded content is located outside of the Drupal PHP directory, so we can just leave that alone during deployment and just make a new symlink to it. Sidenote: you never commit this content to your version control software!

The build plan

What a build plan comes down to in practice is simply put:

  1. Download the source code
  2. Do some local modification to those files
  3. Package the result as an artifact.

This means that whatever you put in git, is not necessarily going to end up on your deployment environment. For a Drupal website this means we can do a lot of handy things during the build phase:

  • Remove unwanted files developers forgot to remove from git (e.g. remove CHANGELOG.txt and the other .txt files)
  • Compile SASS code to CSS in production mode instead of development mode
  • Remove sources and development files (SASS code, maybe PSD’s you added in git, development modules like devel and coder )
  • Add modules from another repository you need to make sure exist on production sites (e.g. modules like prod_check which is nice to have on a production environment)
  • Or ofcourse remove development modules that should not be deployed to production (e.g. devel, coder, …)
  • And maybe other things specific to your project

It will take you some time to setup all of this and make it error proof, but after that you have a fully automated build system that will never forget a single thing!

Creating a build plan

Ok, let’s start by creating a Build plan. From the “Create” menu at the top chose “Create new plan” and fill in the fields like in the screenshot below. Do not chose a version control system here yet, we’ll add that later. (If you add it here, it will be a global repository and we don’t want that).

(Click the image for a larger version)

Create a new Bamboo build plan

On the next screen just check “Yes please!” to enable the plan and click Create. We will add the tasks later, we just want an empty build plan for now. When we have our empty build plan, go to “Actions” on the right side and chose “Configure plan”. You will get the screen below (click the image for a larger version):

Configure a Bamboo build plan

As you can see Bamboo has made some default items for us: A “Default stage” stage with one job called “Default Job”. We will use these defaults for this example and just add tasks inside this one job.

Connect our git repository

As we need to do git checkouts in more than one task, we will add our Drupal git repository as a local repository for this project. On the build plan configuration page go to the “Repositories” tab and click “Add repository”:

(Click the image for a larger version)

Add a source code repository

It should be pretty obvious what you need to fill in here.

The easiest way to connect to Bitbucket is with the “Bitbucket” option, but that requires entering a password and I don’t like that. So I always chose “Git”, enter the ssh location for the Bitbucket repository and use an ssh private key to authenticate. But chose whatever method works for you.

It’s important that you chose the “master” branch here as that will be the main branch for our builds. Master should always be the code that goes onto production, so try to keep that best practice for your projects too.

If you want to read about a proper git branching model for your development, be sure to checkout the Git branching model.

Add build tasks

The last thing we have to do now is add tasks that will actually do things for us. Below is a screenshot of the real Narfum project (that has 2 stages instead of 1 but we will ignore the test stage for now) where I’m currently showing you the “Package Drupal” job.

(Click the image for a larger version)

Package Drupal job

There are 3 jobs:

  • A “Source Code Checkout” task: Checkout code from Bitbucket to a local directory on the build server
  • A “Script” task: Do some magic (in this case simply compile sass code to css)
  • A “Script” task: Make a tar.gz file

The first step will always be a source code checkout. Remember that jobs can run in parallel and they are sandboxed in their own directory. So one job does not know about another job’s files, meaning you always have to checkout files (or important an artifact) as the first task in a job.

The 3 tasks in detail:

Task 1: Checkout source code from our repository.

These files will be downloaded in the root directory of our job and will be available to be modified for the remaining tasks.

(Click the image for a larger version)

Task 1: Source Code Checkout

Task 2: Magic

Once we have the Drupal code, we can do a lot of things to modify this code. We keep it simple here and just do a production compile of the SASS files for our theme:

(Click the image for a larger version)

Task 2: Magic

Notice the “Working sub directory” at the bottom! This points to the main theme directory.

Task 3: Create Drupal tarball

The last task is always creating a Drupal tarball of our files now that we’re done with modifying them:

(Click the image for a larger version)

Task 3: Create tarball

I prefer to exclude files like the “node_modules” directory rather than removing them so a new build won’t have to download them all again. (I know they are cached in the bamboo user’s homedir yes, but it’s the idea that counts here: we don’t want to re-do too many things for new builds).

After those 3 tasks are done, we will have a drupal.tar.gz file in our root directory. We now need to make this available as a shared artifact so our deployment plan can use it.

The last build step: create the artifact

In the “Package Drupal” stage, go to “Artifacts” and add a new artifact definition:

Artifact overview page:

(Click the image for a larger version)

Artifact overview

Artifact detail page:

Artifact definition

Make sure the “Shared” box is checked, otherwise it will not be available to our deployment project!

And that’s all there is do to for a Drupal build plan. If you run this build now from the “Run” menu and then “Run plan” you should get a green page saying the build was successful. You will also be able to download the artifact manually at the bottom of the page.

This next screenshot is an example build result page from the Narfum website project. You can ignore the right upper box for now, in your project that will be empty as you don’t have a linked deployment project yet:

(Click the image for a larger version)

A successful Bamboo build

The deployment plan

Still with me after the build plan setup? Good. Because now it’s time to deploy our code to an actual environment.

Create a deployment plan

A deployment plan is nothing more than a container for multiple deployment environments. From the “Create” menu chose “Create deployment project” and fill in the screen like in the screenshot below. Make sure you select the right build project you are attaching to this deployment plan:

(Click the image for a larger version)

Create a deployment plan

After that you will see the configuration page of our empty deployment plan.

Creating enviroments

Now chose “Add environment” and simply give it a clear name. I always go for the structure “$hostingprovider - $env_type” so this could be “AWS - Production”. Click on “Create and configure tasks”.

This will be our production environment but you can of course add a staging environment and testing environment too. Using the “Clone environment” option after our production environment is finished this is very fast to setup.

You should now see the screen below. This is a similar list of tasks you saw on the job configuration page for a build plan:

Create deployment tasks

There are 2 tasks made for you already, which you should always leave as first two tasks for your deployment project: the clean working directory and the artifact download. These tasks make sure you have an empty work directory with just our drupal.tar.gz artifact file.

The next tasks will then be using this drupal.tar.gz file and get it on our target environment. The exact tasks in our deployment will be:

  • Copy the tarball to the target environment via scp
  • Extract the tarball to a new release directory
  • Added the needed symbolic links
  • Run databases updates (if needed)
  • Set this new release as the new live version
  • Run cache clears
  • Clean up older releases

This is what it will look like when we’ve set up all these tasks (I’ve switched to my Narfum website deployment plan again now for these screenshots):

Completed deployment environment tasks

Environment variables

Before we continue with the tasks, we first need to setup some variables. End your task setup process and go back to the deployment plan page. You will get an incomplete task warning but just ignore that for now.

Unfinished deployment environment

Click the “Variables” button at the bottom and add the variables “deploy.hostname” and “deploy.username” with the values needed for your server:

Deployment environment variables

We can now go back to configure our environment tasks.

Environment tasks

Remember that tasks inside a job can halt the deployment process if they fail? That’s the main reasons we split up all these things into separate tasks.

Task 1: Copy the artifact to the remote server

This is adding a “SCP Task” where you simply copy the artifact to the remote server. We can use the variable “deploy.hostname” as “${bamboo.deploy.hostname}” inside tasks, the same goes for “deploy.username”.

I’m also not using a password but ssh keys to login to the remote server. Sadly you have to upload the private key in every task, this is one of the few shortcomings Bamboo still has.

Task 1: Copy the artifact to the remote server

Task 2: Extract the tarball on the remote server

This tasks uses the “SSH Task” type we will be using for the rest of the tasks. It simply allows you the enter shell commands that will be executed on the remote server over an SSH connection.

This task makes a new release directory inside the “releases” directory on the server, extracts the tarball there and then deletes it again.

Task 2: Extract the tarball on the remote server

In this task we add the symbolic links to our env.settings.php file and our sites/default/files content. See this blog post how and why we do this.

Task 3: Update symbolic links

Task 4: Databases updates

This task is currently not present for my project, but you can easily add it here yourself. Make the same SSH Script as above and use whatever drush commands you would like.

The idea for this task is:

  • Your Drupal code has all the needed hook_update_xxx() to upgrade your database schema, enable modules, set variables etc
  • Bamboo runs a simple drush updatedb command and all those update hooks get executed

Task 5: Set this new version as the live version

This simply makes the “www” folder, which is the Apache or nginx document root, a symbolic link to the newly uploaded release folder:

Task 5: Set the new uploaded version as the live version

Task 6: Cache clear

Because this is always a good thing to do.

For most of my project I also do a sudo php-fpm reload here, to make sure the PHP opcache is cleared, but permission to execute that command needs to be set up on your server first and is outside the scope of this blog post.

Task 6: Cachec clear

Task 7: Clean up older releases

This is a nice to have task. For production environments we mostly do this manually when the server raises a disk space warning, but for testing and staging environments this can be automated.

This script only keeps the last 5 recent deployments (determined by the timestamp of the release folder) and deletes the rest. The chmod command is needed because Drupal removes the write flag from the sites/default folder:

Task 7: Clean up older releases

And that’s all for the environment tasks.

Running a deployment

Now that we have a working build plan with a linked deployment plan we can run a deployment. The steps we have to do are always:

  • Push your code to the master branch.
  • Run your build plan.
  • If the build is successful create a release on the build result page. Otherwise fix your code and go back to step 1.
  • Deploy this release to an environment.
  • Check if everything is working

You probably made some errors in your config along the way. Luckily Bamboo will show you a nice big log file where you can debug your problem, so go ahead and test with your own projects now. Your automated Drupal deployment setup is now finished!

Sidenote: Using Triggers it’s possible to automate deployments whenever a build runs successful. That might be a good thing to do for automated deployment to a dev or test environment, but for a production environment you still want to keep that a manual task.

Room for improvement

This blog post of course only shows a very simple deployment setup. To keep this blog post somewhat short I only covered the basic steps in creating the whole deployment setyp. It’s up to you to extended these build and deployment plans for your own project.

Here are a few pointers what can still be improved:

  • Use build scripts (e.g. Ant or Maven tasks with a build file) instead of Bamboo SSH scripts for you tasks. This makes re-use of deployment scripts easier and also adds them to your version control system instead of being hardcoded into Bamboo. Bamboo has special tasks for running these build scripts.
  • Add more tests in the build and deployment phase. Make them proper Unit tests and Bamboo will display them in a special tab in a build, making it easy to see how many of your tests failed.
  • While it’s not possible to run actual tests during deployment phases, you can write deployment tasks that have a fail status (when the script exit code is any other number than 0) to halt a deployment that didn’t got as expected.
  • Almost every step of a build or deployment can have triggers and notifications. You can use these to schedule builds, automate deployments on a successful build and to send out mails or Hipchat/Slack notices when a build or deployment has succeeded.
  • Add more branches. A build plan can have multiple branches so you can build your project from other branches than the master branch. Bamboo can even auto-detect and auto-build these branches using triggers.

There is also a big marketplace of plugins for Bamboo, free and commercial ones, that make your life easier.

Newer versions of Bamboo will most likely add more useful features, so make sure you keep upgrading your Bamboo installation to the latest version.

The end.

That’s all folks, I hope you learned something useful from this post. Use the comments section if you have any questions or remarks!

A better alternative for using phpMyAdmin

Almost every week I run into at least one production site that has a phpMyAdmin installed in the document root of the site, or as a separate vhost on the server. While this used to be pretty required in 2005 to make changes to the database in production, now in 2015 we have better ways to do that.

The problem

The reason phpMyAdmin is installed on the website is that the MySQL server only listens on localhost via a UNIX socket, or on the loopback interface 127.0.0.1 via tcp. That way it’s impossible to connect to it from a remote address.

The bad thing about this is that we have an extra web application on our site we need to take care of. These phpMyAdmin installs are often never updated and might contain security issues that allow attackers to gain access to you production database.

A better alternative: SSH tunnels

If your server is reachable via SSH (even via a VPN connection) we can use a better method: SSH tunnels.

How this works is pretty simple:

  • We connect to our server via an SSH connection
  • Over this SSH connection we set up a tunnel with a port forward that allows a SQL client on our own computer to use the remote database as if it was a local connection

This might sound complicated, but there are a lot of SQL clients available that do this SSH tunneling for you. Below is a screenshot from Sequel Pro for OSX:

Sequel Pro for Mac OSX

You can see 2 things here:

  • the MySQL connection (which always connects to 127.0.0.1)
  • the SSH connection (which is your normal SSH login)

Once this connection has been setup the SQL client works just as it would on a local connection.

SQL clients that support tunneling

These are the clients I use on a daily basis:

  • OSX: Sequel Pro
  • Linux, Windows & OSX: MySQL Workbench
  • And ofcourse using the mysql commandline program in an SSH connection (mostly via drush sql-cli when it’s a Drupal website)