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

# Addons

# Addons API Reference

Manage addons that bundle multiple applications and jobs together for coordinated deployment and management. Addons provide a way to deploy complex multi-component systems as a single unit.

## Endpoints Overview

| Method | Endpoint                        | Description            |
| ------ | ------------------------------- | ---------------------- |
| GET    | `/api/addons`                   | List all addons        |
| POST   | `/api/addons/new`               | Create new addon       |
| PUT    | `/api/addons/edit`              | Edit addon             |
| GET    | `/api/addons/{addonName}`       | Get addon details      |
| POST   | `/api/addons/deploy`            | Deploy addon           |
| POST   | `/api/addons/deployments/rerun` | Rerun addon deployment |
| POST   | `/api/addons/uninstall`         | Uninstall addon        |

## Addon Management

### List All Addons

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/addons
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "addons": {
    "monitoring": {
      "name": "monitoring",
      "description": "Monitoring and observability addon",
      "variables": {
        "prometheus_port": {
          "type": "string",
          "value": "{prometheus_port}",
          "default": "9090"
        },
        "grafana_port": {
          "type": "string",
          "value": "{grafana_port}",
          "default": "3000"
        }
      },
      "applications": {
        "prometheus": {
          "type": "monitoring",
          "value": {
            "installation": {
              "setup_type": "docker",
              "docker": {
                "image": "prom/prometheus:latest"
              }
            }
          }
        },
        "grafana": {
          "type": "monitoring",
          "value": {
            "installation": {
              "setup_type": "docker",
              "docker": {
                "image": "grafana/grafana:latest"
              }
            }
          }
        }
      },
      "jobs": {
        "backup": {
          "command": "backup.sh",
          "schedule": "0 0 * * *",
          "environment": {
            "BACKUP_DIR": "/backups"
          }
        }
      }
    }
  }
}
```

### Create Addon

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/addons/new
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "name": "monitoring",
  "description": "Monitoring and observability addon",
  "variables": {
    "prometheus_port": {
      "type": "string",
      "value": "{prometheus_port}",
      "default": "9090"
    }
  },
  "applications": {
    "prometheus": {
      "type": "monitoring",
      "value": {
        "installation": {
          "setup_type": "docker",
          "docker": {
            "image": "prom/prometheus:latest"
          }
        }
      }
    }
  }
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "message": "Addon created successfully"
}
```

### Get Addon Details

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/addons/{addonName}
```

**Parameters:**

* `addonName` (path): Name of the addon

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "addon": {
    "name": "monitoring",
    "description": "Monitoring and observability addon",
    "variables": {
      "prometheus_port": {
        "type": "string",
        "value": "{prometheus_port}",
        "default": "9090"
      }
    },
    "applications": {
      "prometheus": {
        "type": "monitoring",
        "value": {
          "installation": {
            "setup_type": "docker",
            "docker": {
              "image": "prom/prometheus:latest"
            }
          }
        }
      }
    }
  }
}
```

## Deployment Management

### Deploy Addon

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/addons/deploy
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "addonName": "monitoring",
  "nodeName": "production-monitoring",
  "deploymentMode": "docker",
  "variables": {
    "prometheus_port": "9090",
    "grafana_port": "3000"
  },
  "deploymentId": "addon-deploy-20240115-103000"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "deploymentId": "addon-deploy-20240115-103000",
  "message": "Addon deployment started"
}
```

### Rerun Addon Deployment

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/addons/deployments/rerun
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "deploymentId": "addon-deploy-20240115-103000",
  "newDeploymentId": "addon-deploy-20240116-140000",
  "addonName": "monitoring",
  "nodeName": "production-monitoring"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "message": "Addon deployment rerun started",
  "deploymentId": "addon-deploy-20240116-140000",
  "node": "production-monitoring",
  "playbookPath": "/playbooks/monitoring/deploy.yml",
  "originalDeploymentId": "addon-deploy-20240115-103000"
}
```

### Uninstall Addon

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/addons/uninstall
```

**Request Body (JSON):**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "addonName": "monitoring",
  "nodeName": "production-monitoring"
}
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "message": "Addon uninstalled successfully"
}
```

## Advanced Addon Features

### Job Management

Addons can include scheduled jobs that run on the target node:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "jobs": {
    "backup": {
      "command": "backup.sh",
      "schedule": "0 0 * * *",
      "environment": {
        "BACKUP_DIR": "/backups"
      },
      "retry_policy": {
        "retries": 3,
        "retry_interval": "5m"
      },
      "notifications": {
        "message": "Job {job_name} completed",
        "on_success": true,
        "on_failure": true
      }
    }
  }
}
```

### Component Dependencies

Addons can define dependencies between components:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "components": [
    {
      "name": "database",
      "type": "postgresql",
      "ports": ["5432"],
      "dependencies": []
    },
    {
      "name": "api",
      "type": "nodejs",
      "ports": ["3000"],
      "dependencies": ["database"]
    }
  ]
}
```

## Error Responses

Common error responses for Addons API:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": false,
  "error": "Addon not found",
  "details": {
    "addonName": "non-existent-addon"
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": false,
  "error": "Addon deployment failed",
  "details": {
    "addonName": "monitoring",
    "nodeName": "production-monitoring",
    "component": "prometheus",
    "output": "Docker image pull failed"
  }
}
```

## Best Practices

### Addon Design

* Keep addons focused on specific functionality
* Use clear naming conventions
* Document component dependencies
* Test addon deployments thoroughly

### Variable Management

* Use descriptive variable names
* Provide sensible defaults
* Validate variable values
* Document variable usage

### Deployment Strategy

* Test addon deployments in isolation
* Monitor component dependencies
* Implement proper rollback procedures
* Set up comprehensive monitoring

### Job Management

* Use appropriate scheduling for jobs
* Implement proper error handling
* Monitor job execution and results
* Set up notifications for critical jobs

For detailed schema definitions, refer to the OpenAPI specification published alongside the backend service.