calypso/TESTING-GUIDE.md

# AtlasOS - Calypso Testing Guide

This guide provides step-by-step instructions for testing the implemented backend components.

## Prerequisites

1. **System Requirements Installed**:
   ```bash
   sudo ./scripts/install-requirements.sh
   ```

2. **PostgreSQL Database Setup**:
   ```bash
   sudo -u postgres createdb calypso
   sudo -u postgres createuser calypso
   sudo -u postgres psql -c "ALTER USER calypso WITH PASSWORD 'calypso123';"
   sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE calypso TO calypso;"
   ```

3. **Environment Variables**:
   ```bash
   export CALYPSO_DB_PASSWORD="calypso123"
   export CALYPSO_JWT_SECRET="test-jwt-secret-key-minimum-32-characters-long"
   ```

## Building and Running

1. **Install Dependencies**:
   ```bash
   cd backend
   go mod download
   ```

2. **Build the Application**:
   ```bash
   go build -o bin/calypso-api ./cmd/calypso-api
   ```

3. **Run the Application**:
   ```bash
   export CALYPSO_DB_PASSWORD="calypso123"
   export CALYPSO_JWT_SECRET="test-jwt-secret-key-minimum-32-characters-long"
   ./bin/calypso-api -config config.yaml.example
   ```

   Or use the Makefile:
   ```bash
   make run
   ```

   The API will be available at `http://localhost:8080`

## Testing Workflow

### Step 1: Health Check (No Auth Required)

```bash
curl http://localhost:8080/api/v1/health
```

**Expected Response**:
```json
{
  "status": "healthy",
  "service": "calypso-api"
}
```

### Step 2: Create Admin User (via Database)

Since we don't have a user creation endpoint that works without auth, we'll create a user directly in the database:

```bash
sudo -u postgres psql calypso << EOF
-- Create admin user (password is 'admin123' - hash this properly in production)
INSERT INTO users (id, username, email, password_hash, full_name, is_active, is_system)
VALUES (
  gen_random_uuid(),
  'admin',
  'admin@calypso.local',
  'admin123',  -- TODO: Replace with proper Argon2id hash
  'Administrator',
  true,
  false
) ON CONFLICT (username) DO NOTHING;

-- Assign admin role
INSERT INTO user_roles (user_id, role_id)
SELECT u.id, r.id
FROM users u, roles r
WHERE u.username = 'admin' AND r.name = 'admin'
ON CONFLICT DO NOTHING;
EOF
```

### Step 3: Login

```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

**Expected Response**:
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-01-XX...",
  "user": {
    "id": "...",
    "username": "admin",
    "email": "admin@calypso.local",
    "full_name": "Administrator",
    "roles": ["admin"]
  }
}
```

**Save the token** for subsequent requests:
```bash
export TOKEN="your-jwt-token-here"
```

### Step 4: Get Current User

```bash
curl http://localhost:8080/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"
```

### Step 5: Test Storage Endpoints

#### List Physical Disks
```bash
curl http://localhost:8080/api/v1/storage/disks \
  -H "Authorization: Bearer $TOKEN"
```

#### Sync Disks (Async Task)
```bash
curl -X POST http://localhost:8080/api/v1/storage/disks/sync \
  -H "Authorization: Bearer $TOKEN"
```

**Response** will include a `task_id`. Check task status:
```bash
curl http://localhost:8080/api/v1/tasks/{task_id} \
  -H "Authorization: Bearer $TOKEN"
```

#### List Volume Groups
```bash
curl http://localhost:8080/api/v1/storage/volume-groups \
  -H "Authorization: Bearer $TOKEN"
```

#### List Repositories
```bash
curl http://localhost:8080/api/v1/storage/repositories \
  -H "Authorization: Bearer $TOKEN"
```

#### Create Repository (Requires existing VG)
```bash
curl -X POST http://localhost:8080/api/v1/storage/repositories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-repo",
    "description": "Test repository",
    "volume_group": "vg0",
    "size_gb": 10
  }'
```

**Note**: Replace `vg0` with an actual volume group name from your system.

### Step 6: Test SCST Endpoints

#### List Available Handlers
```bash
curl http://localhost:8080/api/v1/scst/handlers \
  -H "Authorization: Bearer $TOKEN"
```

**Note**: This requires SCST to be installed. If not installed, this will fail.

#### List Targets
```bash
curl http://localhost:8080/api/v1/scst/targets \
  -H "Authorization: Bearer $TOKEN"
```

#### Create Target
```bash
curl -X POST http://localhost:8080/api/v1/scst/targets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iqn": "iqn.2025.atlasos.calypso:repo.test",
    "target_type": "disk",
    "name": "test-disk-target",
    "description": "Test disk target",
    "single_initiator_only": false
  }'
```

**Note**: This requires SCST to be installed and running.

### Step 7: Test System Management Endpoints

#### List Services
```bash
curl http://localhost:8080/api/v1/system/services \
  -H "Authorization: Bearer $TOKEN"
```

#### Get Service Status
```bash
curl http://localhost:8080/api/v1/system/services/calypso-api \
  -H "Authorization: Bearer $TOKEN"
```

#### Get Service Logs
```bash
curl "http://localhost:8080/api/v1/system/services/calypso-api/logs?lines=50" \
  -H "Authorization: Bearer $TOKEN"
```

#### Generate Support Bundle (Async)
```bash
curl -X POST http://localhost:8080/api/v1/system/support-bundle \
  -H "Authorization: Bearer $TOKEN"
```

### Step 8: Test IAM Endpoints (Admin Only)

#### List Users
```bash
curl http://localhost:8080/api/v1/iam/users \
  -H "Authorization: Bearer $TOKEN"
```

#### Create User
```bash
curl -X POST http://localhost:8080/api/v1/iam/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operator1",
    "email": "operator1@calypso.local",
    "password": "operator123",
    "full_name": "Operator One"
  }'
```

#### Get User
```bash
curl http://localhost:8080/api/v1/iam/users/{user_id} \
  -H "Authorization: Bearer $TOKEN"
```

## Automated Testing Script

A helper script is provided at `scripts/test-api.sh` for automated testing.

## Common Issues

### 1. Database Connection Failed
- **Symptom**: Health check returns `503` or startup fails
- **Solution**: 
  - Verify PostgreSQL is running: `sudo systemctl status postgresql`
  - Check database exists: `sudo -u postgres psql -l | grep calypso`
  - Verify credentials in environment variables

### 2. Authentication Fails
- **Symptom**: Login returns `401 Unauthorized`
- **Solution**:
  - Verify user exists in database
  - Check password (currently stubbed - accepts any password)
  - Ensure JWT_SECRET is set

### 3. SCST Commands Fail
- **Symptom**: SCST endpoints return errors
- **Solution**:
  - SCST may not be installed: `sudo apt install scst scstadmin`
  - SCST service may not be running: `sudo systemctl status scst`
  - Some endpoints require root privileges

### 4. Permission Denied
- **Symptom**: `403 Forbidden` responses
- **Solution**:
  - Verify user has required role/permissions
  - Check RBAC middleware is working
  - Some endpoints require admin role

## Testing Checklist

- [ ] Health check works
- [ ] User can login
- [ ] JWT token is valid
- [ ] Storage endpoints accessible
- [ ] Disk discovery works
- [ ] Volume groups listed
- [ ] SCST handlers detected (if SCST installed)
- [ ] System services listed
- [ ] Service logs accessible
- [ ] IAM endpoints work (admin only)
- [ ] Task status tracking works
- [ ] Audit logging captures requests

## Next Steps

After basic testing:
1. Test repository creation (requires LVM setup)
2. Test SCST target creation (requires SCST)
3. Test async task workflows
4. Verify audit logs in database
5. Test error handling and edge cases