StackieAlpha Preview

Block System

Blocks are reusable package specifications that define how to install and run a service. They are the fundamental building unit in Stackie — similar in concept to Docker images, but lighter and integrated with your OS package manager.

What a Block Contains

Each block specifies:

  • Packages to install (e.g., PostgreSQL binaries, Node.js runtime)
  • Configuration files and templates
  • Startup commands and health checks
  • Port declarations for network access
  • Volume mounts for persistent data
  • Dependencies on other blocks

Listing Available Blocks

# List installed blocks
stackie blocks

# Search for a block by name or description
stackie search postgres

Using Blocks in a Stack

Blocks are referenced by name in your stackie-stack.yml:

my-project:
  blocks:
    stackie.postgres:
      serves:
        PORT: { port: 5432, type: db }
    stackie.redis: {}

When a block’s binary dynamically links against a shared library that ships in another block’s installed bin/ directory, declare the relationship with links:. The canonical example is PostgREST, which links against libpq from PostgreSQL:

stackie.postgrest:
  depends_on:
    - stackie.postgres   # start postgres before postgrest
  links:
    - stackie.postgres   # prepend postgres bin/ to postgrest's PATH

At startup, stackie prepends each linked block’s <install_path>/bin to the dependent block’s sandbox PATH. The platform loader then resolves the shared library at runtime:

  • Windows: postgrest.exe finds libpq.dll via PATH (Windows has no rpath / LD_LIBRARY_PATH equivalent — PATH is the DLL search path).
  • macOS / Linux: the same bin/ entry covers libpq.dylib / libpq.so through the standard library search.

links is orthogonal to depends_on:

  • depends_on controls startup order (start postgres first).
  • links controls PATH composition (let postgrest see libpq).

A block that needs a sibling library must list the provider in both fields. tool:true deps are bridged automatically and do not need a links: entry.

Multiple instances of the same block

links references a block type (e.g. stackie.postgres), not a specific stack instance. If a stack contains two postgres instances (e.g. a primary and a replica), both share the same installed <install_path>/bin on disk — so the shared library is identical regardless of which instance the dependent connects to. Instance selection is a runtime concern handled by consumes and block_override, not by links.