How to use Deployments
Deploying From Version Control Branches using Beanstalk
The biggest benefit of deploying from version control isn't the ease or the speed - though those are benefits. The biggest benefit is the peace of mind that comes from being able to easily and quickly deploy anytime you want or need. By correctly using branches in your workflow, you can get the most benefit from Beanstalk's deployment tools.
Using Beanstalk Deployment Environments
The rest of this guide will take you through the steps for using Beanstalk's deployment tools to deploy code changes (additions and deletions) from environment branches in your repositories to the corresponding deployment environments.
A deployment environment includes a server or a grouping of servers that you'll be deploying your changes to each time you trigger a deployment. It's easy to think about environments as logical groupings, things like "production" and "staging", that match the environment branches you've created in your repository.
One important aspect about configuring your deployment environments is consistency: every time a deployment is triggered, it's run exactly the same way. This means that it's not only saving you time by being automated, but it reduces the opportunity for mistakes to slip into your deployments.
During the first step of creating and configuring a new deployment environment, you'll be asked to choose "automatic" or "manual" deployment mode.
Deploy Automatically
If you choose automatic deployment mode, Beanstalk will initiate a deployment to the server or servers in that environment each time you commit (SVN) or push (Git).
Automatic deployment mode is ideal if you have a remote development environment, and depending on your team's workflow, to staging.
Deploy Manually
Choosing manual deployment mode will require you to instruct Beanstalk to initiate a deployment when you are ready.
Manual deployments can be triggered two ways - by clicking a button in the Beanstalk web app, or by including a "tag" to your commit message that specifies the environment name. For example, putting the tag [deploy:staging] in your commit message would trigger a deployment to your staging servers.
Matching a repo branch to an environment
Now that you've started using branching properly in your repository, Beanstalk will help you choose a branch to match with your new deployment environment. If you do not see branches other than trunk or master, you may not be properly using branches in Beanstalk.
Server Connection Types
Environments are collections of servers, so you'll need to add one server in each environment in order to deploy to that environment. Beanstalk supports 3 types of deployment server connections: FTP, SFTP, and SSH.
FTP
The simplest deployment server option is FTP. Choosing FTP means that the server you're trying to deploy to accepts connections over
Beanstalk will allow you to specify a repository path to deploy from as well. This means that you can be specific about the directory within your repo that Beanstalk should copy files from.
When Beanstalk deploys files over FTP, it performs smart differential copies to the remote server. This means that it will only deploy files that have been added or updated in your repo (or remove files that have been deleted) since the last deployment. This ensures that deployments are as fast as possible. If desired, you can optionally redeploy all files, resetting the differential for the next deployment.
Beanstalk will also automatically create release notes and a detailed changelog that will help with informing your team of changes included in a deployment or debugging problems with deployed code.
SFTP
FTP is not always available, and doesn't provide the most secure way to transfer files. SFTP offers a more secure connection with similar configuration to FTP. It also provides the option to connect using SSH keys instead of passwords. Other than connection method, SFTP and FTP have identical options.
And just like FTP, Beanstalk's SFTP deployments are smart differential copies with an option to redeploy all files.
SSH
SSH deployments are the newest addition to Beanstalk and allow for more advanced deployment techniques that are preferred for some CMS platforms and web applications. SSH deployments allow you to configure a set of SSH commands to be run on your remote server over a
SSH connections are a way to securely connect to a remote server and run commands. Like SFTP, depending on your server configuration you can connect to a remote host with a username and password or using an SSH key for authentication.
Once configured, Beanstalk will execute these commands every time you trigger the deployment with a commit or manual/tag deployment.
SSH deployments follow some basic rules:
- Each command should be on a separate line.
- Each line will be executed separately.
- Each line that begins with the # character will be treated as a comment.
- Lines are executed in a strict order from top to bottom.
- If a line fails, the next line will not be executed and the deployment will fail.
- Environment variables between lines are not shared.
- Each line is executed in the context of the user home directory.
- The cd command is not carried to the next line. Please use absolute paths instead.
- You can use special variables in commands.
Within these rules, you can run commands such as changing directories and executing an svn up or git pull, run Capistrano or Fabric deploy scripts, restart web servers, clearing caches, anything your SSH user has been given permission to execute.
With great power comes great responsibility
Please, be careful with SSH deployments. While they are extremely flexible and powerful, you are wholly responsible for the result of the commands configured to be run by Beanstalk Deployments. Please be careful and double check the commands before continuing.
Executing tasks before and after deployments
Depending on the complexity of your website or application, you might need to script certain tasks to happen before or after files are deployed. Some examples of these tasks might be renaming of certain configuration files, recompiling code, restarting of your Apache or Nginx, and busting cache - but the possibilities are 100% dependent on your application and web server configuration.
To put this control in your hands, Beanstalk allows you to trigger scripted tasks before and after the deployment takes place using Webhooks. A Webhook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. Our HTTP posts contain a JSON document that includes information about the deployment.
You'll be responsible for writing and configuring your own webhooks since they live on your servers and are specific to your application, and you'll need to make them available at a URL that is accessible from any internet connection.
Best Practices with Automated Deployments
Configuring your deployments may seem like a lot of work, but it's a lot of work that you only have to do one time. Here are some of the best practices that come along with automated deployments:
- Using environment branches ensures that only approved code gets on your servers.
- Deploying from environment branches lets you see what code is currently deployed.
- Deploying only changes since the last deployment makes operations faster.