re-uploading work
This commit is contained in:
305
packs/core/SETUP.md
Normal file
305
packs/core/SETUP.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Core Pack Setup Guide
|
||||
|
||||
This guide explains how to set up and load the Attune core pack into your database.
|
||||
|
||||
## Overview
|
||||
|
||||
The **core pack** is Attune's built-in system pack that provides essential automation components including:
|
||||
|
||||
- **Timer Triggers**: Interval-based, cron-based, and datetime triggers
|
||||
- **Basic Actions**: Echo, sleep, noop, and HTTP request actions
|
||||
- **Built-in Sensors**: Interval timer sensor for time-based automation
|
||||
|
||||
The core pack must be loaded into the database before it can be used in rules and workflows.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before loading the core pack, ensure:
|
||||
|
||||
1. **PostgreSQL is running** and accessible
|
||||
2. **Database migrations are applied**: `sqlx migrate run`
|
||||
3. **Python 3.8+** is installed (for the loader script)
|
||||
4. **Required Python packages** are installed:
|
||||
```bash
|
||||
pip install psycopg2-binary pyyaml
|
||||
```
|
||||
|
||||
## Loading Methods
|
||||
|
||||
### Method 1: Python Loader Script (Recommended)
|
||||
|
||||
The Python loader script reads the pack YAML files and creates database entries automatically.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# From the project root
|
||||
python3 scripts/load_core_pack.py
|
||||
|
||||
# With custom database URL
|
||||
python3 scripts/load_core_pack.py --database-url "postgresql://user:pass@localhost:5432/attune"
|
||||
|
||||
# With custom pack directory
|
||||
python3 scripts/load_core_pack.py --pack-dir ./packs
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Reads `pack.yaml` for pack metadata
|
||||
- Loads all trigger definitions from `triggers/*.yaml`
|
||||
- Loads all action definitions from `actions/*.yaml`
|
||||
- Loads all sensor definitions from `sensors/*.yaml`
|
||||
- Creates or updates database entries (idempotent)
|
||||
- Uses transactions (all-or-nothing)
|
||||
|
||||
**Output:**
|
||||
```
|
||||
============================================================
|
||||
Core Pack Loader
|
||||
============================================================
|
||||
|
||||
→ Loading pack metadata...
|
||||
✓ Pack 'core' loaded (ID: 1)
|
||||
|
||||
→ Loading triggers...
|
||||
✓ Trigger 'core.intervaltimer' (ID: 1)
|
||||
✓ Trigger 'core.crontimer' (ID: 2)
|
||||
✓ Trigger 'core.datetimetimer' (ID: 3)
|
||||
|
||||
→ Loading actions...
|
||||
✓ Action 'core.echo' (ID: 1)
|
||||
✓ Action 'core.sleep' (ID: 2)
|
||||
✓ Action 'core.noop' (ID: 3)
|
||||
✓ Action 'core.http_request' (ID: 4)
|
||||
|
||||
→ Loading sensors...
|
||||
✓ Sensor 'core.interval_timer_sensor' (ID: 1)
|
||||
|
||||
============================================================
|
||||
✓ Core pack loaded successfully!
|
||||
============================================================
|
||||
Pack ID: 1
|
||||
Triggers: 3
|
||||
Actions: 4
|
||||
Sensors: 1
|
||||
```
|
||||
|
||||
### Method 2: SQL Seed Script
|
||||
|
||||
For simpler setups or CI/CD, you can use the SQL seed script directly.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
psql $DATABASE_URL -f scripts/seed_core_pack.sql
|
||||
```
|
||||
|
||||
**Note:** The SQL script may not include all pack metadata and is less flexible than the Python loader.
|
||||
|
||||
### Method 3: CLI (Future)
|
||||
|
||||
Once the CLI pack management commands are fully implemented:
|
||||
|
||||
```bash
|
||||
attune pack register ./packs/core
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After loading, verify the core pack is available:
|
||||
|
||||
### Using CLI
|
||||
```bash
|
||||
# List all packs
|
||||
attune pack list
|
||||
|
||||
# Show core pack details
|
||||
attune pack show core
|
||||
|
||||
# List core pack actions
|
||||
attune action list --pack core
|
||||
|
||||
# List core pack triggers
|
||||
attune trigger list --pack core
|
||||
```
|
||||
|
||||
### Using API
|
||||
```bash
|
||||
# Get pack info
|
||||
curl http://localhost:8080/api/v1/packs/core | jq
|
||||
|
||||
# List actions
|
||||
curl http://localhost:8080/api/v1/packs/core/actions | jq
|
||||
|
||||
# List triggers
|
||||
curl http://localhost:8080/api/v1/packs/core/triggers | jq
|
||||
```
|
||||
|
||||
### Using Database
|
||||
```sql
|
||||
-- Check pack exists
|
||||
SELECT * FROM attune.pack WHERE ref = 'core';
|
||||
|
||||
-- Count components
|
||||
SELECT
|
||||
(SELECT COUNT(*) FROM attune.trigger WHERE pack_ref = 'core') as triggers,
|
||||
(SELECT COUNT(*) FROM attune.action WHERE pack_ref = 'core') as actions,
|
||||
(SELECT COUNT(*) FROM attune.sensor WHERE pack_ref = 'core') as sensors;
|
||||
```
|
||||
|
||||
## Testing the Core Pack
|
||||
|
||||
### 1. Test Actions Directly
|
||||
|
||||
Test actions using environment variables:
|
||||
|
||||
```bash
|
||||
# Test echo action
|
||||
export ATTUNE_ACTION_MESSAGE="Hello, Attune!"
|
||||
export ATTUNE_ACTION_UPPERCASE=false
|
||||
./packs/core/actions/echo.sh
|
||||
|
||||
# Test sleep action
|
||||
export ATTUNE_ACTION_SECONDS=2
|
||||
export ATTUNE_ACTION_MESSAGE="Sleeping..."
|
||||
./packs/core/actions/sleep.sh
|
||||
|
||||
# Test HTTP request action
|
||||
export ATTUNE_ACTION_URL="https://httpbin.org/get"
|
||||
export ATTUNE_ACTION_METHOD="GET"
|
||||
python3 packs/core/actions/http_request.py
|
||||
```
|
||||
|
||||
### 2. Run Pack Test Suite
|
||||
|
||||
```bash
|
||||
# Run comprehensive test suite
|
||||
./packs/core/test_core_pack.sh
|
||||
```
|
||||
|
||||
### 3. Create a Test Rule
|
||||
|
||||
Create a simple rule to test the core pack integration:
|
||||
|
||||
```bash
|
||||
# Create a rule that echoes every 10 seconds
|
||||
attune rule create \
|
||||
--name "test_timer_echo" \
|
||||
--trigger "core.intervaltimer" \
|
||||
--trigger-config '{"unit":"seconds","interval":10}' \
|
||||
--action "core.echo" \
|
||||
--action-params '{"message":"Timer triggered!"}' \
|
||||
--enabled
|
||||
```
|
||||
|
||||
## Updating the Core Pack
|
||||
|
||||
To update the core pack after making changes:
|
||||
|
||||
1. Edit the relevant YAML files in `packs/core/`
|
||||
2. Re-run the loader script:
|
||||
```bash
|
||||
python3 scripts/load_core_pack.py
|
||||
```
|
||||
3. The loader will update existing entries (upsert)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to connect to database"
|
||||
- Verify PostgreSQL is running: `pg_isready`
|
||||
- Check `DATABASE_URL` environment variable
|
||||
- Test connection: `psql $DATABASE_URL -c "SELECT 1"`
|
||||
|
||||
### "pack.yaml not found"
|
||||
- Ensure you're running from the project root
|
||||
- Check the `--pack-dir` argument points to the correct directory
|
||||
- Verify `packs/core/pack.yaml` exists
|
||||
|
||||
### "ModuleNotFoundError: No module named 'psycopg2'"
|
||||
```bash
|
||||
pip install psycopg2-binary pyyaml
|
||||
```
|
||||
|
||||
### "Pack loaded but not visible in API"
|
||||
- Restart the API service to reload pack data
|
||||
- Check pack is enabled: `SELECT enabled FROM attune.pack WHERE ref = 'core'`
|
||||
|
||||
### Actions not executing
|
||||
- Verify action scripts are executable: `chmod +x packs/core/actions/*.sh`
|
||||
- Check worker service is running and can access the packs directory
|
||||
- Verify runtime configuration is correct
|
||||
|
||||
## Development Workflow
|
||||
|
||||
When developing new core pack components:
|
||||
|
||||
1. **Add new action:**
|
||||
- Create `actions/new_action.yaml` with metadata
|
||||
- Create `actions/new_action.sh` (or `.py`) with implementation
|
||||
- Make script executable: `chmod +x actions/new_action.sh`
|
||||
- Test locally: `export ATTUNE_ACTION_*=... && ./actions/new_action.sh`
|
||||
- Load into database: `python3 scripts/load_core_pack.py`
|
||||
|
||||
2. **Add new trigger:**
|
||||
- Create `triggers/new_trigger.yaml` with metadata
|
||||
- Load into database: `python3 scripts/load_core_pack.py`
|
||||
- Create sensor if needed
|
||||
|
||||
3. **Add new sensor:**
|
||||
- Create `sensors/new_sensor.yaml` with metadata
|
||||
- Create `sensors/new_sensor.py` with implementation
|
||||
- Load into database: `python3 scripts/load_core_pack.py`
|
||||
- Restart sensor service
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The loader script supports the following environment variables:
|
||||
|
||||
- `DATABASE_URL` - PostgreSQL connection string
|
||||
- Default: `postgresql://postgres:postgres@localhost:5432/attune`
|
||||
- Example: `postgresql://user:pass@db.example.com:5432/attune`
|
||||
|
||||
- `ATTUNE_PACKS_DIR` - Base directory for packs
|
||||
- Default: `./packs`
|
||||
- Example: `/opt/attune/packs`
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
For automated deployments:
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions workflow
|
||||
- name: Load Core Pack
|
||||
run: |
|
||||
python3 scripts/load_core_pack.py \
|
||||
--database-url "${{ secrets.DATABASE_URL }}"
|
||||
env:
|
||||
DATABASE_URL: ${{ secrets.DATABASE_URL }}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After loading the core pack:
|
||||
|
||||
1. **Create your first rule** using core triggers and actions
|
||||
2. **Enable sensors** to start generating events
|
||||
3. **Monitor executions** via the API or Web UI
|
||||
4. **Explore pack documentation** in `README.md`
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Pack README**: `packs/core/README.md` - Comprehensive component documentation
|
||||
- **Testing Guide**: `packs/core/TESTING.md` - Testing procedures
|
||||
- **API Documentation**: `docs/api-packs.md` - Pack management API
|
||||
- **Action Development**: `docs/action-development.md` - Creating custom actions
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check this troubleshooting section
|
||||
2. Review logs from services (api, executor, worker, sensor)
|
||||
3. Verify database state with SQL queries
|
||||
4. File an issue with detailed error messages and logs
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-01-20
|
||||
**Core Pack Version:** 1.0.0
|
||||
Reference in New Issue
Block a user