attune-system/attune
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

re-uploading work

Browse Source
This commit is contained in:
David Culbreth
2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

401
docs/guides/quick-start.md Normal file
View File

@@ -0,0 +1,401 @@
# Attune API Quick Start Guide
Get the Attune API up and running in minutes!
## Prerequisites
- Rust 1.70+ installed
- PostgreSQL 13+ installed and running
- `sqlx-cli` (will be installed if needed)
## Step 1: Database Setup
The API needs a PostgreSQL database. Run the setup script:
```bash
cd attune
./scripts/setup-db.sh
```
This will:
- Create the `attune` database
- Run all migrations
- Set up the schema
**If the script doesn't work**, do it manually:
```bash
# Connect to PostgreSQL
psql -U postgres
# Create database
CREATE DATABASE attune;
# Exit psql
\q
# Run migrations
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/attune"
cargo install sqlx-cli --no-default-features --features postgres
sqlx migrate run
```
## Step 2: Configure the API
The API uses a YAML configuration file. Create your config from the example:
```bash
cp config.example.yaml config.yaml
```
**Edit the configuration file:**
```bash
nano config.yaml
```
Key settings to review:
```yaml
database:
url: postgresql://postgres:postgres@localhost:5432/attune
security:
jwt_secret: your-secret-key-change-this
encryption_key: your-32-char-encryption-key-here
server:
port: 8080
cors_origins:
- http://localhost:3000
```
**Generate secure secrets for production:**
```bash
# Generate JWT secret
openssl rand -base64 64
# Generate encryption key
openssl rand -base64 32
```
**If your database uses different credentials**, update the database URL in `config.yaml`:
```yaml
database:
url: postgresql://YOUR_USER:YOUR_PASSWORD@localhost:5432/attune
```
## Step 3: Start the API
Simply run:
```bash
cargo run --bin attune-api
```
You should see:
```
INFO Starting Attune API Service
INFO Loaded configuration from config.yaml
INFO Configuration loaded successfully
INFO Environment: development
INFO Connecting to database...
INFO Database connection established
INFO JWT configuration initialized (access: 3600s, refresh: 604800s)
INFO Starting server on 0.0.0.0:8080
INFO Server listening on 0.0.0.0:8080
INFO Attune API Service is ready
```
## Step 4: Test It!
### Health Check
```bash
curl http://localhost:8080/health
```
Expected response:
```json
{
"status": "healthy"
}
```
### Register a User
```bash
curl -X POST http://localhost:8080/auth/register \
-H "Content-Type: application/json" \
-d '{
"login": "admin",
"password": "admin123456",
"display_name": "Administrator"
}'
```
You'll get back access and refresh tokens:
```json
{
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
}
```
### Use the Token
Save your access token and use it for authenticated requests:
```bash
# Replace YOUR_TOKEN with the actual access_token from above
curl http://localhost:8080/auth/me \
-H "Authorization: Bearer YOUR_TOKEN"
```
Response:
```json
{
"data": {
"id": 1,
"login": "admin",
"display_name": "Administrator"
}
}
```
## Step 5: Explore the API
### Available Endpoints
**Authentication:**
- `POST /auth/register` - Register new user
- `POST /auth/login` - Login
- `POST /auth/refresh` - Refresh token
- `GET /auth/me` - Get current user (protected)
- `POST /auth/change-password` - Change password (protected)
**Health:**
- `GET /health` - Basic health check
- `GET /health/detailed` - Detailed status with DB check
- `GET /health/ready` - Readiness probe
- `GET /health/live` - Liveness probe
**Packs:**
- `GET /api/v1/packs` - List all packs
- `POST /api/v1/packs` - Create pack
- `GET /api/v1/packs/:ref` - Get pack by reference
- `PUT /api/v1/packs/:ref` - Update pack
- `DELETE /api/v1/packs/:ref` - Delete pack
### Create a Pack
```bash
curl -X POST http://localhost:8080/api/v1/packs \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ref": "core.basics",
"name": "Basic Operations",
"description": "Core automation pack",
"version": "1.0.0",
"author": "Admin"
}'
```
## Configuration Options
The `.env` file supports many configuration options. See `.env.example` for all available settings.
### Common Customizations
**Change the port:**
```bash
ATTUNE__SERVER__PORT=3000
```
### Debug Logging
Edit `config.yaml`:
```yaml
log:
level: debug
format: pretty # Human-readable output
```
Or use environment variables:
```bash
export ATTUNE__LOG__LEVEL=debug
export ATTUNE__LOG__FORMAT=pretty
cargo run --bin attune-api
```
### Longer Token Expiration (Development)
Edit `config.yaml`:
```yaml
security:
jwt_access_expiration: 7200 # 2 hours
jwt_refresh_expiration: 2592000 # 30 days
```
### Database Connection Pool
Edit `config.yaml`:
```yaml
database:
max_connections: 100
min_connections: 10
```
## Troubleshooting
### Database Connection Failed
```
Error: error communicating with database
```
**Solution:**
1. Verify PostgreSQL is running: `pg_isready`
2. Check credentials in `.env` file
3. Ensure database exists: `psql -U postgres -l | grep attune`
### Migration Errors
```
Error: migration version not found
```
**Solution:**
```bash
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/attune"
sqlx migrate run
```
### Port Already in Use
```
Error: Address already in use
```
**Solution:** Change the port in `.env`:
```bash
ATTUNE__SERVER__PORT=8081
```
### JWT Secret Warning
```
WARN JWT_SECRET not set in config, using default (INSECURE for production!)
```
**Solution:** The default `.env` file has this set. Make sure:
1. The `.env` file exists in the `attune/` directory
2. The variable is set: `ATTUNE__SECURITY__JWT_SECRET=your-secret-here`
## Development Tips
### Auto-reload on Changes
Use `cargo-watch` for automatic rebuilds:
```bash
cargo install cargo-watch
cargo watch -x 'run --bin attune-api'
```
### Enable SQL Query Logging
In `.env`:
Edit `config.yaml`:
```yaml
database:
log_statements: true
```
### Pretty Logs
For development, use pretty formatting:
Edit `config.yaml`:
```yaml
log:
format: pretty
```
For production, use JSON:
Edit `config.yaml`:
```yaml
log:
format: json
```
## Next Steps
- Read the [Authentication Guide](./authentication.md)
- Learn about [Testing](./testing-authentication.md)
- See [API Reference](./auth-quick-reference.md) for all endpoints
- Check out the [Architecture Documentation](./architecture.md)
## Production Deployment
Before deploying to production:
1. **Change JWT Secret:**
```bash
ATTUNE__SECURITY__JWT_SECRET=$(openssl rand -base64 64)
```
2. **Use Environment Variables:**
Don't commit `.env` to version control. Use your platform's secrets management.
3. **Enable HTTPS:**
Configure TLS/SSL termination at your load balancer or reverse proxy.
3. **Use production configuration:**
```bash
# Use production config file
export ATTUNE_CONFIG=config.production.yaml
# Or set environment
export ATTUNE__ENVIRONMENT=production
```
4. **Adjust connection pool** in `config.production.yaml`:
```yaml
database:
max_connections: 100
min_connections: 10
```
6. **Enable JSON Logging:**
```bash
ATTUNE__LOG__FORMAT=json
```
## Getting Help
- Documentation: `docs/` directory
- Issues: GitHub Issues
- API Quick Reference: `docs/auth-quick-reference.md`
Happy automating! 🚀
**Configure CORS origins:**
```bash
# Default (empty) - allows localhost:3000, localhost:8080, 127.0.0.1:3000, 127.0.0.1:8080
ATTUNE__SERVER__CORS_ORIGINS=
# Custom origins (comma-separated)
ATTUNE__SERVER__CORS_ORIGINS=http://localhost:3000,https://app.example.com
```
**Note:** CORS origins must be specified when using authentication (credentials). The API cannot use wildcard origins (`*`) with credentials enabled.