Resources for Developers

Use a Custom Buildpack

If you need to deploy a technology which is not supported by Scalingo, you can used an open-source buildpack or a buildpack you have developed.

To achieve this, you need to define the following environment variable in the environment of the concerned application: BUILDPACK_URL.

Example:

BUILDPACK_URL=https://github.com/cloudfoundry/java-buildpack

Then during the deployment, you’ll be able to see:

<-- Start deployment of my-app -->
-----> Cloning custom buildpack: 'https://github.com/cloudfoundry/java-buildpack'

-- SNIP --

If you need to test a branch of a custom buildpack different than master, specify its name at the end of the URL:

BUILDPACK_URL=https://github.com/cloudfoundry/java-buildpack#branch_name

Build a custom buildpack

Our execution stack is public and can be found as a docker image on the Docker Hub. Its name is scalingo/builder:latest. The base image is based on Ubuntu 14.04, so you’ll find every tool from the ubuntu:14.04 docker image.

Run the following command to start a container in the same environment a custom buildpack will be executed:

docker pull scalingo/builder
docker run --interactive --tty -v /path/to/custom-buildpack:/buildpack scalingo/builder:latest bash

Then if you need to build third-party binaries, you’ll be assured that they will work on our platform.

Architecture of a Buildpack

A buildpack has three mandatory entrypoints:

  • bin/detect: exit with success (return code is 0) if the buildpack applies to the current application.
  • bin/compile: installs the technology.
  • bin/release: handles some metadata.

All these entrypoints are usually Bash script.

Script detect

The purpose of the script located in bin/detect is to detect if the buildpack applies to the application. It takes the build directory in argument. If the buildpack is applicable, the script must print on the standard output the name of the technology and return with the code 0.

Here is an example of such script which detects a buildpack as applicable for our technology if the file biniou.yml is present at the root of the application.

#!/bin/bash

BUILD_DIR=${1:-}

if [ -f "${BUILD_DIR}/biniou.yml" ]; then
  echo "My Wonderful Technology" && exit 0
fi

echo "no" && exit 1

Script compile

The purpose of the script located in bin/compile is to actually compile the application. It is called with three arguments:

  • The build directory: contains the code of the application.
  • The cache directory: used to store information one want to keep between two builds.
  • The environment directory: contains a file per environment variable defined. For instance, an environment variable TEST=1234 leads to a file named TEST containing 1234.

Here is an example of a (very basic) compile script to compile a C application:

#!/bin/bash

BUILD_DIR=${1:-}
CACHE_DIR=${2:-}
ENV_DIR=${3:-}

echo "-----> Install gcc"
apt-get install --yes gcc

echo "-----> Compile the client application"
gcc -o my-app .

Script release

The purpose of the script located in bin/release is to generate some metadata about the application. It takes the build directory in argument. It must print on the standard output a YAML file with a couple of keys:

  • addons: list of addons to install. It is only applied the first time an application is deployed.
  • config_vars: hash of default environment variables.
  • default_process_types: hash of default Procfile entries.

Here is an example of such script for a Node.js application:

#!/bin/bash

cat << EOF
---
addons:
  - scalingo-postgresql
config_vars:
  PATH: /app/bin:/app/vendor/nginx/sbin:/app/vendor/php/bin:/app/vendor/php/sbin:/usr/local/bin:/usr/bin:/bin
default_process_types:
  web: npm start
EOF

Feel free to take inspiration from the various buildpacks proposed by Scalingo: https://github.com/Scalingo?utf8=%E2%9C%93&q=buildpack&type=&language=.


mode_edit Suggest edits