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

# Resource Deployments

> Deploy Kodexa resources such as taxonomies, modules, stores, and data forms using GitOps workflows with validation and multi-environment promotion.

Deploy Kodexa resources (taxonomies, modules, stores, data forms) using modern GitOps workflows with automatic validation, version control, and multi-environment promotion.

## Overview

Resource deployment enables you to manage your Kodexa project configurations as code, with all the benefits of Git-based workflows:

* 📝 **Version Control** - Track all changes in Git
* 👥 **Team Collaboration** - Review changes through pull requests
* 🔄 **Rollback** - Easily revert to previous configurations
* 🌍 **Multi-Environment** - Promote changes across dev/staging/production
* ✅ **Automated Testing** - Validate before deployment

<img src="https://mintcdn.com/kodexa/38NSCexrnuSlewkk/images/resource-deployment.png?fit=max&auto=format&n=38NSCexrnuSlewkk&q=85&s=ecc64daf7228c8a0f7a52702e1e2a7e3" alt="Resource Deployment" width="3002" height="760" data-path="images/resource-deployment.png" />

## Resource Types

Kodexa supports two scopes of resources:

### Organization-Level Resources

Shared across multiple projects:

| Resource              | Description                      | Example Use Case                  |
| --------------------- | -------------------------------- | --------------------------------- |
| **Taxonomies**        | Classification hierarchies       | Document types, entity categories |
| **Stores**            | Storage configurations           | Document stores, vector databases |
| **Knowledge Types**   | Rule templates                   | Conditional logic definitions     |
| **Feature Types**     | Generic capabilities             | Text extraction, OCR              |
| **Feature Instances** | Environment-specific deployments | Production OCR, Dev OCR           |
| **Modules**           | ML modules                       | Document classifiers, extractors  |
| **Project Templates** | Reusable project structures      | Invoice processing template       |
| **Data Forms**        | UI configurations                | Invoice data form                 |

### Project-Level Resources

Project-specific configurations:

| Resource            | Description            | Example Use Case             |
| ------------------- | ---------------------- | ---------------------------- |
| **Projects**        | Project metadata       | Invoice automation project   |
| **Knowledge Items** | Project-specific rules | US tax calculation rules     |
| **Assistants**      | AI assistant configs   | Invoice processing assistant |

## Quick Start

### 1. Configure Environment

Set up authentication using environment variables:

```bash theme={null}
# Install kdx CLI
brew install kodexa-ai/tap/kdx

# Set environment variables for production
export KODEXA_URL=https://platform.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=your-api-key
```

<Tip>
  Get your API token from your Kodexa profile settings at `https://platform.kodexa-enterprise.com/profile`
</Tip>

### 2. Pull Existing Resources

Use the `kdx` CLI to download your existing configuration:

```bash theme={null}
# Pull from production environment
kdx sync pull --target prod --env production
```

This creates a `kodexa-metadata/` directory with your resources:

```text theme={null}
kodexa-metadata/
├── sync-config.yaml
├── manifests/
│   └── production.yaml
└── my-org/
    ├── organization.yaml
    ├── taxonomies/
    │   └── document-classification.yaml
    ├── stores/
    │   └── document-store.yaml
    ├── feature-types/
    │   └── text-extraction.yaml
    └── modules/
        └── doc-classifier-v3.yaml
```

### 3. Review Configuration

The sync creates a v2 configuration structure:

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Define deployment targets
targets:
  prod:
    url: https://platform.kodexa-enterprise.com
    description: Production environment

# Define environments
environments:
  production:
    description: Production deployment

# Branch-based deployment
branch_mappings:
  - branch: main
    target: prod
    environment: production

# Resource manifests
manifests:
  - manifests/production.yaml
```

```yaml theme={null}
# kodexa-metadata/manifests/production.yaml
organizations:
  - slug: my-organization
    resources:
      - type: taxonomy
        slug: document-classification
      - type: store
        slug: document-store
      - type: featureType
        slug: text-extraction
      - type: module
        slug: doc-classifier-v3
```

### 4. Create Git Repository

```bash theme={null}
# Initialize repository
git init
git add .
git commit -m "Initial Kodexa configuration"

# Push to GitHub
git remote add origin git@github.com:your-org/kodexa-config.git
git push -u origin main
```

### 5. Set Up GitHub Actions

Create `.github/workflows/deploy.yml`:

```yaml theme={null}
name: Deploy to Kodexa

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Kodexa
        uses: kodexa-ai/kdx-sync-action@v1
        with:
          kodexa-url: ${{ secrets.KODEXA_URL }}
          kodexa-token: ${{ secrets.KODEXA_TOKEN }}
```

### 6. Configure Secrets

In GitHub repository settings, add:

* `KODEXA_URL` - Your Kodexa platform URL
* `KODEXA_TOKEN` - Your API token

## Working with Resources

### Adding a New Taxonomy

<Steps>
  <Step title="Create YAML file">
    ```yaml theme={null}
    # kodexa-metadata/my-org/taxonomies/invoice-fields.yaml
    slug: invoice-fields
    name: Invoice Field Classification
    description: Classify invoice document fields
    version: "1.0.0"
    taxons:
      - slug: vendor-info
        name: Vendor Information
        children:
          - slug: vendor-name
            name: Vendor Name
          - slug: vendor-address
            name: Vendor Address
      - slug: line-items
        name: Line Items
        children:
          - slug: description
            name: Description
          - slug: quantity
            name: Quantity
          - slug: unit-price
            name: Unit Price
    ```
  </Step>

  <Step title="Add to manifest">
    ```yaml theme={null}
    # kodexa-metadata/manifests/production.yaml
    organizations:
      - slug: my-organization
        resources:
          - type: taxonomy
            slug: invoice-fields  # Add this
    ```
  </Step>

  <Step title="Test Locally">
    ```bash theme={null}
    # Validate configuration
    kdx sync deploy --target prod --env production --dry-run
    ```
  </Step>

  <Step title="Commit and Push">
    ```bash theme={null}
    git add kodexa-metadata/
    git commit -m "feat: add invoice field classification taxonomy"
    git push
    ```
  </Step>

  <Step title="GitHub Actions Deploys">
    GitHub Actions automatically:

    * Validates the configuration
    * Syncs to Kodexa
    * Reports results
  </Step>
</Steps>

### Adding a Document Store

```yaml theme={null}
# kodexa-metadata/my-org/stores/invoice-documents.yaml
slug: invoice-documents
name: Invoice Document Store
description: Central repository for invoice documents
type: document
configuration:
  storage_backend: s3
  retention_days: 365
  enable_versioning: true
```

Add to manifest:

```yaml theme={null}
# kodexa-metadata/manifests/production.yaml
organizations:
  - slug: my-organization
    resources:
      - type: store
        slug: invoice-documents
```

### Adding a Feature Type

```yaml theme={null}
# kodexa-metadata/my-org/feature-types/ocr-extraction.yaml
slug: ocr-extraction
name: OCR Text Extraction
description: Extract text from scanned documents using OCR
version: "2.0.0"
capabilities:
  - text_extraction
  - layout_analysis
parameters:
  - name: language
    type: string
    default: "eng"
  - name: dpi
    type: integer
    default: 300
```

### Adding a Feature Instance

```yaml theme={null}
# kodexa-metadata/my-org/feature-instances/ocr-prod.yaml
slug: ocr-prod
name: OCR Extraction - Production
feature_type_slug: ocr-extraction
configuration:
  language: "eng"
  dpi: 600
  enable_gpu: true
resources:
  memory: "4Gi"
  cpu: "2"
environments:
  production: true
  staging: false
  development: false
```

## Sync Configuration

The `sync-config.yaml` defines deployment targets, environments, and resource manifests using the v2 format:

### Basic Configuration

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Deployment targets
targets:
  prod:
    url: https://platform.kodexa-enterprise.com
    description: Production Kodexa instance

# Environments
environments:
  production:
    description: Production deployment

# Resource manifests
manifests:
  - manifests/production.yaml
```

### Multi-Environment Configuration

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

# Define multiple targets
targets:
  dev:
    url: https://dev.kodexa-enterprise.com
    description: Development environment
  staging:
    url: https://staging.kodexa-enterprise.com
    description: Staging environment
  prod:
    url: https://platform.kodexa-enterprise.com
    description: Production environment

# Define environments
environments:
  development:
    description: Development deployment
  staging:
    description: Staging deployment
  production:
    description: Production deployment

# Branch-based deployment
branch_mappings:
  - branch: main
    target: prod
    environment: production
  - branch: staging
    target: staging
    environment: staging
  - branch: develop
    target: dev
    environment: development

# Different manifests per environment
manifests:
  - manifests/development.yaml
  - manifests/staging.yaml
  - manifests/production.yaml
```

### Manifest Composition

Organize resources across multiple manifest files:

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
manifests:
  - manifests/shared-taxonomies.yaml
  - manifests/shared-stores.yaml
  - manifests/production-features.yaml
  - manifests/production-modules.yaml
```

```yaml theme={null}
# kodexa-metadata/manifests/shared-taxonomies.yaml
organizations:
  - slug: my-organization
    resources:
      - type: taxonomy
        slug: document-classification
      - type: taxonomy
        slug: invoice-fields
```

```yaml theme={null}
# kodexa-metadata/manifests/production-features.yaml
organizations:
  - slug: my-organization
    resources:
      - type: featureType
        slug: ocr-extraction
      - type: featureInstance
        slug: ocr-prod
```

## Multi-Environment Deployment

Deploy the same configuration to multiple environments using branch mappings:

### Branch-Based Strategy

Configure automatic deployment based on Git branches:

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
version: 2
metadata_dir: kodexa-metadata

targets:
  dev:
    url: https://dev.kodexa-enterprise.com
  staging:
    url: https://staging.kodexa-enterprise.com
  prod:
    url: https://platform.kodexa-enterprise.com

environments:
  development:
    description: Dev environment
  staging:
    description: Staging environment
  production:
    description: Production environment

branch_mappings:
  - branch: develop
    target: dev
    environment: development
  - branch: staging
    target: staging
    environment: staging
  - branch: main
    target: prod
    environment: production
```

**Workflow:**

```text theme={null}
develop branch → dev.kodexa-enterprise.com (development)
staging branch → staging.kodexa-enterprise.com (staging)
main branch    → platform.kodexa-enterprise.com (production)
```

### GitHub Actions for Multi-Environment

```yaml theme={null}
# .github/workflows/multi-environment.yml
name: Multi-Environment Deploy

on:
  push:
    branches:
      - main
      - staging
      - develop

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set environment variables
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "KODEXA_TARGET=prod" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=production" >> $GITHUB_ENV
          elif [[ "${{ github.ref }}" == "refs/heads/staging" ]]; then
            echo "KODEXA_TARGET=staging" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=staging" >> $GITHUB_ENV
          else
            echo "KODEXA_TARGET=dev" >> $GITHUB_ENV
            echo "KODEXA_ENVIRONMENT=development" >> $GITHUB_ENV
          fi

      - name: Deploy to ${{ env.KODEXA_ENVIRONMENT }}
        run: |
          export KODEXA_URL=${{ secrets[format('KODEXA_{0}_URL', env.KODEXA_TARGET)] }}
          export KODEXA_ACCESS_TOKEN=${{ secrets[format('KODEXA_{0}_TOKEN', env.KODEXA_TARGET)] }}
          kdx sync deploy --target ${{ env.KODEXA_TARGET }} --env ${{ env.KODEXA_ENVIRONMENT }}
```

### Manual Environment Deployment

Deploy to specific environments locally:

```bash theme={null}
# Deploy to development
export KODEXA_URL=https://dev.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=dev-token
kdx sync deploy --target dev --env development

# Deploy to staging
export KODEXA_URL=https://staging.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=staging-token
kdx sync deploy --target staging --env staging

# Deploy to production
export KODEXA_URL=https://platform.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=prod-token
kdx sync deploy --target prod --env production
```

## Pull Request Workflow

Validate changes before deployment:

```yaml theme={null}
# .github/workflows/pr-validation.yml
name: Validate Resources

on:
  pull_request:
    paths:
      - 'kodexa-metadata/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate configuration
        run: |
          export KODEXA_URL=${{ secrets.KODEXA_DEV_URL }}
          export KODEXA_ACCESS_TOKEN=${{ secrets.KODEXA_DEV_TOKEN }}
          kdx sync deploy --target dev --env development --dry-run

      - name: Comment results
        uses: actions/github-script@v7
        with:
          script: |
            const message = `### ✅ Resource Validation

            Your changes are valid and ready to deploy.

            Resources validated against development environment.`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: message
            });
```

## Common Workflows

### Add New Resource

```bash theme={null}
# 1. Create feature branch
git checkout -b feature/add-vendor-taxonomy

# 2. Add resource file
cat > kodexa-metadata/my-org/taxonomies/vendor-types.yaml << EOF
slug: vendor-types
name: Vendor Type Classification
version: "1.0.0"
taxons:
  - slug: corporate
    name: Corporate Vendor
  - slug: individual
    name: Individual Vendor
EOF

# 3. Add to manifest
# Edit kodexa-metadata/manifests/production.yaml to include:
# - type: taxonomy
#   slug: vendor-types

# 4. Validate locally
export KODEXA_URL=https://platform.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=your-token
kdx sync deploy --target prod --env production --dry-run

# 5. Commit and push
git add .
git commit -m "feat: add vendor type taxonomy"
git push origin feature/add-vendor-taxonomy

# 6. Open pull request on GitHub
# 7. GitHub Actions validates automatically
# 8. After approval, merge deploys to production
```

### Update Existing Resource

```bash theme={null}
# 1. Pull latest changes
git checkout main
git pull

# 2. Create branch
git checkout -b fix/update-invoice-form

# 3. Modify resource
vim kodexa-metadata/my-org/data-forms/invoice-form.yaml

# 4. Test locally
kdx sync deploy --target prod --env production --dry-run

# 5. Commit and deploy
git add .
git commit -m "fix: update invoice form field validation"
git push origin fix/update-invoice-form
```

### Promote from Dev to Production

```bash theme={null}
# 1. Test in development
git checkout develop
git pull
# Make changes, test

# 2. Merge to staging
git checkout staging
git merge develop
git push
# Automatic deployment to staging

# 3. After validation, merge to main
git checkout main
git merge staging
git push
# Automatic deployment to production
```

### Rollback Changes

```bash theme={null}
# Find the commit to rollback to
git log --oneline

# Create rollback branch from previous commit
git checkout -b rollback/revert-taxonomy-change abc1234

# Push and merge
git push origin rollback/revert-taxonomy-change
# Create PR and merge
```

## Troubleshooting

### Resource Not Found

**Error:** `Resource 'my-taxonomy' not found in target environment`

**Cause:** Resource doesn't exist in target environment or not in manifest

**Fix:**

```bash theme={null}
# Check manifest includes the resource
cat kodexa-metadata/manifests/production.yaml

# Add to manifest if missing
# Then deploy
kdx sync deploy --target prod --env production
```

### Environment Variable Issues

**Error:** `KODEXA_URL not set`

**Cause:** Required environment variables not configured

**Fix:**

```bash theme={null}
# Set required variables
export KODEXA_URL=https://platform.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=your-api-key

# Or use .env file
cat > .env << EOF
KODEXA_URL=https://platform.kodexa-enterprise.com
KODEXA_ACCESS_TOKEN=your-api-key
EOF

source .env
```

### Validation Errors

**Error:** `Feature instance references unknown feature type`

**Cause:** Feature instance references a feature type that doesn't exist

**Fix:**

```bash theme={null}
# Add the missing feature type first
cat > kodexa-metadata/my-org/feature-types/missing-type.yaml << EOF
slug: missing-type
name: Missing Feature Type
version: "1.0.0"
EOF

# Add to manifest
# Edit kodexa-metadata/manifests/production.yaml

# Deploy both together
kdx sync deploy --target prod --env production
```

### Target or Environment Not Found

**Error:** `Target 'prod' not found in sync-config.yaml`

**Cause:** Target or environment not defined in configuration

**Fix:**

```yaml theme={null}
# Add to sync-config.yaml
targets:
  prod:
    url: https://platform.kodexa-enterprise.com
    description: Production environment

environments:
  production:
    description: Production deployment
```

### Conflicting Changes

**Error:** Merge conflict in YAML files

**Fix:**

```bash theme={null}
# Pull latest from target environment
kdx sync pull --target prod --env production

# Resolve conflicts manually
vim kodexa-metadata/my-org/taxonomies/conflicted-file.yaml

# Test resolution
kdx sync deploy --target prod --env production --dry-run

# Commit resolution
git add .
git commit -m "fix: resolve merge conflict"
```

## Best Practices

### 1. Use Semantic Versioning

```yaml theme={null}
slug: invoice-classifier
version: "2.1.0"  # Major.Minor.Patch
```

### 2. Document Dependencies

```yaml theme={null}
# invoice-automation-project.yaml
slug: invoice-automation
# Dependencies:
#   - taxonomy: invoice-fields v1.0.0
#   - store: invoice-documents v1.0.0
#   - module: invoice-classifier v2.1.0
```

### 3. Test in Lower Environments First

```bash theme={null}
# Test in dev
export KODEXA_URL=https://dev.kodexa-enterprise.com
export KODEXA_ACCESS_TOKEN=dev-token
kdx sync deploy --target dev --env development

# Promote to staging
git checkout staging
git merge develop
git push

# Finally production
git checkout main
git merge staging
git push
```

### 4. Use Meaningful Commit Messages

```bash theme={null}
git commit -m "feat: add OCR feature instance for production

- Configured with high-accuracy model
- Enabled GPU acceleration
- Set memory limit to 4GB"
```

### 5. Keep Resources Modular

Break large configurations into smaller, focused files and manifests:

```text theme={null}
kodexa-metadata/
├── manifests/
│   ├── shared-taxonomies.yaml
│   ├── shared-stores.yaml
│   ├── production-features.yaml
│   └── production-models.yaml
└── my-org/
    ├── taxonomies/
    │   ├── invoice-fields.yaml
    │   ├── vendor-types.yaml
    │   └── payment-methods.yaml
    └── feature-types/
        ├── ocr-extraction.yaml
        └── text-extraction.yaml
```

### 6. Use Environment-Specific Manifests

```yaml theme={null}
# kodexa-metadata/sync-config.yaml
branch_mappings:
  - branch: develop
    target: dev
    environment: development
  - branch: main
    target: prod
    environment: production

manifests:
  - manifests/shared.yaml           # Both environments
  - manifests/dev-only.yaml         # Dev-specific
  - manifests/production-only.yaml  # Prod-specific
```

## Next Steps

<CardGroup cols={2}>
  <Card title="GitOps with GitHub Actions" icon="github" href="/guides/deployment/gitops-github-actions">
    Complete GitHub Actions deployment guide
  </Card>

  <Card title="CLI Metadata Sync" icon="terminal" href="/guides/kdx-cli/sync/overview">
    Local development with kdx CLI
  </Card>

  <Card title="Resource Operations" icon="box" href="/guides/kdx-cli/resource-operations">
    CRUD operations for resources
  </Card>

  <Card title="KDX CLI Overview" icon="command-line" href="/guides/kdx-cli/overview">
    Learn about the kdx CLI
  </Card>
</CardGroup>