We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use the Dokku One-Click DigitalOcean Image to Run a PHP App

Posted Nov 26, 2013 22.5k views One-Click Install Apps Dokku PHP Git PostgreSQL Ubuntu

Note: The Dokku project has changed significantly since this guide was written. The instructions below may not reflect the current state of the Dokku project.


A significant hurdle in developing an application is providing a sane and easy way to deploy your finished product. Dokku is a Platform as a Service solution that enables you to quickly deploy and configure an application to a production environment on a separate server.

Dokku is similar to Heroku in that you can deploy to a remote server. The difference is that Dokku is built to deploy to a single, personal server and is extremely lightweight. Dokku uses Docker, a Linux container system, to easily manage its deployments.

In this guide, we will cover how to deploy a PHP app with Dokku using the DigitalOcean Dokku one-click installation image.

Step One –– Create the Dokku Droplet

The first thing we need to do is create the VPS instance that contains our Dokku installation. This is simple to set up using the DigitalOcean Dokku application.

Click on the "Create" button to create a new droplet:

DigitalOcean create droplet

Name your droplet, and select the size and region that you would like to use:

DigitalOcean configure droplet 1

Scroll down and click on the "Applications" tab. Select the Dokku application image:

DigitalOcean Dokku image

Select your SSH keys if you have them available. If you do not already have them configured, now is a great time to create SSH keys to use with your DigitalOcean droplets. This step will help you later.

Click "Create Droplet". Your Dokku VPS instance will be created.

DigitalOcean final create

Once your droplet is created, you should set up your domain name to point to your new Dokku droplet. You can learn how to configure domain names with DigitalOcean here.

Step Two –– Access the Droplet To Complete Configuration

You can complete your Dokku configuration by accessing your VPS from a web browser.

If you configured a domain name to point to your Dokku installation, you should visit your domain name with your favorite web browser. If you do not have a domain name configured, you can use your droplet's IP address.

You will be given a simple configuration page. There are a few parts that you need to configure here.

DigitalOcean Dokku ssh keys

First, check that the Public Key matches the computer that you will be deploying from. This means that if your project is on your home computer, you should use the public key that corresponds to that set up.

If you selected multiple SSH keys to embed during droplet creation, only the first will be available here. Modify it as necessary.

DigitalOcean Dokku hostname configuration

Next, modify the Hostname field to match your domain name. Leave this as your IP address if you do not have a domain name configured.

Choose the way that you want your applications to be referenced. By default, the application will be served like this:


If you select the "Use virtualhost naming for apps" check box, your apps will be accessible using a virtualhost instead:


Click the "Finish Setup" button to complete the configuration.

Step Three –– Deploy a Simple PHP Application to your Dokku Droplet

Now that we have Dokku configured correctly, we are ready to begin preparing things for our deployment. Dokku handles PHP applications smoothly, so you should not have to tinker with your code very much to successfully launch your application.

Create an Application Database with Dokku

One thing you may be familiar with if you have deployed apps using other services is the idea of the database being separate from your application environment.

Configuring things in this way allows you to easily divorce your data from the application if either the database backend or the code itself must be updated. It also allows you to switch databases on a whim with little or no fuss.

In order to stay lean, Dokku handles database resources through a plugin system. We can install the database plugin we need without the overhead of having the code for each separate database packaged into our deployment environment. Dokku has a page in their wiki listing available plugins. Each has their own installation instructions.

Our application will take advantage of a PostgreSQL database, so we will install the associated plugin. To install the PostgreSQL plugin directly from GitHub, run:

dokku plugin:install https://github.com/dokku/dokku-postgres.git

This will download and configure all of the necessary packages for Dokku to integrate PostgreSQL functionality within apps. If we look at the Dokku help command, we can see that the new database commands are already available to us:

dokku help

. . .
plugins         Print active plugins
postgres:create <app>     Create a PostgreSQL container
postgres:delete <app>     Delete specified PostgreSQL container
postgres:info <app>       Display database informations
postgres:link <app> <db>  Link an app to a PostgreSQL database
postgres:logs <app>       Display last logs from PostgreSQL container
run <app> <cmd>                                 Run a command in the environment of an application
. . .

We will create a database now that our application can then hook into once it's deployed. This is the point where we will need to decide the name of our application. If you set up virtual hosts during the Dokku configuration, the app's name will be present in the URL to reach it:

dokku postgres:create php_app

It will give you the connection information for accessing this database. For the most part, you will not need to connect to the database using this information because when your app is deployed, this information is accessible in a formatted URL within an environmental variable called DATABASE_URL.

Fill in Application Data

Our PHP application will be very simple and straight forward. In fact, it will be so simple that it will not include methods of inserting data within our database, only querying it.

To work around this, we're going to prime our database with a few pieces of data so that we can query later on. This would normally not be necessary at all. It is just for the sake of demonstration.

First, on the Dokku droplet, install the PostgreSQL utilities so that we can connect to the database:

apt-get install postgresql

Now, we need to get those connection parameters that were given as output during the database configuration. We can recall them by typing:

dokku postgres:info php_app
    DSN: postgres://postgres:d257ed7158ae9a01339615aef4a3f871@

We can then connect to the database using the psql command, substituting the data here:

psql -h postgres://postgres:d257ed7158ae9a01339615aef4a3f871@

You will be given a PostgreSQL prompt.

We will create a simple table that we can use to query later:

    item_id SERIAL,
    item_name VARCHAR(30),
    item_quantity INTEGER

Now, insert a few values into the table:

INSERT INTO picnic (item_name, item_quantity) VALUES
    ('sandwich', 6),
    ('root_beer', 4),
    ('water', 2),
    ('salad', 6),
    ('potato_chips', 3),
    ('grapes', 50);

Exit out of PostgreSQL so that we can continue:


Create or Configure your PHP Application

On our development machine (whichever computer has the SSH key that matches the one you entered during the Dokku setup), we will be developing our PHP application.

For the purpose of this tutorial, we will assume that you are developing on an Ubuntu 12.04 VPS, but it could really be any machine as long as you can install git onto it. If your development computer is running Ubuntu and you don't have git installed yet, install it now:

sudo apt-get install git

We will be getting a simple PHP application from GitHub because it does a great job of demonstrating a strategy for connecting to a PostgreSQL database which stores its credentials in a DATABASE_URL environmental variable.

Clone the repository within your user's home directory and then enter the application directory like this:

cd ~
git clone https://github.com/kch/heroku-php-pg.git php_app
cd php_app

Now, we will examine the index.php file and modify it a little to use the table we just created:

nano index.php

Before we make any changes, I want to point out the method the author uses to connect to the database:

function pg_connection_string_from_database_url() {
    return "user=$user password=$pass host=$host dbname=" . substr($path, 1);

$pg_conn = pg_connect(pg_connection_string_from_database_url());

The pg_connection_string_from_database_url function is used to parse the DATABASE_URL environmental variable and assign the relevant pieces to variables that coincide with the way that PHP connects to PostgreSQL databases.

Let me break it down further:

  • $_ENV["DATABASE_URL"]: provides access to the DATABASE_URL environmental variable
  • parse_url: Creates an associative array containing the components of the URL
  • extract: This imports an array of variables into the symbol table

The result is that we associate the parameters necessary to establish a database connection with variables. We then pass these out of the function as variable names that the PHP PostgreSQL library recognizes as connection information.

These variables are passed to the pg_connect function, which returns an object that represents the open database connection.

Now that you have an understanding of how PHP establishes a connection to the database, we will modify the querying string contained in this line:

$result = pg_query($pg_conn, "SELECT relname FROM pg_stat_user_tables WHERE schemaname='public'");

Comment this line out and then write a new query string below it that will use the table we just created:

$result = pg_query($pg_conn, "SELECT item_name,item_quantity from picnic;");

We will also change some of the lines that print to better reflect our content. Find the section that currently prints the table names:

print "Tables in your database:\n";
while ($row = pg_fetch_row($result)) { print("- $row[0]\n"); }

We want to modify the first line to correctly label our content as picnic items. We also want to change the second line to not only print the first item in the row ($row[0]), but also the second item, so that we can see the associated quantity of each food item for our picnic:

// print "Tables in your database:\n";
// while ($row = pg_fetch_row($result)) { print("- $row[0]\n"); }
print "Items in your picnic:\n";
while ($row = pg_fetch_row($result)) { print("- $row[0] -> $row[1]\n"); }

Save and close the file.

Since we cloned this project from GitHub, it is already under version control, but we need to add our new changes to the repository:

git add .
git commit -m 'Modify database connection and printing'

Our application is complete and our git repository is complete.

Deploy your PHP Application to Dokku

The app is now to the point where it is ready for production. We have created a PostgreSQL database on our Dokku droplet that will serve this application. All that's left to do is actually deploy the app.

To deploy our app to Dokku, all we need to do is git push our files to the Dokku droplet. Dokku will configure and launch our app automatically. The first step is to add the Dokku droplet as a git remote for our application.

git remote add remote_name dokku@your_domain.com:php_app

In this scenario, the remote_name can be anything you'd like. It's just a label that is used on the local computer to refer to your Dokku droplet. In most cases, names like "dokku" or "production" would be appropriate and descriptive.

However, the php_app label is important because it has to match the name you chose for your database. This is also the piece that decides how your app will be accessed through virtual hosts.

Now, deploy your application by pushing it to Dokku:

git push remote_name master

You should see the Dokku output on your local machine. At the end, it will give you the URL you can use to access your application:

       Default process types for PHP (classic) -> web
-----> Releasing php_app ...
-----> Deploying php_app ...
-----> Cleaning up ...
=====> Application deployed:

To dokku@your_domain.com:php_app
   e2b2547..5dfaed7  master -> master

If you visit this page in your web browser, you should be able to see the results of our PHP application:


Dokku PHP app deployment


You have now deployed a PHP application to your Dokku droplet. Although our example application was rather simple, you can see how it is easy to tie in a database to your application through Dokku's plugin system. You can apply the same steps we used here in more complex examples. Dokku will take care of the rest of the configuration and deployment.

By Justin Ellingwood


Creative Commons License