---
description: How to manage and deploy Directus CMS infrastructure changes.
---

# Directus CMS Infrastructure Workflow

This workflow ensures "Industrial Grade" consistency and stability across local, testing, and production environments for the `at-mintel` Directus CMS.

## 1. Local Development Lifecycle

### Starting the CMS
To start the local Directus instance with extensions:
```bash
cd packages/cms-infra
npm run up
```

### Modifying Schema
1.  **Directus UI**: Make your changes directly in the local Directus Admin UI (Collections, Fields, Relations).
2.  **Take Snapshot**:
    ```bash
    cd packages/cms-infra
    npm run snapshot:local
    ```
    This updates `packages/cms-infra/schema/snapshot.yaml`.
3.  **Commit**: Commit the updated `snapshot.yaml`.

## 2. Deploying Schema Changes

### To Local Environment (Reconciliation)
If you pull changes from Git and need to apply them to your local database:
```bash
cd packages/cms-infra
npm run schema:apply:local
```
> [!IMPORTANT]
> This command automatically runs `scripts/cms-reconcile.sh` to prevent "Field already exists" errors by registering database columns in Directus metadata first.

### To Production (Infra)
To deploy the local snapshot to the production server:
```bash
cd packages/cms-infra
npm run schema:apply:infra
```
This script:
1.  Syncs built extensions via rsync.
2.  Injects the `snapshot.yaml` into the remote container.
3.  Runs `directus schema apply`.
4.  Restarts Directus to clear the schema cache.

## 3. Data Synchronization

### Pulling from Production
To update your local environment with production data and assets:
```bash
cd packages/cms-infra
npm run sync:pull
```

### Pushing to Production
> [!CAUTION]
> This will overwrite production data. Use with extreme care.
```bash
cd packages/cms-infra
npm run sync:push
```

## 4. Extension Management
When modifying extensions in `packages/*-manager`:
1.  Extensions are automatically built and synced when running `npm run up`.
2.  To sync manually without restarting the stack:
    ```bash
    cd packages/cms-infra
    npm run build:extensions
    ```

## 5. Troubleshooting "Field already exists"
If `schema:apply` fails with "Field already exists", run:
```bash
./scripts/cms-reconcile.sh
```
This script ensures the database state matches Directus's internal field registry (`directus_fields`).