Deploy a PHP App

This guide explains how to deploy a PHP application to Koyeb using Git-driven or Docker-based deployment. The application can be built using either native buildpacks or from a Dockerfile.

To successfully follow this documentation, you will need to have a Koyeb account . You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the PHP application from this guide using the Deploy to Koyeb button below.

You can consult the repository on GitHub to find out more about the example application that this guide uses.

Create the PHP app

Get started by creating a basic PHP application that we will deploy on Koyeb. The buildpack for PHP uses the composer.json file to identify PHP repositories, so you can install Composer if your application requires it, but this demonstration will not need it. If you’d like to test your PHP locally, you can optionally install PHP locally as well.

To begin, create a new project directory and a web subdirectory that will hold the actual PHP files. Navigate into the web directory:


mkdir -p example-php/web
cd example-php/web

Create a new file called index.php with the following contents:

web/index.php


<!DOCTYPE html>
<html>
  <head>
    <title>Example PHP page</title>
  </head>
  <body>
    <?php
      echo '<h1>Hello world!</h1>';
      echo '<p>This page uses PHP version ' . phpversion() . '.</p>';
    ?>
  </body>
</html>

Save and close the file when you are finished.

If you have PHP installed locally, you can test this page by executing the following command in the web directory:


php -S 127.0.0.1:8000

If you visit 127.0.0.1:8000 in your web browser, you should see a page that includes the “Hello world!” message as well as information about the version of PHP that is executing the PHP code block.

Create the project management files

Next, we’ll create a few files that will help Koyeb deploy the project.

First, create a composer.json file. The PHP buildpack that Koyeb uses looks for a composer.json file to identify PHP projects. While many PHP projects use Composer, our project has no dependencies, so we can use an empty JSON object.

Navigate back into the root directory of your project and add a composer.json file with the following contents:

composer.json

{}

This example application should run on any modern version of PHP. If your application requires a specific PHP version, you can set the PHP version in the composer.json file as described in the build with PHP page.

Next, create a Procfile in the root directory. This will be used to define what web server to use to serve the project (Apache or Nginx ) and to direct the server to the project’s “document root” (the directory where our PHP files are located).

Create a Procfile with one of the two lines depending on which server you prefer.

For Apache:

Procfile


web: heroku-php-apache2 web/

For Nginx:

Procfile


web: heroku-php-nginx web/

Create a Dockerfile for the project (Optional)

We can build and run our PHP project on Koyeb using the native PHP buildpack, but we can also optionally build from a Dockerfile for more control. To make it possible to build a container image for our application, we just need to create the Dockerfile. We’ll also define a .dockerignore file to tell the builder what files to skip when creating the image.

First, define a .dockerignore file in your main project directory. Inside, paste the following contents:

.dockerignore


.git
.gitignore
Dockerfile
.dockerignore
/vendor/
composer.phar

This file tells Docker to not include Git files, the Docker files themselves, and any artifacts that Composer might produce when managing dependencies. This helps ensure that the image we build is not bloated and that the build completes faster.

Next, create a new file called Dockerfile within the main project directory. Inside, paste the following contents:

Dockerfile


FROM php:apache
 
WORKDIR /var/www/html
COPY web .
 
ENV PORT=8000
EXPOSE ${PORT}
 
RUN sed -i 's/Listen 80/Listen ${PORT}/' /etc/apache2/ports.conf

This Dockerfile is based on the Apache 2 version of the official PHP Docker image . The instructions copy contents of the web directory to the document root folder. Afterwards, it sets a default port modifiable by the PORT environment variable and changes the configuration file so that the server listens accordingly.

If you have Docker installed locally, you can build and test the image on your computer and optionally upload it to a registry. You can deploy container images from any container registry to Koyeb.

We can also build the Dockerfile directly from the repository when we deploy, which is useful as a way of automatically deploying when changes occur. We will demonstrate this method as one of the options in this guide.

Push the project to GitHub

In the project directory, initialize a new git repository by running the following command:


git init

Next, download a basic .gitignore file designed for Composer projects from GitHub:


curl -L https://raw.githubusercontent.com/github/gitignore/main/Composer.gitignore -o .gitignore

Next, add the project files to the staging area and commit them. If you don’t have an existing GitHub repository to push the code to, you can create a new one and run the following commands to commit and push changes to your GitHub repository:


git add :/
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Deploy to Koyeb using git-driven deployment

Once the repository is pushed to GitHub, you can deploy the PHP application to Koyeb. Any changes in the deployed branch of your codebase will automatically trigger a redeploy on Koyeb, ensuring that your application is always up-to-date.

Koyeb control panel

To deploy the PHP app on Koyeb using the control panel , follow the steps below:

Click Create Web Service on the Overview tab of the Koyeb control panel.
Select GitHub as the deployment option.
Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public PHP example repository into the Public GitHub repository: https://github.com/koyeb/example-php
Choose the Builder for your project. We can use either a Dockerfile or buildpack for this repository.
Name the App and Service, for example example-php.
Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Deploy to Koyeb from a container registry

If you chose to build a container image for the PHP application, you can optionally deploy the application from a container registry instead of from GitHub.

Koyeb control panel

To deploy a pre-built PHP container image on Koyeb using the control panel , follow the steps below:

Click Create Web Service on the Overview tab of the Koyeb control panel.
Select Docker as the deployment option.
Choose the container image and tag from your registry and click Next to continue.
Name the App and Service, for example example-php.
Click the Deploy button.

A Koyeb App and Service will be created. The container image will be pulled from the container registry and a container will be deployed from it. Once the initialization is complete, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.