How to Deploy Phalcon Applications to Microsoft Azure with Nanobox

Phalcon is a high-performance PHP MVC web framework written in Zephir and C and implemented as a PHP extension. It's fast, resource-light, and handles concurrency well. Microsoft Azure is Microsoft's cloud offering built for deploying and managing applications on their global network of data centers.

In this article, I'm going to walk through deploying a Phalcon application to Microsoft Azure using Nanobox. Nanobox uses Docker to build local development and staging environments, as well as scalable, highly-available production environments on Azure.

Download Nanobox

Go ahead and create a Nanobox account and download Nanobox Desktop, the Nanobox CLI.

Setup Your Phalcon Project

Whether you have an existing Phalcon project or are starting from scratch, the process of configuring it for Nanobox is the same.

Add a boxfile.yml

Nanobox uses the boxfile.yml to build and configure your app's environment both locally and in production. Create a boxfile.yml in the root of your project with the following:

  engine: php
    runtime: php-7.1
    webserver: apache
    document_root: public
      - curl
      - gettext
      - gd
      - json
      - mbstring
      - bz2
      - zlib
      - hash
      - pdo
      - pdo_mysql
      - fileinfo
      - phalcon
    - echo "alias phalcon=\'phalcon.php\'" >> /data/var/home/gonano/.bashrc

    php: start-php
    apache: start-apache
    - cache

  image: nanobox/mysql:5.7

This boxfile.yml will:

  • Provide a PHP runtime with PHP 7.1.
  • Include and use Apache as the webserver.
  • Set the document root to public.
  • Install the Phalcon PHP extension along with other required extensions.
  • Add phalcon as an alias for phalcon.php for convenience.
  • Provide a publicly accessible webserver when deployed.
  • Make cache writable.
  • Provide a MySQL database.

Depending on packages and functionality in your app, you may need to add other extensions, PHP settings, etc. The following guides show how to modify PHP settings, add extensions, and modify other settings:

PHP Settings
PHP Extensions
PHP Webserver Config

Start the Local Dev Environment

With the boxfile.yml in place, you can fire up a virtualized local development environment. I recommend adding a DNS alias just so the app will be easier to access from a browser.

# Add a convenient way to access the app from a browser
nanobox dns add local phalcon.local

# Start the dev environment
nanobox run

Nanobox will provision a local development environment, mount your local codebase into the VM, provision a containerized MySQL database, load your app's dependencies (if a composer.json is present), then drop you into a console inside the VM.

Generate a New Phalcon Project

If you have an existing Phalcon project, you can skip this section. To generate a new Phalcon project from scratch, add the following to your composer.json:

    "require-dev": {
        "phalcon/devtools": "~3.0.3"

Run the following from inside the Nanobox console:

# Install phalcon dev tools
composer install

# cd into /tmp
cd /tmp

# generate a new phalcon app
phalcon project myapp

# change back to the /app dir
# enable the dotglob shell option to interact with hidden files
# copy the generated app into your project folder
cd -
shopt -s dotglob
cp -a /tmp/myapp/* .

Your project's current working directory is mounted into the /app directory in the VM, so all the Phalcon files written there will propagate back down to your machine's filesystem and vice versa.

Update the Database Connection

In this example, I'm using MySQL, but you can use any of the officially supported data services. When Nanobox spins up a data service, it generates environment variables for the necessary connection credentials. For MySQL, host, user, and password environment variables are provided. Also, Nanobox provides a default gonano database.

Update your app/config/config.php to use the auto-generated environment variables in your connection config.

'database' => [
    'adapter'     => 'Mysql',
    'host'        => $_ENV['DATA_MYSQL_HOST'],
    'username'    => $_ENV['DATA_MYSQL_USER'],
    'password'    => $_ENV['DATA_MYSQL_PASS'],
    'dbname'      => 'gonano',
    'charset'     => 'utf8',

Adding Other Data Components

Note: The process for adding other data components such as Redis, Memcached, Postgres, etc. is the same:

  1. Add the data component to your boxfile.yml.
  2. Add the necessary PHP extensions.
  3. Update your connection config to use the auto-generated environment variables.
  4. nanobox build to apply the changes and provision the data component.

Run Phalcon Locally

Ok, you should be ready to fire Phalcon up locally. Nanobox's PHP engine includes a php-server helper script that starts your app using settings defined in the boxfile.yml. For this example, it'll start Nginx and PHP-FPM. Just run the following from the root of your project in the Nanobox console:


You'll then be able to access your running Phalcon app at phalcon.local.

Any changes you make to your codebase will be reflected in the running app. Once you're done hacking, exit out of the Nanobox console and your local dev environment will shutdown.

Alright! Now to the fun part!

Setup Your Azure Account

If you haven't already, create a Microsoft Azure account. In your Azure Portal, click on "More Services" at the bottom of the left nav and filter for "Subscriptions". Click on your Subscription ID.

Azure Subscription ID

Copy and store your Subscription ID. You're going to need it later.

Register Resource Providers

Inside your Subscription ID options, filter for and select "Resource providers". Register "Microsoft.Compute", "Microsoft.Network", and "Microsoft.Storage" by clicking on the "Register" button to the right of each option. These are the resources necessary for Nanobox to build and provision your application on Azure.

Select Azure Resource Providers

Get Your Active Directory ID

In the left nav, select "Azure Active Directory" and go to "Properties". Copy the "Directory ID".

Active Directory ID

Copy and store your Active Directory ID. You're going to need it later.

Create a New Application Registration

Still inside Azure Active Directory, select "App Registrations" and create a new app registration. An "App Registration" is essentially an API integration. You're giving Nanobox access to your Azure resources through a registered "app".

Create New App Registration

Enter the required information:

Name - This can be whatever you'd like.
Application type - Web app / API
Sign-on URL - This isn't used by Nanobox, so put whatever you'd like.

App Registration Credentials

After saving your new app registration, Copy and store your Application ID. You're going to need it later. Click on your new app registration in your list of registered apps, then select "Keys". Provide a key description and expiration, then save.

Key Details

Copy and store the key value. You won't be able to retrieve it after you navigate away from this section and you're going to need it later.

Key Value

Create a New Provider Account

In your Nanobox dashboard, go to the Hosting Accounts section of your account admin and click "Add Account", select Azure, and click "Proceed".

Add a New Azure Provider

Enter the required credentials.

Subscription ID - Azure Subscription ID
Tenant ID - Azure Active Directory ID
Application ID - Azure Application ID
Authentication Key - Azure Application Registration Key Value
Cloud Environment - Should be set to default

Enter Azure Auth Credentials

Click "Verify & Proceed". Name your provider, select your default region, then click "Finalize/Create".

Name Your Provider & Select a Default Region

Launch a New App

Go to the home page of your Nanobox dashboard and click the "Launch New App" button. Select your Azure provider from the dropdown and choose the region in which you'd like to deploy your app.

Select your Azure provider

Confirm and click "Let's Go!" Nanobox will order an server on Azure under your account. When the server is up, Nanobox will provision platform components necessary for your app to run:

  • Load-Balancer: The public endpoint for your application. Routes and load-balances requests to web nodes.
  • Monitor: Monitors the health of your server(s) and application components.
  • Logger: Streams and stores your app's aggregated log stream.
  • Message Bus: Sends app information to the Nanobox dashboard.
  • Warehouse: Storage used for deploy packages, backups, etc.

Once all the platform components are provisioned and running, you're ready to deploy your app.

Stage Your App Locally

Nanobox provides "dry-run" functionality that simulates a full production deploy on your local machine. This step is optional, but recommended. If the app deploys successfully in a dry-run environment, it will work when deployed to your live environment.

nanobox deploy dry-run

More information about dry-run environments is available in the Dry-Run documentation.


Add Your New App as a Remote

From the root of your project directory, add your newly created app as a remote.

nanobox remote add app-name

This connects your local codebase to your live app. More information about the remote command is available in the Nanobox Documentation.

Deploy to Your Live App

With your app added as a remote, you're ready to deploy.

nanobox deploy

Nanobox will compile and package your application code, send it up to your live app, provision all your app's components inside your live server, network everything together, and voila! Your app will be live.

Manage & Scale

Once your app is deployed, Nanobox makes it easy to manage and scale your production infrastructure. In your Nanobox dashboard you'll find health metrics for all your app's servers/containers. Your application logs are streamed in your dashboard and can be streamed using the Nanobox CLI.

Although every app starts out on a single server with containerized components, you can break components out into individual servers and/or scalable clusters through the Nanobox dashboard. Nanobox handles the deep DevOps stuff so you don't have to. Enjoy!

Posted in PHP, Microsoft, Azure, Phalcon, Deployment