Quickstart¶
The easiest way to get started is to run Freight on Heroku:
Requirements¶
Note
Freight is designed to support behind-firewall installation. However, this guide does not yet cover all required configuration.
If you’re not using Heroku, you’ll need to ensure a few server dependencies:
- Redis
- PostgreSQL
- Python 2.7
- Node.js
Dependencies¶
Freight contains dependencies both from Python (for the API and workers) and JavaScript (for the frontend). We recommend using a virtualenv, but we’re not going to cover that in our quickstart guide.
Start by installing Python dependencies:
python setup.py develop
And then install the JavaScript dependencies:
npm install
Configuration¶
Configuration can be managed either via a Python file, or selectively via environment variables. Generally there are sane defaults available where appropriate, though many things are install-specific.
If you’re using a configuration file you’ll need to pass it with FREIGHT_CONF
environment variable:
FREIGHT_CONF=/tmp/freight.conf.py bin/web
The following values should be configured:
-
API_KEY
¶
The API key clients will use to communicate with Freight.
-
SSH_PRIVATE_KEY
¶
The SSH private key required for cloning repositories (newlines replaced with
\n
). This will also be made available to providers as a file-system resource.
-
DEFAULT_TIMEOUT
¶
The default timeout for deploys.
Google Authentication¶
The frontend currently only supports authenticating with Google. You’ll need a Google Developer account in order to create an OAuth2 webserver application. Set its Redirect URI to $HOST/auth/complete/.
-
GOOGLE_CLIENT_ID
¶
The client ID for the Google application.
-
GOOGLE_CLIENT_SECRET
¶
The client ID for the Google application.
-
GOOGLE_DOMAIN
¶
The Google Apps domain to restrict authentication to.
GitHub Checks¶
To integrate GitHub context checks you’ll need to generate an API token:
curlish https://api.github.com/authorizations \
-u your-username \
-X POST \
-J scopes='repo' \
-J note='freight'
The following configuration is available:
-
GITHUB_TOKEN
¶
The generated API token.
-
GITHUB_API_ROOT
¶
The base URL for the API. Defaults to
https://api.github.com
Bootstrap the Database¶
Note
If you’re on Heroku, you can skip this step.
If you haven’t already, create a new database for Freight:
createdb -E utf-8 freight
Now apply Freight’s migrations:
bin/upgrade
Webserver¶
At this point you should have a working installation. To test this, launch the webserver:
bin/web
You should then be able to access the frontend: http://localhost:5000
Creating an Application¶
Note
Our examples will use the Curlish utility and the local server with its default key.
With the webserver online, you should be able to access the API. The first thing you’ll need to do is create an application:
curlish http://localhost:5000/api/0/apps/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70' \
-X POST \
-J repository=git@github.com:my-organization/example.git \
-J name=example \
-J provider=shell \
-J provider_config='{"command": "bin/fab -a -i {ssh_key} -R {environment} {task}:sha={sha}"}'
We’ve created a new application named “example” using the shell provider.
The important part here is our provider configuration:
{
"command": "bin/fab -a -i {ssh_key} -R {environment} {task}:sha={sha}"
}
The command we’re passing is simply a wrapper around Fabric:
#!/bin/bash
# Usage: bin/fab [arguments]
# Wrapper around Fabric which ensures any required dependencies are installed.
pip install fabric pytz
fab $@
Note
This bin/fab file is not part of Freight, but rather it’s referencing a path relative to your repository root.
Creating a new Deploy¶
Once we’ve configured our application we can create a new deploy:
curlish http://localhost:5000/api/0/tasks/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70' \
-X POST \
-J app=example \
-J ref=master \
-J task=deploy \
-J user="user@example.com"
In our response we’ll get back the task summary which simply notes its pending and gives you it’s ID:
{
"id": "1",
"status": "pending"
}
Monitoring a Deploy¶
While Freight intends to provide a feature-rich frontend, it’s fundamentally an API-driven application.
For example, to get the status of a deploy:
curlish http://localhost:5000/api/0/tasks/1/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70'
Additionally you can access the logs via the API:
curlish http://localhost:5000/api/0/tasks/1/log/?offset=-1&limit=1000 \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70'
Rolling Back¶
While Freight doesn’t formally offer a first-class rollback control, you can tell it to deploy the previous stable:
curlish http://localhost:5000/api/0/tasks/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70' \
-X POST \
-J app=example \
-J ref=:previous \
-J task=deploy \
-J user="user@example.com"
Setting up Slack notifications¶
First of all, head to Slack and create a “webhook” integration.
curlish https://scurri-freight-test.herokuapp.com/api/0/apps/1/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70' \
-X POST \
-J notifiers='[{"type":"slack", "config": {"webhook_url": "https://hooks.slack.com/services/XXX/YYY/ZZZ"}}]'
Setting up Github checks¶
In this case, only the CircleCI checks will be considered.
curlish https://scurri-freight-test.herokuapp.com/api/0/apps/1/ \
-H 'Authorization: Key 3e84744ab2714151b1db789df82b41c0021958fe4d77406e9c0947c34f5c5a70' \
-X POST \
-J checks='[{"type": "github", "config": {"contexts": ["ci/circleci"], "repo": "my-organization/example"}}]'
Next Steps¶
To learn more about other checks/notifiers, we recommend diving into the code.