Setup Guide

Complete setup instructions for the AquaCloud Integration API in your development environment.

System Requirements

Minimum Requirements

• Operating System: Linux, macOS, or Windows
• Memory: 2GB RAM minimum, 8GB recommended
• Storage: 10GB free space for local database cache
• Network: Stable internet connection for S3 access

Recommended Tools

• curl or Postman for API testing
• Docker for containerized deployment
• Python 3.8+ or Node.js 16+ for SDK usage
• Git for version control

Installation Options

Option 1: Direct API Usage

No installation required - just start making HTTP requests:

# Test API connectivity
curl -X GET "https://api.aquacloud.ai/v3/health"

Option 2: Docker Container

Run the API locally with Docker:

# Pull the latest API container
docker pull aquacloud/integration-api:latest

# Run with environment variables
docker run -d \
  --name aquacloud-api \
  -p 8000:8000 \
  -e AWS_ACCESS_KEY_ID=your-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret \
  -e KEYCLOAK_SERVER_URL=https://auth.aquacloud.ai \
  -e KEYCLOAK_REALM=aquacloud \
  aquacloud/integration-api:latest

Option 3: Python SDK

Install the official Python SDK:

pip install aquacloud-integration

Option 4: Node.js SDK

Install the JavaScript SDK:

npm install @aquacloud/integration-sdk

Environment Configuration

Required Environment Variables

Create a .env file with the following configuration:

# AWS Credentials (Required)
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
AWS_DEFAULT_REGION=us-west-2

# API Configuration
AQUACLOUD_API_URL=https://api.aquacloud.ai
AQUACLOUD_API_VERSION=v3

# Authentication (Choose one method)

# Method 1: Username/Password (Development)
AQUACLOUD_USERNAME=your-username
AQUACLOUD_PASSWORD=your-password

# Method 2: Client Credentials (Production)
AQUACLOUD_CLIENT_ID=your-client-id
AQUACLOUD_CLIENT_SECRET=your-client-secret

# Optional: Local Database Configuration
DB_PERSISTENCE=true
DB_FILE_PATH=./data/aquacloud.db
DB_QUERY_DEBUG=false

# Optional: Performance Settings
QUERY_TIMEOUT=300
MAX_CONCURRENT_QUERIES=10
CACHE_TTL=3600

Environment-Specific Configurations

Development Environment

# Development .env
AQUACLOUD_API_URL=https://dev-api.aquacloud.ai
LOG_LEVEL=DEBUG
DB_PERSISTENCE=false  # Use in-memory for faster testing
RATE_LIMIT_ENABLED=false

Staging Environment

# Staging .env
AQUACLOUD_API_URL=https://staging-api.aquacloud.ai
LOG_LEVEL=INFO
DB_PERSISTENCE=true
QUERY_TIMEOUT=600

Production Environment

# Production .env
AQUACLOUD_API_URL=https://api.aquacloud.ai
LOG_LEVEL=WARNING
DB_PERSISTENCE=true
QUERY_TIMEOUT=300
MAX_CONCURRENT_QUERIES=5

Database Setup

Local Database Configuration

The API supports persistent local databases for improved performance:

Enable Persistence

# In your .env file
DB_PERSISTENCE=true
DB_FILE_PATH=/var/lib/aquacloud/data.db

Initialize Database

# Create data directory
mkdir -p /var/lib/aquacloud

# Set permissions
chmod 755 /var/lib/aquacloud

# The database will be created automatically on first use

Database Management

import os
from aquacloud_integration import Client

# Initialize client
client = Client()

# Load all tables for better performance
client.database.load_all_tables(schema="prod_mart")

# Check database status
status = client.database.get_status()
print(f"Database size: {status['size_mb']} MB")
print(f"Loaded tables: {len(status['tables'])}")

Docker Volume for Persistence

When using Docker, mount a volume for persistent data:

docker run -d \
  --name aquacloud-api \
  -p 8000:8000 \
  -v /host/path/data:/app/data \
  -e DB_PERSISTENCE=true \
  -e DB_FILE_PATH=/app/data/aquacloud.db \
  aquacloud/integration-api:latest

Network Configuration

Firewall Settings

Ensure the following ports are accessible:

Port	Protocol	Purpose
443	HTTPS	API access
8080	HTTP/HTTPS	Keycloak authentication

Proxy Configuration

If behind a corporate proxy:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

For Python SDK:

import requests
from aquacloud_integration import Client

# Configure proxy
proxies = {
    'http': 'http://proxy.company.com:8080',
    'https': 'https://proxy.company.com:8080'
}

client = Client(proxies=proxies)

Verification & Testing

Health Check

Verify API connectivity:

curl -X GET "https://api.aquacloud.ai/v3/health"

Expected response:

{
  "status": "healthy",
  "version": "v3.1.2",
  "timestamp": "2024-01-15T14:30:22Z"
}

Authentication Test

Test authentication:

curl -X POST "https://api.aquacloud.ai/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

Database Connection Test

Test database access:

# Get your access token first
export ACCESS_TOKEN="your-access-token"

# List available tables
curl -X GET "https://api.aquacloud.ai/v3/database/tables" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Query Test

Execute a simple test query:

curl -X POST "https://api.aquacloud.ai/v3/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT COUNT(*) as total FROM fish_growth_data LIMIT 1"
  }'

SDK Setup Examples

Python Setup

# install.py
import os
from aquacloud_integration import Client

def setup_client():
    # Load configuration from environment
    client = Client(
        api_url=os.getenv('AQUACLOUD_API_URL'),
        username=os.getenv('AQUACLOUD_USERNAME'),
        password=os.getenv('AQUACLOUD_PASSWORD')
    )
    
    # Test connection
    try:
        health = client.get_health()
        print(f"✅ Connected to API v{health['version']}")
        return client
    except Exception as e:
        print(f"❌ Connection failed: {e}")
        return None

if __name__ == "__main__":
    client = setup_client()

Node.js Setup

// setup.js
const { AquaCloudClient } = require('@aquacloud/integration-sdk');
require('dotenv').config();

async function setupClient() {
  const client = new AquaCloudClient({
    apiUrl: process.env.AQUACLOUD_API_URL,
    username: process.env.AQUACLOUD_USERNAME,
    password: process.env.AQUACLOUD_PASSWORD
  });

  try {
    await client.authenticate();
    const health = await client.getHealth();
    console.log(`✅ Connected to API v${health.version}`);
    return client;
  } catch (error) {
    console.error(`❌ Connection failed: ${error.message}`);
    return null;
  }
}

module.exports = { setupClient };

Performance Optimization

Local Database Configuration

Optimize local database performance:

# In .env file
DB_PERSISTENCE=true
DB_FILE_PATH=/fast-ssd/aquacloud/data.db  # Use SSD storage
DB_MEMORY_LIMIT=4GB  # Allocate more memory
DB_THREADS=4  # Use multiple threads

Query Optimization

Best practices for query performance:

# Good: Use specific columns and filters
query = """
SELECT farm_id, measurement_date, weight_kg 
FROM fish_growth_data 
WHERE measurement_date >= '2024-01-01' 
  AND farm_id = 'farm_001'
LIMIT 1000
"""

# Avoid: SELECT * without filters
query = "SELECT * FROM fish_growth_data"

Caching Strategy

Implement intelligent caching:

from aquacloud_integration import Client
import time

class CachedClient:
    def __init__(self):
        self.client = Client()
        self.cache = {}
        self.cache_ttl = 3600  # 1 hour
    
    def query_with_cache(self, sql):
        cache_key = hash(sql)
        now = time.time()
        
        # Check cache
        if cache_key in self.cache:
            data, timestamp = self.cache[cache_key]
            if now - timestamp < self.cache_ttl:
                return data
        
        # Execute query
        result = self.client.query(sql)
        
        # Cache result
        self.cache[cache_key] = (result, now)
        return result

Troubleshooting Common Issues

Connection Errors

Problem: Cannot connect to API

curl: (7) Failed to connect to api.aquacloud.ai port 443

Solutions:

1. Check internet connection
2. Verify firewall settings
3. Test with different network
4. Check DNS resolution: nslookup api.aquacloud.ai

Authentication Failures

Problem: 401 Unauthorized responses

{"error": "unauthorized", "message": "Invalid credentials"}

Solutions:

1. Verify username/password in .env file
2. Check if account is active
3. Try generating new API credentials
4. Ensure no special characters in credentials

Database Loading Issues

Problem: Tables won't load into local database

{"error": "load_failed", "message": "S3 access denied"}

Solutions:

1. Verify AWS credentials are correct
2. Check S3 bucket permissions
3. Ensure correct AWS region is set
4. Test S3 access directly: aws s3 ls s3://your-bucket

Performance Issues

Problem: Slow query performance

Solutions:

1. Enable local database persistence
2. Use appropriate indexes
3. Add WHERE clauses to limit data
4. Consider query result caching

Getting Help

If you encounter setup issues:

1. Check Logs: Enable debug logging with LOG_LEVEL=DEBUG
2. Community: Join our GitHub Discussions
3. Support: Contact support@aquacloud.ai with:
   • Your setup configuration (without credentials)
   • Error messages and logs
   • Steps to reproduce the issue

Next Steps

Once setup is complete:

1. Quick Start Guide - Make your first API calls
2. Authentication Guide - Secure your integration

Ready to start building? Try our Quick Start Guide!