stackpad.json Reference

The stackpad.json file defines a multi-service stack that can be deployed as a template on Stackpad. This reference documents the full specification.

Basic structure

{
  "name": "My Template",
  "description": "A template for deploying my stack",
  "inputs": {},
  "sharedEnv": {},
  "services": {}
}

Top-level fields

Field	Type	Required	Description
name	string	Yes	Display name of the template
description	string	No	Short description shown in the template gallery
inputs	object	No	User-provided values when deploying
sharedEnv	object	No	Environment variables shared across all services
services	object	Yes	Service definitions

Inputs

Inputs are values that the user provides when deploying the template. They can be referenced in other parts of the template.

{
  "inputs": {
    "GIT_URL": {
      "type": "string",
      "description": "GitHub repository URL"
    },
    "BRANCH": {
      "type": "string",
      "description": "Branch to deploy",
      "default": "main"
    }
  }
}

Reference inputs with ${{input.GIT_URL}}.

Shared environment variables

Variables defined in sharedEnv are available to all services:

{
  "sharedEnv": {
    "POSTGRES_PASSWORD": "${{secret(32)}}",
    "JWT_SECRET": "${{secret(64)}}",
    "NODE_ENV": "production"
  }
}

Variable interpolation

Templates support three types of interpolation:

Syntax	Description	Example
${{input.NAME}}	Reference a user input	${{input.GIT_URL}}
${{sharedEnv.NAME}}	Reference a shared variable	${{sharedEnv.POSTGRES_PASSWORD}}
${{secret(N)}}	Generate a random secret of N characters	${{secret(32)}}

Services

Each service is defined as a key-value pair in the services object:

Git service

{
  "services": {
    "web": {
      "type": "web",
      "git": {
        "url": "${{input.GIT_URL}}",
        "branch": "main"
      },
      "port": 3000,
      "env": {
        "DATABASE_URL": "postgresql://postgres:${{sharedEnv.POSTGRES_PASSWORD}}@postgres:5432/app"
      },
      "dependsOn": ["postgres"]
    }
  }
}

Docker image service

{
  "services": {
    "postgres": {
      "type": "database",
      "image": "postgres:16",
      "port": 5432,
      "env": {
        "POSTGRES_PASSWORD": "${{sharedEnv.POSTGRES_PASSWORD}}",
        "POSTGRES_DB": "app"
      },
      "volumes": {
        "/var/lib/postgresql/data": "postgres-data"
      }
    }
  }
}

Service fields

Field	Type	Required	Description
type	web | database | cache | service	Yes	Service type
image	string	No*	Docker image to use
git	object	No*	Git repository config
git.url	string	Yes (if git)	Repository URL
git.branch	string	No	Branch name (default: main)
port	number	Yes	Port the service listens on
env	object	No	Service-specific environment variables
dependsOn	string[]	No	Services that must start first
volumes	object	No	Persistent volume mounts
healthCheck	object	No	Custom health check config
exposes	object	No	Connection strings to inject into dependent services

* Either image or git is required, not both.

Dependencies

Use dependsOn to control startup order. A service waits for its dependencies to be healthy before starting:

{
  "services": {
    "web": {
      "dependsOn": ["postgres", "redis"]
    }
  }
}

Exposes

Use exposes to define connection strings that are automatically injected into dependent services:

{
  "services": {
    "postgres": {
      "exposes": {
        "DATABASE_URL": "postgresql://postgres:${{sharedEnv.POSTGRES_PASSWORD}}@postgres:5432/app"
      }
    }
  }
}

Full example

{
  "name": "Next.js + PostgreSQL",
  "description": "Full-stack web application with a PostgreSQL database",
  "inputs": {
    "GIT_URL": {
      "type": "string",
      "description": "Your Next.js repository URL"
    }
  },
  "sharedEnv": {
    "POSTGRES_PASSWORD": "${{secret(32)}}"
  },
  "services": {
    "postgres": {
      "type": "database",
      "image": "postgres:16",
      "port": 5432,
      "env": {
        "POSTGRES_PASSWORD": "${{sharedEnv.POSTGRES_PASSWORD}}",
        "POSTGRES_DB": "app"
      },
      "volumes": {
        "/var/lib/postgresql/data": "postgres-data"
      },
      "exposes": {
        "DATABASE_URL": "postgresql://postgres:${{sharedEnv.POSTGRES_PASSWORD}}@postgres:5432/app"
      }
    },
    "web": {
      "type": "web",
      "git": {
        "url": "${{input.GIT_URL}}",
        "branch": "main"
      },
      "port": 3000,
      "dependsOn": ["postgres"]
    }
  }
}

What’s next?

• Templates overview — see all available templates
• Templates overview — see all available templates