attune/docker/QUICK_START.md

Attune Docker Quick Start Guide

Get Attune running in Docker in under 5 minutes!

Prerequisites

• Docker Engine 20.10+ (with BuildKit support)
• Docker Compose V2 (included with Docker Desktop)
• 4GB+ available RAM
• Ports available: 3000, 5432, 5672, 6379, 8080, 8081, 15672

TL;DR - Fastest Path

# Clone and enter directory
cd /path/to/attune

# Stop conflicting system services (if needed)
./scripts/stop-system-services.sh

# Start everything
docker compose up -d

# Check status
docker compose ps

# Access the UI
open http://localhost:3000

Step-by-Step Setup

1. Prepare Your Environment

Stop System Services (if running)

If you have PostgreSQL, RabbitMQ, or Redis running on your system:

./scripts/stop-system-services.sh

This will:

• Stop PostgreSQL (port 5432)
• Stop RabbitMQ (ports 5672, 15672)
• Stop Redis (port 6379)
• Verify ports are free
• Optionally disable services on boot

Alternative: If you want to keep system services, see PORT_CONFLICTS.md for changing Docker ports.

2. Start Attune

docker compose up -d

What happens:

1. Downloads Docker images (first time: ~5-10 min)
2. Creates network and volumes
3. Starts PostgreSQL, RabbitMQ, Redis
4. Runs database migrations automatically (16 migrations)
5. Starts Attune services (API, Executor, Worker, Sensor, Notifier)
6. Starts Web UI

3. Verify Services

# Check all services
docker compose ps

# Expected output - all should be "Up" or "Up (healthy)":
# NAME              STATUS
# attune-api        Up (healthy)
# attune-executor   Up (healthy)
# attune-notifier   Up (healthy)
# attune-sensor     Up (healthy)
# attune-web        Up (healthy)
# attune-worker     Up (healthy)  # May restart if Python missing
# attune-postgres   Up (healthy)
# attune-rabbitmq   Up (healthy)
# attune-redis      Up (healthy)

4. Access Services

Service	URL	Purpose
Web UI	http://localhost:3000	Main interface
API	http://localhost:8080	REST API
API Docs	http://localhost:8080/api-docs	Interactive API documentation
Health Check	http://localhost:8080/health	Service status
RabbitMQ Management	http://localhost:15672	Queue monitoring (attune/attune)

# Test API
curl http://localhost:8080/health

# Open Web UI
open http://localhost:3000  # macOS
xdg-open http://localhost:3000  # Linux

Next Steps

Create Your First User

# Option 1: Use the CLI (recommended)
docker compose exec api attune-service create-admin-user \
  --username admin \
  --email admin@example.com \
  --password changeme

# Option 2: Use the Web UI registration page
open http://localhost:3000/register

Load Core Pack (Optional)

The core pack provides basic actions (HTTP requests, timers, etc.):

./scripts/load-core-pack.sh

Explore the API

# Get JWT token
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}' \
  | jq -r '.access_token')

# List packs
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/packs

# List actions
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/actions

Common Commands

Managing Services

# Start all services
docker compose up -d

# Stop all services
docker compose down

# Restart a specific service
docker compose restart api

# View logs
docker compose logs -f           # All services
docker compose logs -f api       # Single service
docker compose logs --tail 100 api  # Last 100 lines

# Check service status
docker compose ps

Database Operations

# Access PostgreSQL
docker compose exec postgres psql -U attune -d attune

# View applied migrations
docker compose exec postgres psql -U attune -d attune \
  -c "SELECT * FROM _migrations ORDER BY applied_at;"

# Reset database (WARNING: Deletes all data)
docker compose down -v
docker compose up -d

Troubleshooting

# View service logs
docker compose logs api --tail 50

# Check migrations
docker compose logs migrations

# Restart everything
docker compose restart

# Full reset (deletes all data)
docker compose down -v
docker compose up -d

Troubleshooting

Port Already in Use

Error: address already in use

Solution:

./scripts/stop-system-services.sh

Or see PORT_CONFLICTS.md for alternatives.

Services Keep Restarting

Check logs:

docker compose logs api --tail 20

Common issues:

• Database not ready → Wait 30 seconds, should auto-recover
• Configuration error → Check environment variables
• Migration failed → Check docker compose logs migrations

Fix:

docker compose down
docker compose up -d

Migrations Failed

View migration logs:

docker compose logs migrations

Reset and retry:

docker compose down -v  # Deletes database
docker compose up -d

Worker Service Failing

Error: Python validation failed

Cause: Worker container doesn't have Python installed

Solution: This is non-critical. Worker will be fixed in future update. Core services work fine without it.

Can't Access Web UI

Check:

docker compose ps web
docker compose logs web --tail 20

Try:

docker compose restart web
open http://localhost:3000

Configuration

Environment Variables

Create a .env file in the project root to customize settings:

cp env.docker.example .env

Edit .env:

# Security (REQUIRED for production)
JWT_SECRET=your-random-secret-here
ENCRYPTION_KEY=your-32-plus-character-encryption-key-here

# Ports (optional)
API_PORT=8080
WEB_PORT=3000
POSTGRES_PORT=5432

Custom Configuration

Override default config with environment variables:

# Format: ATTUNE__SECTION__KEY=value
export ATTUNE__SECURITY__JWT_SECRET=my-secret
export ATTUNE__DATABASE__URL=postgresql://custom:url@host:5432/db
export ATTUNE__WORKER__WORKER_TYPE=container

See configuration.md for all options.

Stopping Attune

Keep Data (Recommended)

docker compose down

Volumes persist, data retained. Next docker compose up -d restarts with existing data.

Delete Everything

docker compose down -v  # WARNING: Deletes all data

Removes all volumes, containers, and networks. Next startup is fresh install.

Production Deployment

This quick start is for development only. For production:

1. Generate secure secrets:

   openssl rand -base64 32  # JWT_SECRET
   openssl rand -base64 32  # ENCRYPTION_KEY
   

2. Use proper .env file with strong credentials

3. Configure HTTPS with reverse proxy (nginx, Traefik)

4. Set up backups for PostgreSQL volumes

5. Use external database (recommended) instead of containerized

6. Monitor with logging/metrics (Prometheus, Grafana)

See production-deployment.md for details.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Docker Compose                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Web UI     │  │   API        │  │  Executor    │ │
│  │  (React)     │  │  (Rust)      │  │  (Rust)      │ │
│  │  Port 3000   │  │  Port 8080   │  │              │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  Worker      │  │  Sensor      │  │  Notifier    │ │
│  │  (Rust)      │  │  (Rust)      │  │  (Rust)      │ │
│  │              │  │              │  │  Port 8081   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
│  ────────────────  Infrastructure  ─────────────────── │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  PostgreSQL  │  │  RabbitMQ    │  │  Redis       │ │
│  │  Port 5432   │  │  Port 5672   │  │  Port 6379   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
│  ┌────────────────────────────────────────────────┐   │
│  │  Migrations (runs once at startup)             │   │
│  └────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Resources

• Docker Documentation
• Port Conflicts Guide
• Build Race Conditions
• Production Deployment
• Configuration Guide

Getting Help

• View logs: docker compose logs <service>
• Check documentation: docs/ directory
• API documentation: http://localhost:8080/api-docs (when running)
• Report issues: GitHub issues

Quick Reference

Essential Commands

# Start
docker compose up -d

# Stop
docker compose down

# Logs
docker compose logs -f

# Status
docker compose ps

# Restart
docker compose restart

# Reset (deletes data)
docker compose down -v && docker compose up -d

Service URLs

• Web UI: http://localhost:3000
• API: http://localhost:8080
• API Docs: http://localhost:8080/api-docs
• RabbitMQ: http://localhost:15672 (attune/attune)

Default Credentials

• PostgreSQL: attune / attune
• RabbitMQ: attune / attune
• First user: Create via CLI or Web UI

---

Ready to automate? Start building workflows in the Web UI at http://localhost:3000! 🚀