> ## 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.

# Drupal plugin

> Drupal-oriented sitectl workflows including Composer, Drush, Solr configuration, login links, and database and config sync.

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 Drupal plugin adds Drupal-specific commands on top of the core sitectl context and <Compose /> model. Install it when your site runs Drupal, whether standalone or as part of a larger stack like ISLE (Islandora).

## Commands

### drush

Run any Drush command inside the Drupal container for the active context:

```bash theme={null}
sitectl drupal drush cr
sitectl drupal drush cron --context museum-prod
sitectl drupal drush updb -y
```

sitectl resolves the correct container from the context and executes the command inside it. You don't need to know the container name or remember which context you're connected to.

### composer

Run Composer from the configured Drupal root inside the running Drupal container:

```bash theme={null}
sitectl drupal composer install
sitectl drupal composer update -W
sitectl drupal composer require 'drupal/islandora:^2.11'
```

The command passes arguments directly to Composer. For authoring commands such as
`require`, `remove`, and `update`, first enable [dev mode](/plugins/drupal/dev) or
provide equivalent bind mounts so `composer.json` and `composer.lock` are persisted
to the host checkout.
Changes made only inside an image-backed production container disappear when that
container is rebuilt or replaced. Review and commit both manifests after every
dependency change.

### solr-config refresh

Generate Drupal Search API Solr configuration and reconcile the tracked and runtime
copies:

```bash theme={null}
sitectl drupal solr-config refresh
sitectl drupal solr-config refresh --reindex
```

Use this after updating Solr or `drupal/search_api_solr`, or when Drupal reports that
the Solr server configuration is out of date. When generated, tracked, and runtime
configuration already match, refresh is a successful no-op. `--reindex` reindexes
only when the runtime configuration changed, so it is also safe to repeat.

The command detects the running Solr version, atomically replaces only a drifted
core's `conf`, preserves its data directory, and reloads the core (or creates it when
missing). Use `--server`, `--core`, `--solr-version`, or `--output` only when the
site differs from the context defaults.

Generate and commit any tracked configuration diff in development before
promotion. Refresh without `--reindex` does not repopulate the index. If an index
needs rebuilding while runtime configuration is already current, reindex explicitly
through the Search API administration page or the site's established Drush workflow.
See [Solr service commands](/plugins/solr) for override flags and the full reindex
caveat, or open the dedicated [solr-config command guide](/plugins/drupal/solr-config).

### login

Generate a one-time Drupal login link via `drush user:login`:

```bash theme={null}
sitectl drupal login
sitectl drupal login --uid 5
```

The default user ID is 1. Pass `--uid` to generate a link for a different user.

### sync database

Copy the Drupal database from one context to another:

```bash theme={null}
sitectl drupal sync database --source museum-prod --target museum-local
```

sitectl backs up the source database, stages it between contexts, imports it into the target, and runs post-import steps. Before importing it confirms the operation with you. Pass `--yolo` to skip the confirmation in automation.

Use `--fresh` to always take a new backup from the source instead of reusing a backup from earlier today.

<Warning>
  Syncing a database replaces the target database. Make sure you have a backup of the target before running this on staging or production.
</Warning>

### sync config

Copy the Drupal config/sync directory from one context to another:

```bash theme={null}
sitectl drupal sync config --source museum-prod --target museum-local
```

This exports the config export from the source, stages it, and imports it into the target via `drush config:import`.

### dev mode

Use the core component workflow to enable local Drupal development mounts:

```bash theme={null}
sitectl set dev-mode enabled
```

Dev mode bind-mounts the Composer manifests and local source paths into the Drupal
container. This lets `sitectl drupal composer` persist dependency edits into the
host checkout. Use ordinary git workflows for extension branches, patches, and
upstream source changes.

## Update workflow

The downstream checkout owns Drupal through its Composer manifests and lockfile.
Use this sequence for Drupal and contributed-module updates:

1. On an update branch in a development context, run `sitectl bump` or author a
   targeted change with `sitectl drupal composer`. Review and commit
   `composer.json`, `composer.lock`, and any generated Solr or config-sync changes.
2. Read the dependency release notes, test the rebuilt development image, and take
   tested backups of MariaDB and the public/private files before production rollout.
3. Run `sitectl deploy`. It pulls dependency images and rebuilds Drupal while the
   current stack is online, then performs the ordered down/up rollout. During the
   gate it starts Drupal and its dependencies, waits for installation, and runs
   `drush updb -y` followed by `drush cr`. Either failure stops the deploy before
   the full-stack start.
4. If the reviewed branch changed config-sync files, import them explicitly with
   `sitectl drupal drush cim -y`. Deploy does not import Drupal configuration.
5. If Solr or Search API Solr changed, run
   `sitectl drupal solr-config refresh --reindex`. If the MariaDB image changed,
   run `sitectl mariadb upgrade`.
6. Run `sitectl healthcheck`, application smoke tests, and any module-specific
   verification before discarding the backup.

Database updates, configuration imports, and content reindexing are separate gates.
A successful `updb` and cache rebuild do not prove that a pending config import or
Solr reindex has completed.

## Assigning the Drupal plugin to a context

When you create or configure a context, set its `plugin` field to `drupal`:

```yaml theme={null}
plugin: drupal
```

sitectl uses this to validate that Drupal commands are only run against Drupal contexts, and to route the `sitectl debug` command to the Drupal plugin for Drupal-specific diagnostics.