Phalcon Compose is a community driven boilerplate development environment for Phalcon projects that runs on Docker. Its purpose is to make it easier to bootstrap Phalcon applications and run them on development or production environments.


To run this stack on your machine, you need at least:


Services included are:

Service name Description
mongo MongoDB server container.
postgres PostgreSQL server container.
mysql MySQL database container.
phpmyadmin A web interface for MySQL and MariaDB.
memcached Memcached server container.
queue Beanstalk queue container.
aerospike Aerospike – the reliable, high performance, distributed database optimized for flash and RAM.
redis Redis database container.
app PHP 7, Apache 2 and Composer container.
elasticsearch Elasticsearch is a powerful open source search and analytics engine that makes data easy to search.


Using Composer, you can create a new project as follows:

composer create-project phalcon/compose --prefer-dist <folder name>

Your output should be similar to this:

 Installing phalcon/compose (version)
  - Installing phalcon/compose (version)
    Loading from cache

Created project in folderName
> php -r "copy('variables.env.example', 'variables.env');"
Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update
Generating autoload files

With Git

Another way to initialize your project is with Git.

 git clone [email protected]:phalcon/phalcon-compose.git
Make sure that you copy variables.env.example to variables.env and adjust the settings in that file

Add your Phalcon Application into application folder.


Add phalcon.local (or your preferred host name) in your /etc/hosts file as follows: www.phalcon.local phalcon.local


You can now build, create, start, and attach to containers to the environment for your application. To build the containers use following command inside the project root:

docker-compose build

To start the application and run the containers in the background, use following command inside project root:

# You can use here your prefered project name with "-p my-app" parameter
$ docker-compose up -d

Now setup your project in the app container using the Phalcon Developer Tools

Replace project in **** with the name of your project/directory (shown in the output of `docker-compose up -d`)

$ docker exec -t <project_app_1> phalcon project application simple

Now you can now launch your application in your browser visiting http://phalcon.local (or the host name you chose above).

Set up

If your application uses a file cache or writes logs to files, you can set up your cache and log folders as follows:

Directory Path
Cache /project/cache
Logs /project/log


For most containers you can access the logs using the docker logs <container_name> command in your host machine.

Environment variables

You can pass multiple environment variables from an external file to a service’s containers by editing the variables.env file.

Web environment

Environment variable Description Default
WEB_DOCUMENT_ROOT Document root for webserver (inside the container). /project/public
WEB_DOCUMENT_INDEX Index document. index.php
WEB_ALIAS_DOMAIN Domain aliases. *.vm
WEB_PHP_SOCKET PHP-FPM socket address.
APPLICATION_ENV Application environment. development
APPLICATION_CACHE Application cache dir (inside the container). /project/cache
APPLICATION_LOGS Application logs dir (inside the container). /project/logs

phpMyAdmin variables

Environment variable Description Default
PMA_ARBITRARY When set to 1 connection to the server will be allowed. 1
PMA_HOST Define address/host name of the MySQL server. mysql
PMA_HOSTS Define comma separated list of address/host names of the MySQL servers. Used only if PMA_HOST is empty.  
PMA_PORT Define port of the MySQL server. 3306
PMA_VERBOSE Define verbose name of the MySQL server.  
PMA_VERBOSES Define comma separated list of verbose names of the MySQL servers. Used only if PMA_VERBOSE is empty.  
PMA_USER Define username to use for config authentication method. phalcon
PMA_PASSWORD Define password to use for config authentication method. secret
PMA_ABSOLUTE_URI The fully-qualified path (e.g. where the reverse proxy makes phpMyAdmin available.  

See also


Xdebug Remote debugger (PhpStorm)

For debugging purposes you can setup Xdebug by passing required parameters (see variables.env).

Environment variable Description Default
XDEBUG_REMOTE_HOST php.ini value for xdebug.remote_host (your host IP).  
XDEBUG_REMOTE_PORT php.ini value for xdebug.remote_port. 9000
XDEBUG_REMOTE_AUTOSTART php.ini value for xdebug.remote_autostart. Off
XDEBUG_REMOTE_CONNECT_BACK php.ini value for xdebug.remote_connect_back. Off

NOTE You can find your local IP address as follows:

# Linux/MacOS
ifconfig en1 | grep inet | awk '{print $2}' | sed 's/addr://' | grep .

# Windows


Startup or linking errors

If you got any startup issues you can try to rebuild app container. There will be no loss of data., it is a safe reset:

docker-compose stop
docker-compose rm --force app
docker-compose build --no-cache app
docker-compose up -d

Full reset

To reset all containers, delete all data (mysql, elasticsearch, etc.) but not your project files in application folder:

docker-compose stop
docker-compose rm --force
docker-compose build --no-cache
docker-compose up -d

Updating dependencies

Sometimes the base images (for example phalconphp/php-apache:ubuntu-16.04) are updated. Phalcon Compose depends on these images. You will therefore need to update them and it is always a good thing to do so to ensure that you have the latest functionality available. The dependent containers to these images will need to be updated and rebuilt:

docker pull mongo:3.4
docker pull postgres:9.5-alpine
docker pull mysql:5.7
docker pull phpmyadmin/phpmyadmin:4.6
docker pull memcached:1.4-alpine
docker pull phalconphp/beanstalkd:1.10
docker pull aerospike:latest
docker pull redis:3.4-alpine
docker pull elasticsearch:5.2-alpine
docker pull phalconphp/php-apache:ubuntu-16.04

Linux/MacOS users can use make to perform the task:

make pull

Then you have to reset all containers, delete all data, rebuild services and restart application.

Linux/MacOS users can use make to perform the task:

make reset