Stephen Ball edited this page Mar 7, 2017 · 10 revisions

Getting Started

Using Deployer

  • Creating Projects
  • Server Management
  • Deployments
  • Command Hooks
  • File Management
  • Notifications
  • Health Checks
  • Templates

Advanced Options

  • Webhooks
  • Custom Notifications


  • Additional Options
  • Getting Help
Clone this wiki locally

To install Deployer you will simply need to clone the code from Github, install dependencies using Composer and run the included script to get everything up and running:

Check for PHP version

Be sure you have at least PHP version 5.6.4 by going to the terminal and typing:

$ php -v

This should report the version and build information. For example:

PHP (cli) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies

Grab the code

  1. Clone the Deployer repository from GitHub to a folder in the webroot of your server, e.g. /var/www/deployer. Launch a terminal or console and navigate to the webroot folder:
$ cd /var/www
$ git clone deployer
  1. Checkout the latest release
$ git checkout <latest release>

Please see the latest release for the latest version.

Run the installer

  1. Install the dependencies
$ composer install -o --no-dev
$ npm install --production
  1. Make sure the storage and upload directories are writable
$ chmod -R 777 storage
  1. Run the installer and follow the instructions
$ php artisan app:install

Notes on running the installer

Most of the settings are obvious, however there is one which may need some explaining

Socket URL []:

This setting is the URL for the socket server, if you are using nginx and use the configuration supplied below you can leave it as below. If you are using Apache you will need to append the port, for example, the installer will attempt to automatically determine if this is needed.

If you need to change the port because, for example, you have another service already using port 6001 you will need to edit the configuration after running the installer

$ editor .env

and then edit the SOCKET_PORT, add the SOCKET_URL if you have the port appended.

Setup your webserver

It is recommended that you run Deployer at the root level of a domain, for example or Although it should work in a sub-directory, it has not been tested in such a setup.

You will need to add a virtual host to your web server which points to the public directory.

Below are a couple of examples, nginx is the preferred method

Nginx example

upstream websocket {
    # If you are using SSL, make sure the upstream server name
    # corresponds to the certificate's server name(s).

server {
    listen 80;
    root "/var/www/deployer/public";
    charset utf-8;

    access_log off;
    error_log  /var/log/nginx/ error;

    sendfile off;

    client_max_body_size 100m;

    location / {
        index index.php;
        try_files $uri $uri/ /index.php?$query_string;

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;

    location / {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        # if you are using SSL, below line should be 'proxy_pass https://websocket;'
        proxy_pass http://websocket;

    location ~* /\.(?!well-known\/) {
        deny all;

Apache example

For Apache, you can use a standard virtual host, as long as your server supports PHP, AllowOverride is on and mod_rewrite is enabled.

<VirtualHost *:80>
    DocumentRoot "/var/www/deployer/public"

    DirectoryIndex index.php

    <Directory "/var/www/deployer/public">
        AllowOverride all

    ErrorLog "/var/log/apache2/"

Finalising setup

Finally, all you need to do to finish setup is start the socket server and queue worker.

$ cd /var/www/deployer
$ php artisan queue:work --queue=deployer-high,deployer-low --sleep=3 --tries=1 --daemon
$ php artisan queue:work --queue=deployer-default --sleep=3 --tries=1 --daemon
$ node socket.js

All that is left to do is to visit your host and login with the details you provided during installation.

Extended setup

Although you now have everything which is required to run Deployer there are a few additional recommended steps

Setup a cronjob

Deployer has several scheduled tasks which run to clean up left over temporary files and check the status of your projects. It is recommended that you set these up, although it not required for these to run unless you wish to use URL checking or heartbeats to monitor the status of cronjobs on your servers.

To setup cronjobs all you need to do is create a cronjob with either crontab -e or by creating a file such as /etc/cron.d/deployer with the following content.

* * * * * root php /var/www/deployer/artisan schedule:run 1>> /dev/null 2>&1

Setup supervisor

Deployer runs a node socket server with a redis pubsub queue to push realtime updates to your web browser, the socket server is started using

$ cd /var/www/deployer
$ node socket.js

However, if the server crashes it will not restart and you will need to do so manually.

There are also several queue listeners, one for running the actual deployments & other user initiated actions and one for processing the updates; as with the node socket server if these crash they will not restart automatically. These are started with

$ cd /var/www/deployer
$ php artisan queue:work --queue=deployer-high,deployer-low --sleep=3 --tries=1 --daemon
$ php artisan queue:work --queue=deployer-default --sleep=3 --tries=1 --daemon

Therefore, it is recommended that you use Supervisor to automatically keep these processes running. It always has the advantage of allowing you to run multiple queue listeners at a time, so enabling multiple deployments to run concurrently.

To setup supervisor you will need to create /etc/supervisor/conf.d/deployer.conf with the following content

command=php artisan queue:work --queue=deployer-high,deployer-low --sleep=3 --tries=1 --daemon

command=node socket.js

command=php artisan queue:work --queue=deployer-default --sleep=3 --tries=1 --daemon

Once created, simply restart supervisor with the following command

$ sudo service supervisor restart

From now on the socket server and queue listener will run automatically.