Introducing StackUp - A Single Application to Spin Up Your Entire Dev Stack
Tags: programming, productivity, tooling, news
Published: 2023-07-23 11:05:17

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

![StackUp Logo](https://github.com/permafrost-dev/stackup/raw/main/assets/stackup-app-512px.png)

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](https://github.com/permafrost-dev/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:

```sh
stackup
```

Or, specify a configuration filename:

```sh
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](https://github.com/permafrost-dev/stackup/tree/main/templates) to get you started.

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

```yaml
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](https://github.com/permafrost-dev/stackup).