Getting Started

Connecting Servers

After signing up for Envoyer, you should add a project to your account. Projects are tied to a source control repository. Of course, if you wish, you may create a project for each "stage" of your project (development and production).

After creating a project, you may add as many servers as you like to the project. After adding a server, you will be given an SSH key to add to your server. You should add the SSH key to the authorized_keys file for the users you want to connect as.

After you have added the SSH key to the server, click the "refresh" icon next to the server's Connection Status indicator. Envoyer will attempt to connect to your server and run a few health checks on the server, such as attempting to restart PHP FPM (if it is installed on the server).

Note: If Envoyer was unable to restart PHP FPM, you will receive an alert on your project overview. The information modal for the alert will provide the command needed to allow Envoyer to restart FPM without a password.

Envoyer IP Addresses

If you need to white-list the Envoyer IP addresses to allow Envoyer to access your server, you should white-list the following addresses:

  • 138.197.10.48
  • 159.203.66.107

The Project Path

The project path is where Envoyer will place several directories on your server: the releases directory, the current symbolic link, and the storage directory (if deploying a Laravel project).

The releases directory contains the last few deployments of your project. The current symbolic link points to the latest release of your project. The storage directory, when deploying a Laravel project, contains the files stored by your application - this directory is automatically kept consistent across deployments so you do not lose its contents on each deploy.

Envoyer will automatically create these directories within your project path as necessary.

Deployment Lifecycle

When a deployment is triggered for your project, Envoyer will execute your deployment plan. By default, this consists of downloading a tarball of your project, installing the Composer dependencies, pointing the current symbolic link at the latest release, and finally purging any old deployments from your server.

Of course, any deployment hooks you have configured will also be run during the deployment.

Managing Uploaded Files

When storing user uploaded files, you should store them in the storage directory of your application if you are using Laravel. Then, you may use the "Manage Linked Folders" feature of Envoyer to create a symbolic link from your public directory to the storage directory. The "Manage Linked Folders" button can be found on the "Deployment Hooks" tab of your project.

If you are not using Laravel, you will essentially follow the same process. However, you will need to manually create a storage directory in the deployment path of your application (the same directory level as the current symbolic link).

Deployments

Cancelling Deployments

If any deployment step or deployment hook exits with a non-zero status code, the entire deployment will be cancelled so your customers do not experience downtime from a broken deployment.

Redeploying Previous Commits

The Redeploy button on your Recent Deployments list allows you to deploy a recent, previous deployment commit. This feature allows you to quickly "rollback" a problematic deployment. When redeploying a previous commit, the normal deployment process will be followed, including all hooks.

Servers

Receiving Code Deployments

When you add a server to your project, you have the option of specifying if your server should receive code deployments. Most servers on your project will probably receive code deployments; however, you may sometimes want to add servers, such as database servers, that do not receive code. Adding these servers allows you to run hooks on the servers without deploying your entire project to them.

Connection Status

The server connection status indicates if Envoyer is able to SSH into your server. In addition, if PHP FPM is installed on your server, Envoyer will attempt to restart it. If Envoyer is not able to restart FPM, you will receive an alert on your project overview. The alert information modal will provide the necessary command to allow Envoyer to restart FPM on your server without a password.

Deployment Hooks

Adding Deployment Hooks

Deployment hooks allow you to customize your entire deployment plan. You may add hooks that run before or after any step in your deployment. You may also specify the servers on which each hook is executed.

Like any other step during your deployment, if a deployment hook exits with a non-zero status code, the entire deployment will be cancelled. This prevents your customers from experiencing downtime with a broken deployment.

Hook Variables

Within your deployment hook script, you may use the release Envoyer variable to access the most current release directory. For example:

cd {{ release }}

php artisan command

The project variable provides access to the project's root (the directory which contains current, releases, and storage):

cd {{ project }}

php artisan command

The sha variable provides access to the commit hash being deployed:

{{ sha }}

The time variable provides access to the timestamp of the current deployment formatted as YmdHis:

{{ time }}

The project variable provides access to the deployment path as defined within the server config:

{{ project }}

Note that variables can be written with or without a space inside of the braces.

{{ variable }}

Is the same as:

{{variable}}
Heartbeats

Overview

Heartbeats provide a monitoring mechanism for your Cron jobs or any other scheduled task performed by your application. You may select from a variety of schedule frequencies when creating the heartbeat. So, for example, if your scheduled job runs daily, you should select the 1 Day monitoring option.

After creating a heartbeat, a unique URL will be assigned to the heartbeat. When this URL is called via a HTTP GET request, the "Last Check-In" time of your heartbeat will be updated.

If Envoyer does not receive a check-in from your job within the specified monitoring frequency, a notification will be sent to your configured notification channels.

Calling Heartbeat URLs Manually

If you are manually modifying your server's /etc/crontab file to add Cron jobs, you can simply append a curl request to your Cron command. For example:

* * * * * user php command && curl http://beats.envoyer.io/heartbeat-id

Calling Heartbeat URLs With Laravel 5

If you are using Laravel 5's Cron scheduler, you may use the thenPing method on your scheduled job:

$schedule->command('foo')->thenPing('http://beats.envoyer.io/heartbeat-id');