prvng_platform/provisioning-server/QUICKSTART.md

# Quick Start Guide

Get the Provisioning API Server running in 5 minutes.

## Prerequisites

- Rust 1.75+ and Cargo
- OR Docker

## Option 1: Run with Cargo (Development)

### 1. Set Environment Variables

```bash
export JWT_SECRET="change-me-in-production"
export PROVISIONING_CLI_PATH="/usr/local/bin/provisioning"
export LOG_LEVEL="info"
```

### 2. Build and Run

```bash
cd provisioning/platform/provisioning-server
cargo run --release
```

### 3. Verify Server is Running

```bash
curl http://localhost:8083/health
```

Expected response:
```json
{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 5
}
```

## Option 2: Run with Docker

### 1. Build Image

```bash
docker build -t provisioning-server .
```

### 2. Run Container

```bash
docker run -d \
  --name provisioning-server \
  -p 8083:8083 \
  -e JWT_SECRET="change-me-in-production" \
  -e PROVISIONING_CLI_PATH="/usr/local/bin/provisioning" \
  provisioning-server
```

### 3. Check Logs

```bash
docker logs -f provisioning-server
```

## Option 3: Run with Docker Compose

### 1. Create .env File

```bash
cat > .env <<EOF
JWT_SECRET=change-me-in-production
PROVISIONING_CLI_PATH=/usr/local/bin/provisioning
EOF
```

### 2. Start Services

```bash
docker-compose up -d
```

### 3. Check Status

```bash
docker-compose ps
docker-compose logs -f
```

## Testing the API

### 1. Health Check (No Auth)

```bash
curl http://localhost:8083/health
```

### 2. Login

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

Save the token:
```bash
export TOKEN="eyJhbGc..."  # Use token from response
```

### 3. List Servers

```bash
curl http://localhost:8083/v1/servers \
  -H "Authorization: Bearer $TOKEN"
```

### 4. Create Server (Check Mode)

```bash
curl -X POST http://localhost:8083/v1/servers/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "default",
    "provider": "upcloud",
    "plan": "1xCPU-2GB",
    "hostname": "test-server",
    "zone": "de-fra1",
    "check_mode": true
  }'
```

### 5. Check Operation Status

```bash
# Use operation ID from previous response
curl http://localhost:8083/v1/operations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"
```

## Using Example Clients

### Bash Client

```bash
cd examples
./api_client.sh health
./api_client.sh login
./api_client.sh list-servers
```

Interactive mode:
```bash
./api_client.sh
# Select options from menu
```

### Python Client

```bash
cd examples
pip install requests  # If not already installed
./python_client.py
```

## Default Users

| Username  | Password    | Role      |
|-----------|-------------|-----------|
| admin     | admin123    | admin     |
| operator  | operator123 | operator  |
| developer | dev123      | developer |

**⚠️ Change these passwords before production!**

## Configuration

### Using Config File

Create `config.toml`:

```toml
[server]
host = "0.0.0.0"
port = 8083

[auth]
jwt_secret = "your-secret-here"

[provisioning]
cli_path = "/usr/local/bin/provisioning"
```

Run with config:
```bash
provisioning-server --config config.toml
```

### Using Environment Variables

```bash
export SERVER_HOST=0.0.0.0
export SERVER_PORT=8083
export JWT_SECRET="your-secret-here"
export PROVISIONING_CLI_PATH="/usr/local/bin/provisioning"

provisioning-server
```

## Troubleshooting

### Server won't start

Check port availability:
```bash
lsof -i :8083
```

Check logs:
```bash
RUST_LOG=debug provisioning-server
```

### Authentication fails

Verify JWT secret is set:
```bash
echo $JWT_SECRET
```

Check token in request:
```bash
curl -v http://localhost:8083/v1/servers \
  -H "Authorization: Bearer $TOKEN"
```

### Operation timeout

Increase timeout in config:
```toml
[provisioning]
timeout_seconds = 600
```

## Next Steps

1. Read full [README.md](README.md)
2. Review [API_REFERENCE.md](API_REFERENCE.md)
3. Explore example clients in `examples/`
4. Configure for production (security checklist in README)
5. Set up monitoring and alerting

## Getting Help

- Check logs: `docker-compose logs -f` or `RUST_LOG=debug cargo run`
- Review error messages: All errors include descriptive messages
- Test with curl: Use `-v` flag for verbose output
- Check health: `curl http://localhost:8083/health`

## Production Deployment

Before deploying to production:

1. ✅ Change all default passwords
2. ✅ Generate strong JWT secret (32+ characters)
3. ✅ Enable TLS/HTTPS
4. ✅ Configure CORS with specific origins
5. ✅ Set up monitoring
6. ✅ Enable audit logging
7. ✅ Review security checklist in README.md

See [README.md](README.md) for complete production deployment guide.