If your repository contains multiple PHP apps, each mapped to a different (sub)domain, you will not be able to use the default PHP buildpack that comes with Dokku because it only supports a single document root. Instead, follow these instructions, which leverage a custom Dockerfile. Note: you don't need to use Docker locally to leverage this technique, but it can be helpful for testing purposes.

Creating an Application

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

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

Preparing Your Application for Deployment

Tutorial App: https://github.com/HealthcareBlocks/php_multiple_apps

1. Add a file named Dockerfile to the root of your code repository. It should be similar to this one.

Notice the first line specifies the PHP version used in the official Docker image. To see the list of versions currently supported, see here.

2. Add a file named virtual-hosts.conf to the root of your code repository. It should be similar to this one.

Update the ServerName, ServerAlias, and DocumentRoot fields. You can remove ServerAlias if not needed.

Leave the first part of the DocumentRoot set to /var/www/html/ - which maps to the root of your code repository. On your local machine, you don't need to use the same directory structure, as long as your apps are located in subdirectories under your repository root.

Important: for Dokku compatibility, leave the port number as 5000. You do not to define an SSL configuration because TLS encryption is handled by the Dokku front-end proxy. See the SSL topic for details.

3. Add a php.ini to the root of your code repository if you need to override any global PHP settings. If you don't need to do this step, remove this line from the Dockerfile you created above.

Installing PHP Extensions

The PHP Docker image does not include extensions like gd and mcrypt by default. However, it's easy to specify them in the Dockerfile, right under the first FROM line. For example:

RUN apt-get update && apt-get install -y \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    libmcrypt-dev \
    libpng12-dev \
    && docker-php-ext-install -j$(nproc) iconv mcrypt \
    && docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install -j$(nproc) gd

For additional documentation, including how to install PECL and other extensions, see here.

Deploy your App

See Deploying via Git topic

Define Your Domains

On the server, do the following for each application (sub)domain, replacing the placeholder values accordingly:

dokku domains:add my-app-name admin.mydomain.com
dokku domains:add my-app-name portal.mydomain.com

Create DNS Records

Refer to this topic for details. In sum, you'll need to create CNAME entries for your primary app name. For example, admin.mydomain.com requires a CNAME entry named 'admin' pointing to my-app-name.server-id.healthcareblocks.com. Same thing for portal.mydomain.com.

Additional Documentation

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