gatehouse/heroku repository overview

⁠Gatehouse build system

⁠Quick start

⁠Adding a build task to an existing project

1. Copy the bitbucket-pipelines.yml file from a directory in this repo to the root directory of your project. For example, a Laravel app would need laravel/bitbucket-pipelines.yml copied to your project root.
2. Commit and push the new file to your repo
3. Monitor build status in the project's Pipelines dashboard on Bitbucket or in the History pane of SourceTree
4. When successful, your deployment can be viewed at http://build.gatehousemedia.com/{repo-name}/{branch-name}

⁠Customizing build steps (optional)

• Additional build commands may be added to your project's bitbucket-pipelines.yml as new lines where needed
• Specify custom environment variables, such as a custom directory to use when deploying code, in your project's repo settings under Pipelines > Environment variables to override global values.
• If custom permissions, file/directory exclusions, or additional dependencies are needed, see Updating Docker images below

⁠Under the hood

⁠Environment variables

These are accessible to any repo and may be edited in the global pipeline settings⁠. They may be overridden by defining values in a specific repo's pipeline settings.

Additional built-in environment variables may be seen by running printenv in your pipeline or by reading the Bitbucket documentation⁠.

⁠Using a custom private key

If a custom private key is needed – for example, if using a custom $BUILD_USER or $BUILD_SERVER – it may be added as an environment variable for your project's repo.

First, prepare your key:

# create a new key, if needed
ssh-keygen -t rsa -b 4096 -N '' -f my_ssh_key

# encode the private key
# on Linux:
base64 -w 0 < my_ssh_key

# or on macOS:
base64 < my_ssh_key

Copy the output of the last command above and paste it in your repo's pipeline environment variables as BUILD_KEY. Make sure to select the Secured checkbox so it is encrypted and obscured.

Add the public key (my_ssh_key.pub in this example) to the authorized_keys file on the receiving server's user SSH config and you're ready to go!

⁠Updating Docker images

When additional dependencies or setup commands are needed to run builds, they may be added to docker/bootstrap.sh for a given project type. Similarly, custom permissions, exclusions, or additional deployment steps may be added to docker/deploy.sh.

For this example, we'll use the Laravel image again. Let's assume the awscli package needs to be added. Add awscli to the BUILD_DEPENDENCIES variable in laravel/docker/bootstrap.sh:

#!/bin/bash -x

declare -x BUILD_DEPENDENCIES=(
  awscli
  curl
  git
  ...
)

Now you can push your updates. You need Docker⁠ installed to run these commands.

# log in to Docker as the user `gatehouse` if you're logged out
docker login

# go to the directory where the Dockerfile is stored
cd /path/to/gh_build/laravel/docker

# build the image
docker build -t laravel .

# tag the image as `my-tag`
# note: this tag is arbitrary, so set it with a name that makes sense to you
docker tag laravel gatehouse/laravel:my-tag

# push it
docker push gatehouse/laravel:my-tag

Specifying a tag will allow you to test updates before making them live for all projects that use the image. The tag will need to be added to your project's bitbucket-pipelines.yml file for it to run. For example, if tagging with my-tag, the bitbucket-pipelines.yml file will need to start with:

image: gatehouse/laravel:my-tag
...

When updates are confirmed as working, push them to the master branch of this repo and the Docker image will automatically be built with the latest tag. The tag in your project's bitbucket-pipelines.yml may now be omitted, as latest is assumed when no tag is present.

⁠Creating new Docker images

Copy an existing setup into a new directory in this repo and make modifications as needed, or create one from scratch if you're feeling ambitious.

Follow the steps above using a new image name to build and push the image, then specify the new image name in your project's bitbucket-pipelines.yml file.