Ferret — Your local Environment made Easy

What’s the first thing you do when you get a new laptop? For many engineers, it’s setting up a good development environment, which is key for developing and troubleshooting effectively.

Running a local environment helps to speed up the development process as well as improve collaboration. But nowadays, especially in microservices architecture, setting up a local environment has becoming more and more complex, requiring the usage of many different tools (Docker, Shell, NPM, etc.) Documentation explaining how to set up the environment ages fast and is tedious to keep up-to-date.

Imagine a world where your scripting code and documentation coincide and every change in code results in new and improved documentation.

This is where Ferret comes in.

No more “pesky” issues

Ferret is a pipeline composition scripting framework, allowing you to create and reuse predefined scripts in one cohesive YAML file which is both readable and flexible. Instead of writing an instruction manual, such as a README, describing the steps needed to create your setup, you create a YAML file that describes your steps both descriptively and technically.

Ferret transforms the documentation into meaningful steps and executes the code, returning a clear output of the progress and status of the steps used in the pipeline itself.

Ready , Steady , Go!

Note: Currently Ferret supports only MacOS and Linux (Homebrew supported Operating System)

In order to install Ferret, visit https://github.com/salesforce/ferret#readme. Once you’ve completed the installation, let’s showcase Ferret’s capabilities with a few swift examples.

Example 1 , first pipeline:

Let’s assume you want to install Docker on a new computer, either for yourself or during IT provisioning. You are not sure whether it’s there already, but, if it’s not, you want to be sure to install it.

Let’s create a new file called docker-install.yaml with the following content:

stages:
  docker installed:
    description: install docker if it is not installed
    when:
      condition:
        operator: not_contains
        command: docker version
        compareTo: "Server: Docker Engine"
    setup:
      - command: brew install homebrew/cask/docker

  start docker:
    description: start docker if it is not up
    when:
      condition:
        operator: not_contains
        command: docker version
        compareTo: "Server: Docker Engine"
    setup:
      - command: open -a Docker

  check docker is up:
    description: make sure docker server is up
    when:
      timeout: 2m
      retryInterval: 5s
      fail: true
      condition:
        operator: contains
        command: docker version
        compareTo: "Server: Docker Engine"
    setup:
      - command: echo "docker is up"

Now let’s run the following command:

$ ferret setup -f docker-install.yaml

By using a simple condition and checking the Docker version, we decide whether to install Docker or skip it.

If the computer is found to be missing Docker, here’s the output you would get:

But if Docker is already installed, and therefore installation is skipped, you would get this output instead:

Sharing is caring

Ferret allows the reuse of predefined pipelines as steps inside newly created pipelines. To do this, it fetches the pipelines from a Github repository (similar concept to Github Actions) or from a local YAML file and then executes the pipeline. For this to work, we will need to define a Github repository containing predefined pipelines.

$ ferret repository --owner=your-repo-owner --repository=repo-name --branch=master 

In order to see a list of pipelines available, you can run

$ ferret pipelines

and a list of all of the pipeline files stored in your predefined repo will appear.

Then, execute your chosen pipeline:

$ ferret setup --pipeline <PIPELINE_NAME>

Example 2: pipeline composition

Let’s push the previously created pipeline to our common repo and reuse it in a pipeline for installing Minikube:

stages:
  docker installed:
    description: install docker locally if not installed. using pipeline from above
    setup:
      - apply:
          pipeline: docker-install

  minikube install:
    description: install minikube locally if not installed.
    when:
      condition:
        operator: not_contains
        command: minikube version
        compareTo: "minikube version"
    setup:
      - command: brew install minikube

Here we use the docker-install pipeline we created in the first example as a building block to a new pipeline, then we check for whether Minikube is installed and install it if it is not.

Docker and Minikube are just examples of what Ferret can do; the beauty of it is that you get to define what tools your developers need for their environments and build pipelines to make installation easy.

Conclusion

As the above examples demonstrate, Ferret is a swift and agile scripting framework that can save time and can help standardize the setup among all the users in your organization, which eventually means easier debugging and maintenance.

Bill Gates once said: “I choose a lazy person to do a hard job. Because a lazy person will find an easy way to do it.” That’s the power of Ferret: utilizing the “laziness” of great engineers all over the world in creating ready-to-use pipeline steps.

Get started with Ferret here and get your local setup in shape!