Dokku: How to deploy a vanilla PHP application

In this article we will show you how to deploy a PHP application to Dokku v0.4.5 running on DigitalOcean.

If you are new to Dokku see our previous article on how to install Dokku and deploying a static site.

PHP buildpack

By default Dokku will use the default Heroku PHP buildpack for PHP applications.

If the correct buildpack isn't automatically detected or you want to use a custom one create a .env file in your repository with the following content:

export BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-php.git

Setup Composer

If you haven't already setup Composer for your app or you haven't installed it you will need to do so.

Create a composer.json file. The file must have at least an empty JSON object: {}.

Specify PHP version

Specify the version of PHP you want to use in your composer.json file:

{
    "require": {
  "php": "~5.6.0"
    }
}

This will use the latest 5.6.x version of PHP.

Instead of the PHP runtime you can also select the HHVM runtime. I haven't tried it yet, though.

{
    "require": {
  "hhvm": "~3.3"
    }
}

Specify extensions

Some PHP extensions will already be enabled by default.

To enable optional extensions you enter:

{
    "require": {
  "php": "~5.6.0",
        "ext-gd": "*",
  "ext-xsl": "*"
    }
}

Specify scripts

If you need to execute any command during the Composer execution process you can use Composer scripts.

For example, to change the permissions of the tmp folder after install:

{
    "require": {
  "php": "~5.6.0",
        "ext-gd": "*",
  "ext-xsl": "*"
    },
 "scripts": {
        "post-install-cmd": [
            "chmod -R 777 tmp"
        ]
 }
}

Install Composer dependencies

The Heroku documentation mentions that it is enough to have a composer.json file in the repository. I have found that without the composer.lock file the deployment will fail.

Run the Composer install command:

composer install

This will install the dependencies and generate the composer.lock file.

Apache vs NGINX

You can choose between Apache and NGINX for your web server. Apache will be used by default.

If you want to specify which web server you want to use create a Procfile. For using NGINX:

web: vendor/bin/heroku-php-nginx

Set the document root

By default the root folder of your repository will be used as the document root. If you want to use a sub-directory you can pass it as the second parameter in the Procfile:

web: vendor/bin/heroku-php-nginx public_html

Custom php.ini settings

Since PHP doesn't run as an Apache module you can't change settings by using php_value in your .htaccess file.

Instead you can place your settings in a .user.ini file (using the same format you would use for a php.ini file) in your document root or the folder where you want those changes to apply.

Not all PHP settings can be changed through a .user.ini file. Only those with modes PHP_INI_USER or PHP_INI_PERDIR.

You can also specify additional php.ini settings without overriding the entire php.ini file by using the -I option for the web server boot script:

web: vendor/bin/heroku-php-nginx -I php_custom.ini public_html

Check the Heroku guide for more details on customizing runtime settings for PHP.

Push your repository

Commit and push the changes to your repository.

Add the Git remote for Dokku if you haven't done that yet:

git remote add dokku dokku@host:app_name

Now push to the remote and see how the deployment goes:

git push dokku master

Next: how to setup your database

In the next article we will look into creating a database and linking it to our application.