All your website configuration (with the exception of custom domain) is contained in the
aerobatic.yml file at the root of your project folder. The only required property is the
id which is the unique Aerobatic identifier of your website. The
aerobatic.yml file is created for you upon running the
aero create CLI command.
There are two additional sections that can be added to the yml file:
deploy block allows specifying config settings that affect how the
aero deploy command works.
deploy: ignore: [*.scss] # Don't deploy .scss files directory: _site # Specifies the directory to deploy ---
Plugins allow you to augment the core static hosting with additional capabilities such as authentication, custom errors, redirects, and more. A growing list of the available plugins can be found in the plugins gallery.
Each plugin is declared in the
plugins array of
aerobatic.yml. The sequence of the array is important as that is the same order the incoming HTTP request passes through. Each plugin has the opportunity to act on the request, either by sending a response (in which case the remaining plugins are never executed), or allowing the request to flow through to the next one.
The http-proxy is an example of a plugin that handles the request directly, so any plugins appearing after it will not get executed (provided the
path is a match). The http-headers plugin, on the other hand, adds some headers to the response, then passes execution along to the next one in the pipeline.
TIP This req / res pipeline pattern will be familiar to developers that have worked with Rack or Express middleware. Aerobatic itself is built atop Express. While it’s somewhat helpful to understand the concept of middleware flow, no experience with Node.js or Ruby is required to deploy websites on Aerobatic.
Here is the basic form for declaring a plugin:
plugins: - name: plugin-name # required - the name of the plugin path: # optional - only invoke if the URL path matches stages:  # optional - only invoke if current deploy stage appears in list options: # depends on the specific plugin option1: true option2: 5
plugins: - name: custom-errors options: errors: 404: errors/404.html - name: basic-auth path: /protected options: username: $BASIC_AUTH_USERNAME password: $BASIC_AUTH_PASSWORD - name: webpage
Notice that the
basic-auth declaration includes a
path property whereas the others do not. This indicates that the plugin should only be invoked if the incoming URL is under the
/protected directory (including nested directories). The other plugins are invoked for all requests assuming the request makes it that far. The
password values are being specified as environment variables - more on that below.
Plugins can include an optional
stages property which specifies when the plugin should be activated. Valid values are
production and the names of any deploy stage such as
A common use case is wanting to lock down only staging instances with the
basic-auth plugin. In the example below visitors to
https://staging.custdomain.net will be prompted for credentials, but not
- name: basic-auth stages: [staging] options: username: $BASIC_AUTH_USERNAME password: $BASIC_AUTH_PASSWORD
You can specify that an alert be sent whenever a deployment completes. The two currently supported alert types are email and Slack. To send an alert for all deployments (regardless of stage), declare YAML like so in your
deploy: alerts: default: # You can specify one or both of these keys email: to: [userA@company.com, userB@company.com] slack: username: 'Website Update' # Optional, defaults to "Aerobatic Deploys" webhookUrl: https://hooks.slack.com/services/xxx/xxx/xxxx ---
To get the
webhookUrl, just add the Incoming Webhook App to your Slack instance. You simply specify which channel you want the alerts to be posted to (i.e. something like “#deployments”) and you’ll be provided the URL to paste into your
aerobatic.yml file. You can also choose an icon or emoji that appears next to each alert.
If you don’t want to store the
webhookUrl in clear text, you can also configure it as an environment variable:
slack: webhookUrl: $SLACK_DEPLOY_ALERT_URL ---
Deploy these changes and you’ll start getting alerts with each new deployment. The alert includes the name of the website, the version name, an optional message, and a hyperlink that launches the site.
The deploy message is a handy way to provide a short description of the what was changed. The message is provided to the
aero deploy command like so:
[$] aero deploy --message "Added new link to the global footer"
There is also the flexibility to define different alerts based on the deploy stage. For example, if you are an agency, you might want to post alerts for all deployments to your team’s internal Slack channel, but additionally send an email alert to the client for production deployments:
deploy: alerts: default: slack: webhookUrl: https://hooks.slack.com/services/xxx/xxx/xxxx production: email: to: [email@example.com] # Alert the client for production deployments ---
You can also omit the
default section altogether and configure alerts on a stage by stage basis - whatever best fits your workflow.
Environment variables can be used to store sensitive configuration settings that you don’t want to hard-code into the
aerobatic.yml file (which you should commit to source-control along with the rest of your project). The basic-auth password is a prime example.
There are two ways to manage environment variables: with the
aero env CLI command and in the control panel web app.
Set an environment variable
[$] aero env --name BASIC_AUTH_PASSWORD --value password123NO
Environment variables can even have different values for different stages. For example maybe you want production and test stages to have different passwords.
Set stage specific values
[$] aero env --name BASIC_AUTH_PASSWORD --value password123NO --stage production [$] aero env --name BASIC_AUTH_PASSWORD --value password456NO --stage test
These environment variables are used at runtime by your website plugins. There is also an
AEROBATIC_API_KEY environment variable which is to be configured with your CI service rather than the
aero env command.