Dokku uses an open source PHP buildpack to compile and run your application. Follow these steps to configure and deploy your app.

Preparing Your Application for Deployment

Do the following steps on your local development machine:

1. Add a file named Procfile to the root of your application and specify the startup command.

If you'd like to use Apache as the backend app server:

web: vendor/bin/heroku-php-apache2

If you'd like to use Nginx as the backend app server:

web: vendor/bin/heroku-php-nginx

For the above statements, if you need to set a document root, add it to the end. For example, if your document root is named public:

web: vendor/bin/heroku-php-apache2 public/

2. Use PHP Composer to define PHP extensions that are dependencies for your application.

Be sure you have Composer installed, and add a composer.json to the root of your source control repository and not within a subdirectory.

If your app does not have any library dependencies and your application is compatible with the latest stable version of PHP, add a composer.json file containing empty JSON curly braces - {}. This is necessary in order for the deployed application to be recognized as a PHP application.

To specify a different PHP version:

{
  "require": {
    "php": "^5.6.0"
  }
}

Supported PHP Versions

  • 5.6.37
  • 7.0.31
  • 7.1.20
  • 7.2.8

Included Extensions

The following built-in extensions are enabled automatically on Healthcare Blocks and do not need to be specified in composer.json. In addition, any extensions that PHP enables by default, such as DOM, JSON, PCRE or PDO, are also included in the environment.

  • Bzip2
  • cURL
  • FPM
  • mcrypt (5.5 and 5.6 only)
  • MySQL (PDO) (uses mysqlnd)
  • MySQLi (uses mysqlnd)
  • OPcache
  • OpenSSL
  • PostgreSQL
  • PostgreSQL (PDO)
  • Readline
  • Sockets
  • Zip
  • Zlib

Additional extensions are built as "shared" and need to be explicitly referenced in your composer.json. For example:

"require": {
  "ext-gd": "*",
  "ext-mbstring": "*"
}

Heroku maintains the official PHP buildpack used by Dokku, so please refer to their page for additional details on this topic.

Don't forget to freeze the composer file and add the composer.json and composer.lock files to source control:

composer update

3. Enable PHP logging.
Add a file named .user.ini to your project's root directory and include the following settings:

log_errors = On
error_log = /dev/stderr
error_reporting = E_ALL

4. Overriding PHP settings.

To override php.ini settings, inside the .user.ini file, you can include custom settings. For example:

upload_max_filesize = 5M

You can also include .user.ini files on a per directory basis.

Important: if you adjust the max filesize in PHP, you'll need to also update Nginx's configuration by creating /home/dokku/my-app-name/nginx.conf.d/custom.conf with the following contents:

client_max_body_size 5m;

The above file will be automatically picked up during the next deployment - no need to restart Nginx.

Defining the Application on the Server

Connect to the server using SSH and create your app(s):

ssh username@server-id.healthcareblocks.com
dokku apps:create my-app-name

Define any environment variables, especially addresses for external services, API keys, and any other production-specific setting you don't want to store in your source code.

dokku config:set my-app-name KEY1=VAR1

Your PHP code can read from environment variables like this:

<?php
echo 'Getting value: ' .$_ENV["KEY1"];
?>

In most cases, your database will be running on a separate machine via our database-as-a-service plan. You should have received connection information and credentials during the on-boarding process.

Deploy your App

See Deploying via Git topic

Using Docker Natively

If you prefer to use your own Dockerfile instead of the PHP buildpack, please refer to the official Dokku Dockerfile deployment instructions.

Troubleshooting

Error Message: "PHP Fatal error: Call to undefined function mysql_connect()"

If you did not specify a PHP version in your composer.json, the PHP buildpack will use the latest stable version of PHP, which is version 7. In that version, the mysql_connect function was removed, and you must use MySQLi or PDO_MySQL as described in http://php.net/manual/en/function.mysql-connect.php.

Shared extension not loading on my PHP page

Be sure you run compose update locally and then check-in the .lock file, then do another deployment.

Frequently Asked Questions

Should I pick Apache over Nginx when defining my Procfile run command?

Apache is more popular and required if your PHP framework requires .htaccess file support. Nginx, on the other hand, runs leaner and faster in virtual machine environments.

How do I run the equivalent of php -i with Dokku?

dokku --rm run my-app-name php -i

How do I write to the error log?

The PHP error log is automatically sent to stderr, and any message logged using the error_log function will thus be available in dokku logs:

error_log("my debug message");

The alternative approach, is writing to the php://stderr stream directly:

file_put_contents("php://stderr", "my debug message \n");

Reference Application

This simple PHP app has been tested on the Healthcare Blocks platform:

https://github.com/heroku/php-getting-started

Additional Documentation

More help topics can be found in the Dokku Getting Started guide.