Skip to content

Instantly share code, notes, and snippets.

Last active March 25, 2020 01:26
Show Gist options
  • Save jtimberman/f939e9c822c581bc7168026f3fa4211c to your computer and use it in GitHub Desktop.
Save jtimberman/f939e9c822c581bc7168026f3fa4211c to your computer and use it in GitHub Desktop.


You'll need to have a system running that is accessible through a DNS record. It should have access to the public Habitat depot, so it can download the required packages.

You'll need to register an OAuth application for GitHub. You need the client ID and client secret that are created for the application later in this guide. Your system needs to have access to so that it can authenticate.

Your system also needs to have an FQDN that can be resolved, for example This will be used in your OAuth application's "Authorization Callback URL." For this example, use The /#/sign-in is required.

Operating System

For these instructions, we used an Ubuntu 16.04 system running in Amazon EC2.

aws ec2 run-instances --image-id ami-367bab56 --instance-type m3.large --security-group-ids sg-0ac13d73 --count 1 --key-name jtimberman --region us-west-2

We run the applications as the hab user.

adduser --group hab
useradd -g hab hab

Bootstrap Habitat

Download Habitat for Linux from our downloads page. This is a .tar.gz file containing the hab binary. Copy it to the target system. The filename will be something like hab-0.10.2-20160930230245-x86_64-linux.tar.gz (the actual version and release may be different). If you wish to download it directly on that system, install wget and use it to download Habitat.

wget "" -O hab-latest.tar.gz

Once you have the .tar.gz on the target system, extract the hab binary (replace hab-latest.tar.gz with the filename you used).

tar -zxf hab-latest.tar.gz

Install the full core/hab package. This ensures it is in the required location, and that the core origin key is downloaded. Replace 0.10.2 and 20160930230245 with the version and release of the directory that was extracted.

./hab-0.10.2-20160930230245-x86_64-linux/hab install core/hab

Create a symlink for the hab binary in the $PATH (/bin).

/hab/pkgs/core/hab/0.10.2/20160930230245/bin/hab pkg binlink core/hab hab

Setup the Supervisor and Director

Install the supervisor and director packages so we can start the Depot services.

hab install core/hab-sup
hab install core/hab-director
hab pkg binlink core/hab-director hab-director

Write the director's configuration file in its own directory - this is not the service directory.

mkdir -p /hab/etc/director

The actual configuration is a .toml file. The private designation here indicates the logical environment. For example, a "private" depot.

cat <<-EOF > /hab/etc/director/config.toml
start = "--permanent-peer"

start = "--permanent-peer"

start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

start = "--permanent-peer --bind router:hab-builder-router.private"

Write out the API custom user configuration. This goes in the API service directory, which needs to be created as we have not yet started the service. Use the FQDN as described in the requirements above.

mkdir -p /hab/svc/hab-builder-api/config

Replace the client_id and client_secret with your GitHub OAuth application's values. Replace the app_url's FQDN with your FQDN. The /v1 is required. The environment should match what we wrote in the director configuration earlier, private.

cat <<-EOF > /hab/svc/hab-builder-api/user.toml
client_id       = "your-oauth-app-client-id"
client_secret   = "your-oauth-app-client-secret"

app_url         = ""
community_url   = ""
docs_url        = ""
environment     = "private"
friends_only    = false
source_code_url = ""
tutorials_url   = ""
www_url         = ""

The session service needs to have the OAuth authentication, too.

mkdir -p /hab/svc/hab-builder-sessionsrv
cat <<-EOF > /hab/svc/hab-builder-sessionsrv/user.toml
client_id       = "your-oauth-app-client-id"
client_secret   = "your-oauth-app-client-secret"

Start everything with the Director

We need to ensure that root CA certificates can be found by Habitat, as it won't look for them in the OS location.

export SSL_CERT_FILE=$(hab pkg path core/cacerts)/ssl/cert.pem

Start the director with the configuration we wrote out earlier.

/bin/hab-director start -c /hab/etc/director/config.toml
Copy link

bixu commented Dec 3, 2016

Nice work so far!
I've set client_id, client_secret and fqdn attributes on my depot, and have a public IP and globally-addressable FQDN on that interface, but when I try to sign in I get this error in the depot UI:

Authentication Failed

Unable to retrieve GitHub token

How to debug? This is my first go-round with Github OAuth in a privately-hosted app.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment