Installation

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 7.0.14-2+deb.sury.org~trusty+1 (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 https://github.com/REBELinBLUE/deployer.git deployer

2. 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

2. Make sure the storage and upload directories are writable

$ chmod -R 777 storage

3. 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 [http://deployer.example.com]:
>

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 http://deployer.example.com:6001, 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 http://deployer.example.com or http://example.com. 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 127.0.0.1:6001;
}

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

    access_log off;
    error_log  /var/log/nginx/deployer.app-error.log 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 /socket.io {
        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>
    ServerName deployer.app
    DocumentRoot "/var/www/deployer/public"

    DirectoryIndex index.php

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

    ErrorLog "/var/log/apache2/deployer.app-error.log"
</VirtualHost>

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 http://deployer.example.com 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

[program:deployer]
command=php artisan queue:work --queue=deployer-high,deployer-low --sleep=3 --tries=1 --daemon
directory=/var/www/deployer
process_name=queue_%(process_num)s
numprocs=3
numprocs_start=0
stdout_logfile=/var/log/supervisor/deployer-%(process_num)s-stdout.log
stderr_logfile=/var/log/supervisor/deployer-%(process_num)s-stderr.log
stderr_logfile_maxbytes=1MB
stdout_logfile_maxbytes=1MB
redirect_stderr=true
autostart=true
autorestart=true

[program:deployer-socketio]
command=node socket.js
directory=/var/www/deployer
numprocs=1
autostart=true
autorestart=true
environment=HOME="/var/www/deployer",NODE_ENV="production"
stderr_logfile=/var/log/supervisor/deployer-socket-stderr.log
stdout_logfile=/var/log/supervisor/deployer-socket-stdout.log
stderr_logfile_maxbytes=1MB
stdout_logfile_maxbytes=1MB

[program:deployer-broadcast]
command=php artisan queue:work --queue=deployer-default --sleep=3 --tries=1 --daemon
directory=/var/www/deployer
numprocs=1
stderr_logfile=/var/log/supervisor/deployer-broadcast-stderr.log
stdout_logfile=/var/log/supervisor/deployer-broadcast-stdout.log
stderr_logfile_maxbytes=1MB
stdout_logfile_maxbytes=1MB
redirect_stderr=true
autostart=true
autorestart=true

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.