> ## Documentation Index
> Fetch the complete documentation index at: https://libops-renovate-github-com-libops-sitectl-isle-0-x.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# compose

> Run Docker Compose commands through the active sitectl context.

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>;

# <Compose /> command

The `compose` command is a core `sitectl` command that runs <Compose /> commands against the active `sitectl` context.

Use it when you want the same <Compose /> operation to respect the site and environment wiring already stored in the context.

For local development contexts, `sitectl compose up` checks whether the default HTTP or HTTPS host port is already in use. If another process owns a needed port, sitectl writes `docker-compose.override.yml` with a Compose `ports: !override` entry for the next available development port before invoking Docker Compose.

HTTP-only stacks publish target port `80` and use `URI_SCHEME=http`. Stacks that publish target port `443`, or whose Traefik command declares an HTTPS entrypoint on `:443`, use `URI_SCHEME=https`. This behavior only applies to local dev contexts, not local production workloads.

See [Managed applications](/apps) for the application template Compose contract.

## Reconcile

For local plugin-owned contexts, `sitectl compose up` can perform a reconcile before handing off to Docker Compose. It reads the plugin's default create definition, checks init artifacts, declared volumes, and local image metadata, then runs the plugin's init and build commands when they are still needed.

This lets a setup-only checkout start cleanly:

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

You can also run the same workflow explicitly:

```bash theme={null}
sitectl compose reconcile
sitectl compose reconcile --force
sitectl compose reconcile --reset-init
```

The reconcile cache is local to the workstation and expires after 7 days. `--force` ignores the cache and reruns build/up. `--reset-init` removes plugin-declared init artifacts and init volumes, clears the cache entry, then reconciles again.

The reconcile step is a synchronous CLI workflow for one local <Compose /> project. It borrows condition names such as `Initialized` and `ImagesAvailable`, but it is not a Kubernetes controller or background loop.

## Clean

Use `sitectl compose clean` when you need to throw away local runtime state and return to a fresh init/build flow:

```bash theme={null}
sitectl compose clean
sitectl compose clean --yes
```

`clean` runs `docker compose down -v`, removes plugin-declared init artifacts such as generated secrets, certs, UID markers, and env files, and clears the reconcile cache entry. It is destructive and prompts for a typed confirmation unless `--yes` is passed.

See [Compose reconcile contract](/contributing/compose-reconcile) for the contributor-facing contract.

## Reference

Run docker compose commands on sitectl contexts.

This command wraps docker compose and automatically applies compose files, env files, and project directory
based on the current context. All docker compose commands and flags are supported.

Automatic behaviors:

* `compose up` automatically adds `-d `--remove-orphans\`\` if not already specified
* Compose file paths (-f flags) are injected from context.ComposeFile setting
* Env file paths (`--env-file` flags) are injected from context.EnvFile setting
* Working directory is set to context.ProjectDir

Examples:
sitectl compose up                    # Start containers in detached mode
sitectl compose down                  # Stop and remove containers
sitectl compose logs -f drupal        # Follow drupal container logs
sitectl compose ps                    # List running containers
sitectl compose exec -it drupal bash      # Open shell in drupal container
sitectl compose `--context` prod up     # Start containers on prod context

```bash theme={null}
sitectl compose COMMAND
```

Run plugin Docker Compose init/build/up reconciliation.

This is the same lifecycle repair path sitectl runs automatically before
`sitectl compose up` for plugin-managed local Compose projects. Use `--force` to
rerun build/up even when the project is cached as current. Use `--reset-init` to
remove plugin-declared init artifacts and init volumes before reconciling.

```bash theme={null}
sitectl compose reconcile
```

| Flag           | Default | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `--force`      | `false` | Ignore the reconcile cache and rerun build/up.                             |
| `--reset-init` | `false` | Remove plugin-declared init artifacts and init volumes before reconciling. |

Destroy local Compose containers, volumes, and plugin init state.

This command runs `docker compose down -v`, removes init artifacts declared by
the active plugin, and clears the local compose reconcile cache entry. It is
destructive: database volumes, uploaded files stored in named volumes, generated
secrets, certificates, and env files declared by the plugin can be lost.

```bash theme={null}
sitectl compose clean
```

| Flag    | Default | Description                               |
| ------- | ------- | ----------------------------------------- |
| `--yes` | `false` | Skip the destructive confirmation prompt. |