Skip to content
No description, website, or topics provided.
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update Jan 22, 2019
config Add xfs-progs 4.20.0 blob Mar 13, 2019
docs Nit-pick clarification Mar 13, 2019
jobs Enable containerd rootless deployment Mar 21, 2019
manifests Bump bpm to 1.0.3 Feb 14, 2019
packages Containerd packaging uses common go script Mar 22, 2019
releases/garden-runc release v1.19.1 Mar 20, 2019
.envrc Move everything that needs GOPATH to a new GOPATH Mar 15, 2019
.gitignore Guardian is not in the gopath Mar 18, 2019
.gitmodules Move grootfs out of the gopath Mar 18, 2019
LICENSE Initial commit. Sep 7, 2015
NOTICE Ensure ordnance-survey does the same as dontpanic Feb 12, 2019

Garden-runC Release

A BOSH release for deploying Guardian.

Guardian is a simple single-host OCI container manager. It implements the Garden API which is used in Cloud Foundry.

Getting started

Clone it:

git clone
cd garden-runc-release
git submodule update --init --recursive


The easiest way to run Garden-runC is to deploy it with BOSH Lite, a VirtualBox development environment for BOSH. Once you have set up bosh-lite (follow the instructions in the bosh-lite docs), just deploy like any bosh release, e.g:

cd garden-runc-release # if you're not already there

You can retrieve the address of the Garden-runC server by running bosh vms. It will be if using the provided deploy-lite script. The server port defaults to 7777.


The easiest way to start creating containers is to use the gaol command line client.

e.g. gaol -t create -n my-container

For more advanced use cases, you'll need to use the Garden client package for Golang.

Operating garden-runc

Operator's guide.

Security Features

The following doc provides an overview of security features on Garden vs Docker vs Kubernetes.

Security overview.

Rootless containers

Garden has experimental support for running containers without requiring root privileges. Take a look at the doc for further info.

If you would like to enable rootless containers please read this document.


In order to help us extend Garden-runC, we recommend opening a Github issue to describe the proposed features or changes. We also welcome pull requests.

You can use other distributions or OS X for development since a good chunk of the unit tests work across alternative platforms, and you can run platform specific tests in a VM using Concourse CI.

In order to contribute to the project you may want some of the following installed:

  • Git - Distributed version control system
  • Go - The Go programming language
  • Direnv - Environment management
  • Gosub - Gosub is a submodule based dependency manager for Go
  • Fly CLI - Concourse CLI
  • Virtualbox - Virtualization box
  • Vagrant - Portable dev environment

Garden-runC uses git submodules to maintain its dependencies and components. Some of Garden-runC's important components currently are:

  • Garden found under src/ is the API server and client.
  • Guardian found under src/ is the Garden backend.
  • GrootFS found under src/ downloads and manages root filesystems.
  • GATS found under src/ are the cross-backend integration tests of Garden.


  • Garden Shed, previously found under src/, has now been removed. GrootFS is now the default container rootfs management tool with no option to revert to Shed from versions above 1.16.8.

Set your $GOPATH to the checked out directory, or use Direnv to do this, as below:

direnv allow

Running the tests

Concourse CI is used for running Garden-runC tests in a VM. It provides the Fly CLI for Linux and MacOSX. Instructions for deploying a single VM Concourse using BOSH can be found in the concourse-deployment repo

Once running, navigate to in a web browser and download the Fly CLI using the links found in the bottom-right corner. Place the fly binary somewhere on your $PATH.

The tests use the Ginkgo BDD testing framework.

Assuming you have configured a Concourse and installed Ginkgo, you can run all the tests by executing FLY_TARGET=<your concourse target> ./scripts/test from the top level garden-runc-release directory.

Note: The concourse-lite VM may need to be provisioned with more RAM If you start to see tests failing with 'out of disk' errors.

Integration tests

The integration tests can be executed in Concourse CI by using Fly CLI and executing ./scripts/test. To run individual tests, use./scripts/remote-fly:

# Set your concourse target
export GARDEN_REMOTE_ATC_URL=<target>

# Running Guardian tests
./scripts/remote-fly ci/tasks/guardian.yml

# Running Garden tests
./scripts/remote-fly ci/tasks/garden.yml

# Running Garden Integration tests
./scripts/remote-fly ci/tasks/gdn-linux.yml

# Running Garden Integration Windows Regression tests (aka Gats98)
WINDOWS_TEST_ROOTFS=docker:///microsoft/nanoserver:1709 ./scripts/remote-fly ci/tasks/gdn-linux.yml

Running the tests locally

It is possible to run the integration tests locally on a Linux based OS like Ubuntu, but we don't recommend it due to the dependencies required, and the need for parts of the testing suite to run as a privileged user. If you'd like to run them locally, you will need at least:

  • A recent version of Go (1.8+)
  • Kernel version 4.4+
  • Running as a privileged user
  • AUFS
  • Overlayfs
  • xfs

The tests can be executed without Concourse CLI by running ginkgo -r command for any of the components:

# Running Garden unit tests
cd src/
ginkgo -r

# Running Guardian unit tests
cd src/
ginkgo -r

It should be possible to run the unit tests on any system that satisfies golang build constraints.

Committing code

Write code in a submodule:

cd src/ # for example
git checkout master
git pull
# test, code, test..
git commit
git push

Commit the changes, run the tests, and create a bump commit:

# from the garden-runc directory
./scripts/test-and-bump # or just ./scripts/bump if you've already run the tests


>= v1.17.2: Don't Panic

If you have a problem with garden-runc, don't panic! There is a tool that you can use to gather information useful for debugging issues on garden-runc-release deployments. Run this command on the deployment VM as root:


N.B. From v1.18.3, if your BOSH environment has BPM enabled for Garden, dontpanic should still be run from the host, not from within the BPM container.

<= v1.17.1: ordnance-survey

If running an earlier version of Garden, you can get the same information by running the following as root on the VM:

curl -sSfL | bash

N.B. If your BOSH environment has BPM enabled for Garden, ordnance-survey should still be run from the host, not from within the BPM container.


Apache License 2.0

You can’t perform that action at this time.