Using Preview Deployments
Preview Deployments are automatically generated deployments of newer versions of your application code that run alongside your live application. They are designed to allow you to quickly test changes to your application code without having to deploy to a separate environment.
Preview Deployments are triggered by changes in the git repository of your application - this means that simply pulling new code into your repo can automatically update your Preview (depending on your settings).
Previews run on separate, unique subdomains so they are only visible to your team and those you specifically choose to share them with (such as clients or beta testers)
Preview Deployments only apply to your applications web components - they use the same database(s), and the same environment variables, components and manifest settings as the base application. They are not a truly separate instance of your application and should not be treated as such. We recommend running previews in non-production environments when you are doing rapid feature iterations.
Types of Preview Deployments
We support three kinds of (mutually exclusive) Preview Deployments:
- Branches - creates new Preview Deployments based on git branch names
- Tags - creates new Preview Deployments based on git tag names
- Pull Requests - creates & removes Preview Deployments based on git pull requests
Both branches and tags can be matched using the glob format - so, for example, if you specify
feature* as your branch name, we will create a Preview for any branch with the word “feature” in it.
Previews & database migrations
Preview Deployments run database migrations if needed. As such, please be sure that any database changes are backward-compatible, as both the “live” application and the preview will be use the newly migrated database.
Enabling and disabling Preview Deployments
By default Preview Deployments are disabled. You can enable Preview Deployments via you Cloud 66 Dashboard:
- Log in and click on your application
- Click on Settings & Information in the right-hand column
- Click the Preview Deployments tab at the top of the main panel
- Select the method of Preview Deployment you prefer
- If you select Branches of Tags, you will need to specify at least one name (or glob) to match. You can also specify a branch name for Pull Requests but this is optional.
- Click Save
Once you have enabled Previews for your application, you will need to add the webhook to your git provider to complete the setup (see below).
To disable Previews, follow the same process but select No Preview Deployments instead. Note that this will not remove any previews currently deployed on your servers. To delete previews - see our guide below.
Triggering Preview Deployments via your git provider
In order for your git provider to automatically alert us to the fact that a new branch or tag has been created or pushed, you need to add a webhook URL to your provider.
You can find the webhook URL at the top of the Preview Deployments settings page (under Settings & Information). Copy the URL and then use it to set up the automation with your git provider.
Setting up Previews on GitHub
To enable Preview Deployments on GitHub:
- Log into GitHub and open your app’s repo page
- Click on the Settings tab
- Click on Webhooks in the left-hand nav
- Click the Add Webhook button
- Paste the webhook URL from your dashboard into the Payload URL field
- Under the events section, select “Send me everything”
- Click Add Webhook
Now, every time you add or push a branch or tag that matches the conditions you set in your Dashboard, we will automatically deploy a Preview to your servers.
Monitoring Preview Deployments
Whenever a Preview Deployment is underway, a link will appear on the Previews page that will allow you to follow the logs for that deployment.
If the deployment fails for any reason we will keep the logs, otherwise we will discard them after the deployment is complete.
Browsing and managing Previews
If you have any Deployment Previews active on your servers, a Previews menu-item will appear in your Dashboard’s right-hand navigation column. This page lists all the Previews currently running on your servers, which branch of your code they originate from, and the most recent commit hash.
To browse a Preview:
- Log into your Dashboard and open your app
- Click on Previews in the right-hand column
- Click on the Preview link for the branch you wish to browse - this will open the unique subdomain on which your Preview is hosted.
You can use this URL to share the Preview with people outside of your team, but it should not be made public or used in any DNS settings.
You can manually trigger the redeploy of a Preview by clicking the icon next to it. Bear in mind that we this will redeploy the current commit.
You can use this interface to delete old or unwanted Preview Deployments. To do so, click on the trash-bin icon next to any Preview to delete it. Remember that if you push code to the same branch again, you will also spawn the Preview again.
While we do not limit the number of Previews an app can have, we strongly recommend against having more than a few at any time. By their nature, Previews require resources to run (RAM, CPU cycles etc.) and thus reduce the capacity of your application to serve your visitors. For this reason we recommend running previews in non-production environments when you are doing rapid feature iterations
Deleting Previews using Cloud 66 Toolbelt
You can also list and delete unwanted Previews using the Cloud 66 Toolbelt (cx) to do this use the following commands:
cx stacks variants list -s my-stack --type preview # Lists previews with UIDs cx stacks variants delete [UID] -s my-stack # Deletes a preview by UID