> ## Documentation Index
> Fetch the complete documentation index at: https://sitectl.libops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# create

> Create a new stack from an installed plugin definition.

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

The `create` command provisions a new <Compose /> stack using a create definition registered by an installed plugin. Run `sitectl create list` to see all available definitions, or omit arguments to be guided interactively.

## Reference

Create a new stack using a first-class create definition registered by an installed sitectl plugin.

```bash theme={null}
sitectl create [plugin[/definition]] [args...]
```

## Selecting a definition

You can qualify the target as `plugin/definition` to skip prompts entirely:

```bash theme={null}
sitectl create isle/default
sitectl create drupal/default
```

Or just pass a definition name when it is unambiguous across installed plugins:

```bash theme={null}
sitectl create default
```

## Flag ordering

`create` forwards everything after it to the selected plugin's create runner, so it
does not parse flags itself. Global `sitectl` flags such as `--context` and
`--log-level` must therefore come **before** the `create` subcommand:

```bash theme={null}
# correct: global flags before `create`, create flags after
sitectl --context staging create drupal/default \
  --path ./drupal --type local --checkout-source template --setup-only
```

Putting a global flag after `create` forwards it to the plugin, which rejects it:

```bash theme={null}
# wrong: --context is forwarded to the plugin
sitectl create drupal/default --path ./drupal --context staging
# Error: unknown flag: --context
```

Plugin-specific create flags (for example `--path`, `--type`, `--checkout-source`,
`--setup-only`, or ISLE's `--fcrepo` and `--blazegraph`) still go after the target,
because they belong to the plugin's create runner.

## Template release and provenance

The documented application plugins clone their matching LibOps template from the
stable `v1.0.0` ref by default. Use `--template-branch` only when you deliberately
want another reviewed template ref; do not substitute a moving branch in unattended
creation without recording that decision.

Before sitectl discards the template's Git history, it resolves the exact cloned
commit. It initializes a new repository owned by the site and atomically writes
`.libops/template.lock.yaml`. Commit that file with the downstream fork. It records
the source repository and commit, available sitectl/plugin build identities, the
template contract digest, and the declared component-defaults revision.

The lock is provenance, not an attestation or an automatic update channel. The
template owns `.libops/template-contract.yaml` and may declare
`.libops/component-defaults.revision`; the downstream create operation owns
`.libops/template.lock.yaml`. A source template that already contains the lock is
invalid. See [Updating a downstream fork](/apps#updating-a-downstream-fork) for the
upgrade workflow.

## Remote Prerequisites

For `--type remote`, the standard create runner checks the SSH target before cloning
or starting the stack. The remote host needs `git`, `make`, Docker, the Docker
Compose v2 plugin, and Docker daemon access for the SSH user.

If those tools are missing on a supported mutable host, sitectl asks before installing
or starting them. Pass `--yolo` for unattended QA or automation:

```bash theme={null}
sitectl create wp/default \
  --type remote \
  --checkout-source template \
  --ssh-hostname 203.0.113.10 \
  --ssh-user root \
  --ssh-key ~/.ssh/id_ed25519 \
  --yolo
```

Supported automatic bootstrap paths are Ubuntu/Debian through `apt`, Fedora/RHEL
through `dnf` or `yum`, and Fedora CoreOS through `rpm-ostree`. Fedora CoreOS package
layering requires a reboot, so rerun `sitectl create` after the host comes back.
Google Container-Optimized OS is detected separately: sitectl can start Docker if
that is the only missing item, but it will not try to install host packages on COS.

## Setup-Only and First Start

`--setup-only` creates the local checkout and context without starting the stack. A fresh template checkout may still run clone-time init. For plugin-owned local contexts, the first later `sitectl compose up` checks the plugin's declared init artifacts and images, then runs any remaining init or build commands before starting Compose:

```bash theme={null}
sitectl create ojs/default --path ./ojs --type local --checkout-source template --setup-only
sitectl compose up
```

That handoff uses the plugin create definition as desired lifecycle metadata. Standard application plugins wait up to 10 minutes for Compose services to become running or healthy before reporting the site ready; a timeout is a failed create/start, not a successful background startup. See [Compose reconcile contract](/contributing/compose-reconcile) for contributor details.

## Image and Build Overrides

Compose template create runners can accept image override flags:

```bash theme={null}
sitectl create wp/default --path ./wp --type local --tag wp=nginx-1.30.3-php84
sitectl create ojs/default --path ./ojs --type local --tag ojs=3.5.0-5-php84
sitectl create drupal/default --path ./drupal --type local --build-arg drupal.BASE_IMAGE=libops/drupal:php84
```

These flags write the same local `docker-compose.override.yml` file used by [`sitectl image set`](/commands/image). Use `sitectl image set` later when you need to change image or build-arg overrides for an existing local context.