setup-private-habitat-depot.md

Prerequisites

You'll need to have a system running that is accessible through a DNS record. It should have access to the public Habitat depot, https://app.habitat.sh 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 https://github.com so that it can authenticate.

Your system also needs to have an FQDN that can be resolved, for example depot.example.com. This will be used in your OAuth application's "Authorization Callback URL." For this example, use http://depot.example.com/#/sign-in. 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 "https://api.bintray.com/content/habitat/stable/linux/x86_64/hab-%24latest-x86_64-linux.tar.gz?bt_package=hab-x86_64-linux" -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
[cfg.services.core.redis.private]
start = "--permanent-peer"

[cfg.services.core.hab-builder-router.private]
start = "--permanent-peer"

[cfg.services.core.hab-builder-jobsrv.private]
start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

[cfg.services.core.hab-builder-sessionsrv.private]
start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

[cfg.services.core.hab-builder-vault.private]
start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

[cfg.services.core.hab-builder-api.private]
start = "--permanent-peer --bind database:redis.private,router:hab-builder-router.private"

[cfg.services.core.builder-api-proxy.private]
start = "--permanent-peer --bind router:hab-builder-router.private"
EOF

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
[github]
client_id       = "your-oauth-app-client-id"
client_secret   = "your-oauth-app-client-secret"

[ui]
app_url         = "http://depot.example.com/v1"
community_url   = "https://www.habitat.sh/community"
docs_url        = "https://www.habitat.sh/docs"
environment     = "private"
friends_only    = false
source_code_url = "https://github.com/habitat-sh/habitat"
tutorials_url   = "https://www.habitat.sh/tutorials"
www_url         = "https://www.habitat.sh"
EOF

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
[github]
client_id       = "your-oauth-app-client-id"
client_secret   = "your-oauth-app-client-secret"
EOF

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

@juliandunn Updated instructions w/ downloading from bintray instead.

@bdangit I haven't encountered any issues with finding zmq. We can discuss more in slack.

@julian7 That's pretty neat! However that whole section is now rewritten to use the download-from-bintray method :).

@bdangit I saw some zmq issues as well, but not the same ones. I also only saw them when I ran /bin/hab-director start -c /hab/etc/director/config.toml with RUST_LOG=debug and RUST_BACKTRACE=1 set on the environment

@freethejazz ah yea my issues got resolved on its own some how... maybe some race conditions? 😕

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:

DANGER
Authentication Failed

Unable to retrieve GitHub token

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