> For the complete documentation index, see [llms.txt](https://docs.stoobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app.md).

# How to Scaffold an App

## Background

See this page for what Scaffold is:

{% content-ref url="/pages/hvGjzhgu6l2Nw4iB48E6" %}
[Scaffold](/core-concepts/scaffold.md)
{% endcontent-ref %}

## Prerequisites

{% hint style="info" %}
We currently only support Docker for containerization
{% endhint %}

1. Install Docker <https://docs.docker.com/engine/install/>
2. After installation ensure that `docker compose` is a valid command

## Steps to Scaffold an App

{% hint style="info" %}
`stoobly-agent scaffold apply` requires **stoobly-agent v2.5.0 or later**.
{% endhint %}

**Recommended:** Describe your app and its services in a declarative `.stoobly/scaffold.yml`, then apply it. This keeps the whole setup reviewable, version-controlled, and reproducible by teammates with one command.

1. In the root directory of a version-controlled code repository, create `.stoobly/scaffold.yml`:

```yaml
# .stoobly/scaffold.yml
version: 1
commands:
  - resource: app
    action: create
    options:
      app_name: <APP-NAME>
      # For E2E testing, add plugin: [playwright] or plugin: [cypress]
      plugin: [playwright]

  - resource: service
    action: create
    options:
      service_name: <SERVICE-NAME>
      hostname: <SERVICE-HOSTNAME>
      scheme: <SERVICE-SCHEME>
      port: <SERVICE-PORT>

  # Add one service block per service. Repeat as needed.
```

2. Validate, then apply:

```bash
stoobly-agent scaffold apply .stoobly/scaffold.yml --dry-run
stoobly-agent scaffold apply .stoobly/scaffold.yml
```

3. A `.stoobly` [context](/core-concepts/context.md) will be created in the app directory if it does not already exist
   1. Inside the context folder, a `docker` folder will be created with initial core services

For the full walkthrough and the complete config schema:

{% content-ref url="/pages/IsP4sqSmIxdC4r86BS5O" %}
[Applying a Scaffold Config](/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app/applying-a-scaffold-config.md)
{% endcontent-ref %}

{% content-ref url="/pages/vNbSv8Y3FUGMz3PL3GyX" %}
[Apply](/faq/scaffold/apply.md)
{% endcontent-ref %}

## Alternative: Individual CLI Commands

You can also run the underlying commands directly instead of writing a config file — useful for one-off scaffolds or quick experiments.

1. Run the scaffold app create command in the root of your app directory.

```bash
stoobly-agent scaffold app create <APP-NAME>
```

{% hint style="info" %}
**Recommended for E2E Testing:** Include `--plugin playwright` or `--plugin cypress` when creating the app scaffold. This sets up Playwright or Cypress-specific configurations and dependencies for running E2E tests.
{% endhint %}

{% hint style="info" %}
We recommend running this command from the root directory of a version-controlled code repository.
{% endhint %}

2. A `.stoobly` [context](/core-concepts/context.md) will be created in the app directory if it does not already exist
   1. Inside the context folder, a `docker` folder will be created with initial core services

To add a service the same way:

{% content-ref url="/pages/BKCC6lKg9jOIW8EYkhK8" %}
[Scaffolding a Service](/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app/scaffolding-a-service.md)
{% endcontent-ref %}