Batect

build and testing environments as code tool

Batect allows you to define your development tasks (building, running, testing, linting and more) in terms of one or more Docker containers, run those tasks quickly and consistently everywhere, and easily share them with your team.

Batect is:

• 🚀 fast: Tasks start quickly due to parallelisation, run quickly thanks to caching, and clean up reliably every time - we've seen 17% quicker execution than Docker Compose.

• 😌 easy to use: Easily share your development tasks with your whole team, and free them from manual setup of build tools and dependencies for tasks like running your app locally or integration testing. And no installation is required either - just drop the script in your project and Batect takes care of the rest.

• ✨ consistent: Batect uses Docker to create a clean, isolated environment every time you run a task, freeing you from "works on my machine" issues - including on CI. And you can easily share tasks between projects with bundles.

• ✅ versatile: Anything that can run in a Docker container can be run with Batect - builds, unit testing, integration testing, linting, local environments, deployments; frontend, backend or somewhere in between, Batect can do it all.

Hello World

The simplest possible batect.yml:

containers:
  my-container:
    image: alpine:3.11.3

tasks:
  say-hello:
    description: Say hello to the nice person reading the Batect README
    run:
      container: my-container
      command: echo 'Hello world!'

Run it with ./batect say-hello:

$ ./batect say-hello
Running say-hello...
my-container: running echo 'Hello world!'

Hello world!

say-hello finished with exit code 0 in 1.2s.

Get a list of available tasks with ./batect --list-tasks:

$ ./batect --list-tasks
Available tasks:
- say-hello: Say hello to the nice person reading the Batect README

Take a look at the sample projects for more examples.

Getting started

1. Download the latest version of batect and batect.cmd from the releases page, and copy them into your project.

   Note that you only need the scripts - you don't need to download batect.jar.

   The batect and batect.cmd scripts are designed to be committed alongside your project, and not installed globally. Committing them alongside your code improves consistency within your team, as everyone uses the same version of Batect. They will automatically pull down the correct version of Batect for your operating system.

2. If you're on Linux or macOS, make sure the script is executable: run chmod +x batect.

3. Create your batect.yml to define your tasks and the environments they run in:

   • Take a look at the sample projects for inspiration
   • Dive straight into the configuration file reference
   • Follow the getting started tutorial
   • Or, if you're using another tool already and want to switch to Batect, batectify by @ineffyble can convert files from other tools to Batect's format

Requirements

Batect requires Docker 18.03.1 or newer, Java 8 or newer (although this requirement will be removed before v1.0), and:

• On Linux and macOS: Bash and curl
• On Windows: Windows 10 / Windows Server 2016 or later

Batect supports both Linux and Windows containers.

A 64-bit version of Java is required on Windows.

Under the hood

Take a look at the task lifecycle to understand how Batect executes tasks.

Documentation

All documentation is available on the documentation site. Highlights include:

• Introduction
• Getting started tutorial
• Configuration file reference
• Sample projects
• Comparison with other tools

Presentations

• Dockerised local build and testing environments made easy at Container Camp AU (July 2019): video

  Also presented at DevOpsDays Auckland (October 2019), DDD Sydney (September 2019) and DDD Melbourne (August 2019).

• Build & Testing Environments as Code: Because Life's Too Short Not To at Evolution by ThoughtWorks (June 2018): video, slides

Support and community

We use GitHub Discussions for community support and Q&A.

Feedback

Please open an issue on GitHub if you run into a problem or have a suggestion.

You can see what new features and improvements are planned in the roadmap.

Contributing

See the contribution guide.

Acknowledgements

Thank you to the following people for their bug reports, pull requests, suggestions and feedback, in alphabetical order:

• @andeemarks
• @assafw
• @binkley
• @Byron-TW
• @cazgp
• @eichelkrauta
• @ekamara
• @ineffyble
• @jagregory
• @jobasiimwe
• @Letitia-May
• @minnn-minnn
• @pameck
• @safiranugroho
• @Sami5
• ...and everyone else who has used the tool and provided feedback offline

Thank you to YourKit for providing a complimentary copy of the YourKit profiler, and thank you to JFrog for providing a complimentary instance of both Bintray and Artifactory.