Preparing for your first deployment
Before you can run your first deployment, you'll need create a project and allow DeployHQ access to your repository, then add one or more servers to deploy to.
In this chapter we'll be running through the following processes:
To create your new project, head to the Projects tab at the top of the screen, then click New Project on the right hand side of the page:
Enter a name, then if you want to take advantage of a Template at this stage, we'll be covering templates in more detail in the Templates chapter of the DeployHQ manual.
Next, choose from one of the supported SCMs if you have your code hosted there. Otherwise, if you're using a different service or hosting the repository on your own servers, you can choose the option to Manually enter repository details.
DeployHQ can deploy from a Git, Mercurial or SVN repository hosted anywhere. If your repository is hosted on Bitbucket, Codebase, Gitlab or Github you can connect to it simply by logging in with your account with the provider, then choosing from a list of projects and repositories that you have access to.
Once you've done so, DeployHQ will connect to the repository and add your new project's public key as a deployment key where appropriate, so that we can access and clone the repository.
When you first create your project, choose Bitbucket under the Where is your repository hosted? area. Then you will be taken to Bitbucket's website, where you can login and authorise access:
Once you click Grant Access, a list of your Bitbucket repositories will appear in Deploy. Just select the repository you want to add, and DeployHQ will do the rest.
When you first create your project, choose Codebase under the Where is your repository hosted? area. You'll then need to login to Codebase if you haven't already done so, and you'll be prompted to Allow Access via our SSO service aTech Identity:
Next a list of projects will be pulled from your Codebase account, from which you can choose the repository you want to add to the project. Once you have selected your repository, DeployHQ will do the rest.
When you first create your project, choose Github under the Where is your repository hosted? area. Then you will be taken to Github's website, where you can login and authorise access:
Once you click Authorize atech, a list of your Github repositories will appear in DeployHQ. Just select the repository you want to add, and DeployHQ will do the rest.
When you first create your project, choose Gitlab under the Where is your repository hosted? area. Then you will be taken to Gitlab's website, where you can login and authorise access:
Once you click Authorize, a list of your Gitlab repositories will appear in DeployHQ. Just select the repository you want to add, and Deploy will do the rest.
If you wish to enter details for a repository other than Codebase, Bitbucket, Github or Gitlab, click Manually enter repository details.
Enter the full URL to the repository, a custom port if it is required, and the default branch you wish to deploy from. You can view the public key at this point if you wish to add it to your repository server's authorized keys. This can be accessed later otherwise from the repository settings menu.
If you want to add the deployment key manually to any of the main repository hosts, see the following articles with further information about how to do this below:
Please note, if wish to add an SVN repository, we only support HTTP(s) with username and password authentication.
If you have a repository hosted elsewhere, such as on your own repository server, you can connect to this too. Just use the manual option, then paste the URL you'd normally use to access the repository in your project settings, then add the project's public key to your repository server's
authorized_keys file if you're connecting via SSH, or enter your username and password if you're connecting via HTTP.
Finally, if you're connecting to a self-hosted repository service that we support automatic deployments from, in particular Gitlab, select this under the Hosting Service dropdown.
In your DeployHQ project, a server is simply an endpoint that you connect and deploy your code to. DeployHQ can deploy your code to pretty much anywhere, using standard protocols such as SSH/SFTP, FTP or FTPS to connect to your servers. As well as this, we support a number of services such as Rackspace Cloud Files or Amazon S3.
You can add the new server to your project by heading to the Servers & Groups page in your project, then clicking the New Server button on the right hand side of the page.
Enter a name for your server so you can easily identify it in the future, then optionally choose a server group (we'll be covering these in the Working with multiple servers chapter.
Next, choose the appropriate protocol you want to connect to your server with, with links below to more information about configuring each protocol:
Once you've configured your connection details, enter the Deployment Path - the directory on the server where you want your code to be uploaded to, for example public_html/, then when you are finished click Create Server. DeployHQ will check your connection and present you with a list of your servers.
Enter the hostname of your server, then enter the port your server is listening on (if you haven't changed this you can leave this field blank and DeployHQ will use the default port 22).
Enter your username and if you're using password authentication, your password. Alternatively, if you'd rather use SSH keys to authenticate check the use SSH key rather than password for authentication box. You can find the appropriate public key to add to the appropriate
authorized_keys file on your server by clicking here underneath the Use SSH key checkbox.
Enter the hostname and port your FTP server is listening on (if you haven't changed this you can leave this field blank and DeployHQ will use the default port 21).
Enter your username and password, then enable passive (PASV) mode if your server supports it. Finally, if your FTP server doesn't report hidden files such as .gitignore by default, you can enable the option to Force the server to report hidden files.
Enter the server's hostname and the port your FTP server is listening on (if you haven't changed this you can leave this field blank and Deploy will use the default port 21).
Then enter your username and password, and enable the option if the connection is Implicit. Next enable the option if necessary to Ignore TLS/SSL certificate errors (you will need to do this if are connecting using a self signed certificate).
Deploy will connect to your server using TLS v1.0 by default, but if you need to connect using a specific version you can select it via the TLS version dropdown. Enable passive mode (PASV) if your server supports it, then if your FTP server doesn't report hidden files such as .gitignore by default, you can enable the option to Force the server to report hidden files.
Enter your Bucket name, then the Access ID and secret key.
Finally, if you want to upload your files to a different folder from your Bucket's root directory, enter the directory in the Path Prefix.
If you're having trouble adding your bucket, we recommend checking our troubleshooting guide for setting a minimum policy to allow connections from DeployHQ.
Select the Rackspace region for the Region dropdown, then enter a container name.
Next enter the username and API to authenticate with your instance, then if you want to upload your files to a different folder from your instance's root directory, enter the directory in the Path Prefix.
Once you've added your repository and server, you can go ahead and run your first deployment! To start your deployment, either click the Deploy Project button at the top of the screen from any page in your project, or the New Deployment button within your Overview page:
DeployHQ prepares a deployment by checking the last revision that was deployed to your server, then comparing it to the latest one pushed to the remote branch, therefore when you deploy to a server for the first time, DeployHQ will upload the whole repository.
As a result, you'll see the Start Revision, the commit that your files will be deployed from, set to "The very first commit":
If you already have your files on your server and want to skip this, you can find out how to do so within the Advanced Configuration chapter of the DeployHQ manual.
Once you're happy with the configuration for your deployment, hit Deploy and your deployment will start, otherwise, you can press Preview and DeployHQ will generate a full list of changes that will be included in your deployment, allowing you to check before starting it.
If you're happy with the preview deployment, you can start it by clicking the Run Deployment button below the list of changed files.
When you start a deployment, the process consists of several stages, which we will outline in further detail below.
During this stage, we'll check connections to your server and repository, then if these tests pass we will checkout a working copy of your repository at the specified end revision, then update it from its source.
If you have build commands configured, these will be run, then a manifest of your changes will be prepared for deployment.
During this stage, DeployHQ will connect to your server, then run any configured pre-transfer SSH commands. You can find out more about setting up SSH commands in the Advanced Configuration chapter of the DeployHQ manual. After this, all files will be uploaded or removed as appropriate. The Transferring files section will show a progress bar of all the files as they're being transferred, and you can toggle Show file destinations? to display the path on the your server that the files are being uploaded to.
Finally, any configuration files set up for this server and deployment will be uploaded, then any configured post-transfer SSH commands will be run.
At this point, any configured notifications will be delivered, then emails will be sent to configured recipients with the status of the deployment.
You've now completed your first deployment! For more advanced settings, head to our the Advanced configuration chapter via the button below.