piper

Overview

Piper is a command-line utility aimed at simplifying the creation and management of containerized development environments. It uses fixture data from your file system to create environments with the data repositories you need, and applies updates to the repositories as your fixture data changes.

The primary goal of this project is to enhance the developer experience, particularly when starting a new project. It is designed to eliminate the need for time-consuming and error-prone tasks, such as writing and updating seeder scripts, commonly associated with setting up and iterating on an environment.

For documentation regarding specific technologies see docs.

Features

• Environment Creation: Quickly create fully functional development environments
• Hot Reloading: Update data repositories by simply editing your fixtures directory
• Fixture Generation: Generate fixture data using Faker schemas and the Pexels API
• Database Synchronization: Upload and download data objects to and from remote repositories
• Version Control: Maintain an organized log of changes to your data objects and schemas

Requirements

• Docker Engine with Compose V2
• Node.js v16 or higher with npx (only required for generate commands)

Installation

Binary Distributions

Be sure to replace <version> in the commands below with your desired version. You may need to tweak the commands depending on your operating system. If you don't see a binary suitable for your architecture below, check out the releases page.

Linux

curl -LO https://github.com/mitchelldw01/piper/releases/download/<version>/piper_Linux_x86_64.tar.gz && tar -xzf piper_Linux_x86_64.tar.gz && sudo mv piper /usr/local/bin/

macOS

For Intel systems:

curl -LO https://github.com/mitchelldw01/piper/releases/download/<version>/piper_Darwin_x86_64.tar.gz && tar -xzf piper_Darwin_x86_64.tar.gz && sudo mv piper /usr/local/bin/

For Silicon systems:

curl -LO https://github.com/mitchelldw01/piper/releases/download/<version>/piper_Darwin_arm64.tar.gz && tar -xzf piper_Darwin_arm64.tar.gz && sudo mv piper /usr/local/bin/

Install with Go

go install github.com/mitchelldw01/piper

Quick Start

To get started, first navigate to an empty directory and execute the following command:

piper init --mongodb --s3

This will bootstrap your directory with everything necessary to create the environment. Your fixture data will be stored in the piper directory. As it already contains some data, you're all set to initiate the environment.

Begin by verifying the correctness of your Docker setup. This can be done by running the following command:

docker compose up

If the containers build successfully, you'll need to stop them. Afterwards, restart them using Piper this time with the following command:

piper start

Use the Esc key to shut down gracefully when you're done

This command creates the data repositories and objects as defined by your fixtures. In this case, it establishes a MongoDB database and an S3 bucket, both named demo.

As you make additions, changes, and deletions to your fixtures, Piper will apply updates to the repositories accordingly. For instance, try making a change to the MongoDB document located in your fixture data. The terminal output should indicate that the document was updated in the database.

You can also modify the fixture data when Piper is not running. These changes will be applied the next time you start the environment.

Configuration

Add a piper.toml to your project to customize the default start behavior. Other supported file formats include JSON and YAML.

# service names to inherit output from
attach = []

# bucket name to use for S3 downloads
bucket = ""

# build images before starting containers
build = false

# compose files to include when starting containers
files = ["docker-compose.yml"]

# docker profiles to use when starting containers
profiles = []

# refresh the environment from scratch
refresh = false

# watch for file changes and apply updates
watch = true

Command Reference

For documentation regarding commands for specific technologies see docs.

piper init [options]

Initialize a new project

piper init --mongodb --s3

Options

piper start [options]

Start the environment

piper start --attach app --attach test

When using the --refresh option, Piper will determine a list of Docker volume names based on the services in your compose file and the name of your working directory. If the names of your volumes do not conform to <directory>_<service> then the --refresh option will not work as expected.

Options