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

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

2. Build and Run

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

3. Verify Server is Running

curl http://localhost:8083/health

Expected response:

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 5
}

Option 2: Run with Docker

1. Build Image

docker build -t provisioning-server .

2. Run Container

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

docker logs -f provisioning-server

Option 3: Run with Docker Compose

1. Create .env File

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

2. Start Services

docker-compose up -d

3. Check Status

docker-compose ps
docker-compose logs -f

Testing the API

1. Health Check (No Auth)

curl http://localhost:8083/health

2. Login

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

Save the token:

export TOKEN="eyJhbGc..."  # Use token from response

3. List Servers

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

4. Create Server (Check Mode)

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

# 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

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

Interactive mode:

./api_client.sh
# Select options from menu

Python Client

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:

[server]
host = "0.0.0.0"
port = 8083

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

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

Run with config:

provisioning-server --config config.toml

Using Environment Variables

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:

lsof -i :8083

Check logs:

RUST_LOG=debug provisioning-server

Authentication fails

Verify JWT secret is set:

echo $JWT_SECRET

Check token in request:

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

Operation timeout

Increase timeout in config:

[provisioning]
timeout_seconds = 600

Next Steps

1. Read full README.md
2. Review 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 for complete production deployment guide.