attune/docs/guides/quick-start.md

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:

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:

# 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:

cp config.example.yaml config.yaml

Edit the configuration file:

nano config.yaml

Key settings to review:

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:

# 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:

database:
  url: postgresql://YOUR_USER:YOUR_PASSWORD@localhost:5432/attune

Step 3: Start the API

Simply run:

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

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy"
}

Register a User

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:

{
  "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:

# Replace YOUR_TOKEN with the actual access_token from above
curl http://localhost:8080/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "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

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:

ATTUNE__SERVER__PORT=3000

Debug Logging

Edit config.yaml:

log:
  level: debug
  format: pretty  # Human-readable output

Or use environment variables:

export ATTUNE__LOG__LEVEL=debug
export ATTUNE__LOG__FORMAT=pretty
cargo run --bin attune-api

Longer Token Expiration (Development)

Edit config.yaml:

security:
  jwt_access_expiration: 7200      # 2 hours
  jwt_refresh_expiration: 2592000  # 30 days

Database Connection Pool

Edit config.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:

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:

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:

cargo install cargo-watch
cargo watch -x 'run --bin attune-api'

Enable SQL Query Logging

In .env: Edit config.yaml:

database:
  log_statements: true

Pretty Logs

For development, use pretty formatting: Edit config.yaml:

log:
  format: pretty

For production, use JSON: Edit config.yaml:

log:
  format: json

Next Steps

• Read the Authentication Guide
• Learn about Testing
• See API Reference for all endpoints
• Check out the Architecture Documentation

Production Deployment

Before deploying to production:

1. Change JWT Secret:

   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.

4. Use production configuration:

   # Use production config file
   export ATTUNE_CONFIG=config.production.yaml
   
   # Or set environment
   export ATTUNE__ENVIRONMENT=production
   

5. Adjust connection pool in config.production.yaml:

   database:
     max_connections: 100
     min_connections: 10
   

6. Enable JSON Logging:

   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:

# 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.