Image for post
Image for post

Convert an old PHP 5 web application to Docker

Take an old PHP 5 web application and convert it to Docker containers, using the latest PHP 7, Composer, Node.js, Grunt, and Bower.

Backstory

PHP was always the go-to language for me. I started exploring PHP in 2000, around the time of PHP 4 launch, in an effort to convert an increasingly popular website that was written as lots of individual, static HTML pages. I began work on writing a Content Management System from scratch, and the CMS was still distributing 30,000 articles some 17 years later.

This walk through is about another PHP application — it was written using the latest PHP 5 features at the time, and was left happily running in a single Amazon EC2 “classic” instance since 2015.

When I started this migration, the last commit was July 30th 2016.

Existing platform

The frontend was left running a variety of third party libraries, notably Bootstrap 3.3 and jQuery 2.2.

The server-side was Symfony 3.1 and templates were Twig 1.x.

Data was obtained from an external API using guzzle and locally cached using doctrine cache 1.6. Logging was done with monolog.

Build toolkit included Node.js for npm (package manager), Grunt (javascript task runner), and Bower (web package manager).

CSS stylesheets were written in sass, so we included a parser to create css, concatenate, and minimize. Javascript was consolidated, obfuscated (“uglified”), and also minified.

To get a feel for the build steps, here’s the “build-all” grunt task:

grunt.registerTask('build-all', ['clean:all', 'concat', 'uglify', 'sass', 'cssmin', 'bowercopy', 'copy', 'string-replace:version', 'composer:dist:install:optimize-autoloader', 'composer:dist:update:optimize-autoloader']);

And finally, as you can see from the above, I was using Composer for PHP dependency management.

And finally the server itself was using Nginx with php-fpm.

Everything was stuck in the year 2015. My development server had long since been destroyed. I couldn’t do any changes; I didn’t even have PHP installed any more.

Aspiration

  • Upgrade front end to the latest versions of Bootstrap and jQuery.
  • Update server side runtime libraries to the latest version — apply necessary code changes required as a result, but no other functional changes.
  • Upgrade the built-kit to the latest versions — but no other changes to the tasks or tools used.
  • Deploy to an up-to-date operating system, with PHP 7.x.

My overarching constraint for the above was that I didn’t want to have to work through and recreate an entire development platform to do it. I wanted to find a way I could achieve the upgrade without needing to stack my Windows laptop with grunt, bower, nodejs, composer, PHP, just for this one task.

I turned to Docker to save the day.

Creating a build container

My build server required the following tools to be installed:

  • PHP 7.x
  • Composer
  • Node.js
  • Grunt
  • Bower

Transitively, for SASS parsing, I subsequently found I needed:

  • Ruby

PHP and Composer (build time)

Given this was used at build time, I wasn’t concerned about having a bloated image so I decided to go for a full PHP installation as the base image. I used the latest PHP image (on Alpine) for my build environment (which I gave the label “buildenv”).

FROM php:7.4.1-alpine AS buildenv

Unfortunately, Composer isn’t included by default and while I could follow the Composer installation instructions, we only need the final ‘composer’ binary file. Luckily, there’s an official Composer image to use. So we reference that image in our layers, and copy the composer binary over into our buildenv.

FROM composer:1.9.1 AS composer 
FROM php:7.4.1-alpine AS buildenv
COPY --from=composer /usr/bin/composer /usr/bin/composer

At this stage, we have an Alpine 3.10 operating system with PHP 7.4.1 and Composer 1.9 available.

Node.js, Grunt, Bower (build time)

Building upon the previous layer, I then looked to the other build tools I required. These I grouped into a single layer, and installed the packages and ensured npm was up to date. Job done.

RUN apk add --update nodejs npm && \
npm update -g npm && \
npm install -g grunt-cli && \
npm install -g bower

Ruby (build time)

A bit of trial and error determined that the sass parser required Ruby. This is in its own layer to keep it separate while I worked out the packages I needed to install. More than I thought and remembered.

RUN apk add --update ruby ruby-bundler ruby-dev \
ruby-rdoc build-base gcc && \
gem install sass

Create a working directory

I always like to do everything inside a working directory, so I create /app and work inside here for all subsequent stages.

RUN mkdir /app 
WORKDIR /app

Downloading the application dependencies

Remarkable looking back at all of the stages to get through before we can commence the application build. In summary, we have these steps for downloading the build time and runtime dependencies we require;

  1. npm install — download the javascript build libraries into node_modules
  2. composer install — PHP server side runtime dependencies, such as Twig and Symfony.
  3. bower update — download all the client side runtime libraries, such as jQuery.
# Copy npm dependencies
COPY package.json .
RUN npm install
# Copy composer and download dependencies
COPY composer.json .
RUN composer install
# Copy bower and download dependencies
RUN apk add --update git
RUN echo '{ "allow_root": true }' > /root/.bowerrc
COPY bower.json .
RUN bower update

To briefly explain the above techniques.

  • I copy only the files needed for the job (e.g. package.json, composer.json, or bower.json) — that’s so that I can isolate changes and limit recreating layers unnecessarily. Some of these steps can take 5 minutes to complete so I don’t want to trigger a full rebuild because I changed an unrelated file.
  • Bower — needs git, so this stage I added that. Secondly, bower throws a warning when it is run as ‘root’ user — so the second line suppresses that.

So now we have a build environment that has an Alpine 3.10 operating system with PHP 7.4.1 and Composer 1.9 available. It has the latest versions of nodejs, grunt, and bower, and we have downloaded all the build-time and runtime dependencies that we require.

I think now we’re ready to build the application.

Building the application

In Docker terms, this may feel like an anticlimax. Because I’m using grunt, the existing build-all task that I created back in 2015 will still do the job.

# Copy all the remaining source code
COPY src/ /app/src
COPY Gruntfile.js .
RUN grunt build-all

This is where all the work is done. You can skip this if you want, but I’ve shared so you can see the original build task. You might find this snippet useful to take some concepts into your own project.

In summary, what we are doing is:

  1. cleaning our build directory
  2. concatenating all javascript source code into a single file.
  3. obfuscating the javascript code
  4. using sass parser to create our css stylesheets
  5. minifying the css stylesheets
  6. copying all our javascript and css, third party css, and fonts over to our final distribution directory
  7. copy all server-side source code into the directory ready for Composer
  8. update version number placeholder
  9. run Composer to create an optimized production-ready runtime

It wasn’t all plain sailing when I upgraded my libraries to their latest version. Some changes were easy, sure, but a few required code updates — after all, I had to accommodate 5 years of deprecated features and changes. But all in all, it wasn’t as painful as I expected.

At this stage we have a buildenv containing a directory /app/dist/ with all our final build output ready to be run.

Building the runtime image

So far everything we have done is in our ‘buildenv’. But we don’t want all this bloatware in our final image. So we start again with a slim operating system, and I chose Alpine.

On top of that, we need PHP but this time we only need a small subset of the PHP packages to run this application (your mileage will vary). And for this particular runtime, we still have Nginx.

As you will see later, I am also using supervisor to manage the processes to ensure php-fpm and nginx are kept running.

# Create final image
FROM alpine:3.11.0
# Install packages
RUN apk upgrade && apk --no-cache add php7 php7-fpm \
php7-json php7-openssl \
nginx supervisor curl

Configuration

Our three processes each need some configuration, so we copy those into place in the image. These trivial configuration files have been shared in the example repository on GitHub.

In summary, the configuration is simply to allow Nginx to listen on port 8080 and redirect requests to php-fpm to handle.

# Configure nginx 
COPY config/nginx.conf /etc/nginx/nginx.conf
# Configure php-fpm
COPY config/fpm-pool.conf /etc/php7/php-fpm.d/www.conf
COPY config/php.ini /etc/php7/conf.d/zzz_custom.ini
# Configure supervisord
COPY config/supervisord.conf /etc/supervisor/conf.d/supervisord.conf

Use nobody user to own directories

We’re using the ‘nobody’ user, so we need to ensure directory permissions are aligned.

RUN chown -R nobody.nobody /run && \
chown -R nobody.nobody /var/lib/nginx && \
chown -R nobody.nobody /var/log/nginx

We now have our runtime image, with PHP and Nginx installed and configured. But we still need our application.

Copy the final distribution from the build environment

Let’s create the directory /var/www/html and switch to the nobody user, then copy all the distribution contents over from the ‘buildenv’.

# Setup document root 
RUN mkdir -p /var/www/html
# Switch to use a non-root user from here on
USER nobody
# Add application
WORKDIR /var/www/html
COPY --chown=nobody --from=buildenv /app/dist/ /var/www/html/

Expose the port

Nearly at the end now — we need to expose the port that Nginx will be reachable on.

# Expose the port nginx is reachable on 
EXPOSE 8080

Ensure services are running

The final stage now is to use supervisord to ensure that Nginx and php-fpm are running and able to serve requests.

# Let supervisord start nginx & php-fpm 
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

Conclusion

And that’s it — we can build the image and run it locally. Our runtime has a low footprint because we used a slim base image and only installed the absolute bare-minimum packages we required to run our application.

Your situation will obviously be different, the libraries you use may be more complex — but I hope the overview gives a sense of what can be accomplished.

For build automation, I then combined GitHub with DockerHub so that future commits automatically kick off a build and the creation of a new versioned image.

And I deployed that into Google Cloud Run, where the exact same image I ran on my laptop I could also happily run in Production.

I killed off my Amazon EC2 “classic” micro instance after almost 6 years, and reduced the cost of running to pennies a year.

And by choosing Docker, I had a maintainable platform to keep on top of.

The final Dockerfile

I ended up with a single Dockerfile, applying the Docker multi-stage build technique, and ultimately created a cut-down, slim runtime image. I could have consolidated a few layers, and break out, but once the initial set up was done, I could spin out new images in under a minute so I left it all as one.

Final Dockerfile

A note from the author

Thank you for reading this article — I hope you found this article useful and I look forward to your comments and feedback.

Source code is available from this example repository on GitHub.

You can follow me on Twitter and connect on LinkedIn.

Written by

DevOps | SRE | AWS | GCP https://twitter.com/davelms