calypso/docs/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:

   sudo ./scripts/install-requirements.sh
   

2. PostgreSQL Database Setup:

   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:

   export CALYPSO_DB_PASSWORD="calypso123"
   export CALYPSO_JWT_SECRET="test-jwt-secret-key-minimum-32-characters-long"
   

Building and Running

1. Install Dependencies:

   cd backend
   go mod download
   

2. Build the Application:

   go build -o bin/calypso-api ./cmd/calypso-api
   

3. Run the Application:

   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:

   make run
   

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

Testing Workflow

Step 1: Health Check (No Auth Required)

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

Expected Response:

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

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

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

Expected Response:

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

export TOKEN="your-jwt-token-here"

Step 4: Get Current User

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

Step 5: Test Storage Endpoints

List Physical Disks

curl http://localhost:8080/api/v1/storage/disks \
  -H "Authorization: Bearer $TOKEN"

Sync Disks (Async Task)

curl -X POST http://localhost:8080/api/v1/storage/disks/sync \
  -H "Authorization: Bearer $TOKEN"

Response will include a task_id. Check task status:

curl http://localhost:8080/api/v1/tasks/{task_id} \
  -H "Authorization: Bearer $TOKEN"

List Volume Groups

curl http://localhost:8080/api/v1/storage/volume-groups \
  -H "Authorization: Bearer $TOKEN"

List Repositories

curl http://localhost:8080/api/v1/storage/repositories \
  -H "Authorization: Bearer $TOKEN"

Create Repository (Requires existing VG)

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

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

curl http://localhost:8080/api/v1/scst/targets \
  -H "Authorization: Bearer $TOKEN"

Create Target

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

curl http://localhost:8080/api/v1/system/services \
  -H "Authorization: Bearer $TOKEN"

Get Service Status

curl http://localhost:8080/api/v1/system/services/calypso-api \
  -H "Authorization: Bearer $TOKEN"

Get Service Logs

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

Generate Support Bundle (Async)

curl -X POST http://localhost:8080/api/v1/system/support-bundle \
  -H "Authorization: Bearer $TOKEN"

Step 8: Test IAM Endpoints (Admin Only)

List Users

curl http://localhost:8080/api/v1/iam/users \
  -H "Authorization: Bearer $TOKEN"

Create User

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

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