Introducing StackUp - A Single Application to Spin Up Your Entire Dev Stack

As developers, we often find ourselves working with complex development environments that require a series of steps to set up and tear down. This process can be time-consuming and prone to errors, especially when working in a team where consistency is key. Enter StackUp, a tool that automates the process of spinning up and shutting down your entire development stack.

What is StackUp?

StackUp is a tool designed to simplify the process of setting up and tearing down complex development environments. It allows you to define a series of steps that execute in order on startup and shutdown, as well as a list of server processes that should be started. Additionally, StackUp runs an event loop while the server processes are running, allowing you to run tasks on a cron schedule.

One of the key features of StackUp is its ability to automate routine tasks. With a simple configuration, you can define a sequence of tasks that your project requires, such as starting containers, running database migrations, or seeding data. This automation not only saves you time but also ensures consistency across your development environment.

StackUp also includes a robust precondition system. Before doing anything, checks can be performed to ensure everything is set up correctly. This feature helps prevent common issues that occur when the environment is not properly configured.

Running StackUp

To run StackUp, simply run the binary in a directory containing a stackup.yaml configuration file:

stackup

Or, specify a configuration filename:

stackup --config stackup.dev.yaml

Configuration

The application is configured using a YAML file named stackup.yaml containing five sections: preconditions, tasks, startup, shutdown, and scheduler.

Preconditions

The preconditions section of the configuration file is used to specify a list of conditions that must be met before the tasks and servers can run. Each precondition is defined by a name and a check. The name is a human-readable description of the precondition, and the check is a javascript expression that returns a boolean value indicating whether the precondition is met.

Tasks

The tasks section of the configuration file is used to specify all tasks that can be run during startup, shutdown, as a server, or as a scheduled task.

Startup & Shutdown

The startup and shutdown sections of the configuration define the tasks that should be run synchronously during either startup or shutdown. The values listed must match a defined task id.

Servers

The servers section of the configuration file is used to specify a list of tasks that the application should start as server processes. The values listed must match a defined task id.

Scheduler

The scheduler section of the configuration file is used to specify a list of tasks that the application should run on a schedule. Each entry should contain a task id and a cron expression. The task value must be equal to the id of a task that has been defined.

Example Configurations

StackUp provides several example configurations to get you started.

Let's take a look at an example configuration for a Laravel project:

name: my stack
description: laravel application stack
version: 1.0.0

preconditions:
    - name: dependencies are installed
      check: binaryExists("php")

    - name: project is a laravel application
      check: exists(getCwd() + "/artisan")

startup:
  - task: start-containers
  - task: run-migrations-fresh
  - task: run-migrations-no-seed

shutdown:
  - task: stop-containers

servers:
  - task: horizon-queue
  - task: httpd

scheduler:
    - task: artisan-scheduler
      cron: '* * * * *'

tasks:
  - name: spin up containers
    id: start-containers
    if: exists(getCwd() + "/docker-compose.yml")
    command: docker-compose up -d
    silent: true

  - name: run migrations (rebuild db)
    id: run-migrations-fresh
    if: hasFlag("seed")
    command: php artisan migrate:fresh --seed

  - name: run migrations (no seeding)
    id: run-migrations-no-seed
    if: '!hasFlag("seed")'
    command: php artisan migrate

  - name: stop containers
    id: stop-containers
    if: exists(getCwd() + "/docker-compose.yml")
    command: docker-compose down
    silent: true

  - name: run artisan scheduler
    id: artisan-scheduler
    command: php artisan schedule:run

  - name: horizon queue
    id: horizon-queue
    command: php artisan horizon
    platforms: ['linux', 'darwin']

  - name: httpd
    id: httpd
    command: php artisan serve

Available Functions

Many of the configuration fields can be defined using a javascript expression syntax. To specify an expression to be evaluated, wrap the content in double braces: {{ env("HOME") }}.

Conclusion

StackUp is a powerful tool that can significantly simplify the process of setting up and tearing down complex development environments. By automating routine tasks and ensuring consistency across your development environment, StackUp can save you time and help you avoid common setup errors. Give it a try on your next project!

For more information, please see the StackUp GitHub repository.