@fleetbase/aws-marketplace

Fleetbase AWS Marketplace Extension

A comprehensive AWS Marketplace SaaS integration extension for Fleetbase that enables CloudFormation template deployment through AWS Marketplace while meeting all SaaS integration requirements.

Overview

This extension provides a complete solution for publishing Fleetbase as a SaaS product on AWS Marketplace while maintaining the ability to deploy CloudFormation templates. It handles customer registration, subscription management, usage tracking, billing, and CloudFormation deployment management.

Features

🔧 Backend Components

• Customer Management: Complete customer registration and profile management
• Subscription Tracking: Real-time subscription status monitoring
• CloudFormation Integration: Deploy and manage AWS infrastructure
• Usage Tracking: Automatic billing and usage reporting
• Security: Comprehensive security and compliance features

🎨 Frontend Components

• Registration Flow: Seamless customer onboarding with AWS token validation
• Dashboard: Comprehensive overview with real-time status updates
• Deployment Management: Create, monitor, and manage CloudFormation stacks
• Billing Interface: Usage tracking and billing reports
• Responsive Design: Works on desktop and mobile devices

🔒 Security Features

• AWS Marketplace token validation
• Webhook signature verification
• Rate limiting and access controls
• Audit logging and monitoring
• Data encryption and protection

Installation

Prerequisites

• Fleetbase instance (v1.6+)
• AWS Account with Marketplace seller access
• PHP 8.1+ with Laravel 10+
• Node.js 16+ with Ember.js
• MySQL/PostgreSQL database

Quick Installation

• Install Backend Package:

  composer require fleetbase/aws-marketplace
  php artisan vendor:publish --provider="Fleetbase\AwsMarketplace\Providers\AwsMarketplaceServiceProvider"
  php artisan migrate
  

• Configure Environment:

  # Add to .env file
  AWS_MARKETPLACE_PRODUCT_CODE=your_product_code
  AWS_MARKETPLACE_ACCESS_KEY_ID=your_access_key
  AWS_MARKETPLACE_SECRET_ACCESS_KEY=your_secret_key
  CLOUDFORMATION_DEFAULT_TEMPLATE_URL=https://your-bucket.s3.amazonaws.com/template.yaml
  

• Install Frontend:

  cd addon && pnpm install && pnpm build
  

For detailed installation instructions, see the Installation Guide.

Configuration

AWS Marketplace Setup

• Create IAM User: With marketplace and CloudFormation permissions
• Configure Product: Set up SaaS product in AWS Marketplace
• Set Webhook URLs: Configure SNS topics for marketplace events
• Upload Templates: Store CloudFormation templates in S3

Environment Variables

# AWS Marketplace Configuration
AWS_MARKETPLACE_PRODUCT_CODE=your_product_code
AWS_MARKETPLACE_SELLER_ID=your_seller_id
AWS_MARKETPLACE_ACCESS_KEY_ID=your_access_key
AWS_MARKETPLACE_SECRET_ACCESS_KEY=your_secret_key
AWS_MARKETPLACE_REGION=us-east-1

# CloudFormation Configuration
CLOUDFORMATION_DEFAULT_TEMPLATE_URL=https://your-bucket.s3.amazonaws.com/template.yaml
CLOUDFORMATION_TEMPLATE_BUCKET=your-cloudformation-templates
CLOUDFORMATION_ALLOWED_REGIONS=us-east-1,us-east-2,us-west-1,us-west-2

# Billing Configuration
MARKETPLACE_BILLING_ENABLED=true
MARKETPLACE_USAGE_DIMENSION=deployment_hours
MARKETPLACE_METERING_ENABLED=true

For complete configuration options, see the Configuration Guide.

Usage

Customer Registration

Customers subscribe through AWS Marketplace and are redirected to your Fleetbase instance for registration:

https://your-fleetbase-domain.com/console/marketplace/register?x-amzn-marketplace-token=TOKEN

CloudFormation Deployment

Once registered, customers can deploy CloudFormation templates:

// Create deployment via API
POST /api/marketplace/deployments
{
  "stack_name": "my-fleetbase-deployment",
  "deployment_region": "us-east-1",
  "template_url": "https://bucket.s3.amazonaws.com/template.yaml",
  "parameters": {
    "InstanceType": "t3.medium",
    "Environment": "production"
  }
}

Usage Tracking

The extension automatically tracks deployment hours and submits usage to AWS Marketplace:

// Usage is tracked automatically
$billingService = app(BillingService::class);
$billingService->recordUsage($subscription, 'deployment_hours', 2.5);

API Reference

The extension provides a comprehensive REST API for all marketplace operations:

Public Endpoints

• POST /marketplace/register - Customer registration
• POST /marketplace/webhook - AWS Marketplace webhooks
• GET /marketplace/config - Public configuration

Authenticated Endpoints

• GET /marketplace/subscription - Subscription details
• GET /marketplace/deployments - List deployments
• POST /marketplace/deployments - Create deployment
• GET /marketplace/billing/summary - Billing summary

For complete API documentation, see the API Reference.

Architecture

Backend Architecture

├── Models/
│   ├── MarketplaceCustomer.php      # Customer management
│   ├── MarketplaceSubscription.php  # Subscription tracking
│   ├── CloudFormationDeployment.php # Deployment management
│   ├── MarketplaceBillingRecord.php # Usage tracking
│   └── MarketplaceEvent.php         # Event logging
├── Services/
│   ├── AwsMarketplaceService.php    # AWS Marketplace API
│   ├── CloudFormationService.php    # CloudFormation operations
│   ├── CustomerService.php          # Customer management
│   ├── BillingService.php           # Usage and billing
│   └── NotificationService.php      # Communications
└── Http/
    ├── Controllers/
    │   └── MarketplaceController.php # API endpoints
    └── Middleware/
        ├── ValidateMarketplaceToken.php
        └── EnsureMarketplaceAccess.php

Frontend Architecture

├── routes/
│   ├── register.js                  # Registration flow
│   └── dashboard.js                 # Main dashboard
├── controllers/
│   ├── register.js                  # Registration logic
│   └── dashboard.js                 # Dashboard logic
├── templates/
│   ├── register.hbs                 # Registration UI
│   └── dashboard.hbs                # Dashboard UI
└── services/
    └── marketplace.js               # API service

Development

Setting Up Development Environment

• Clone Repository:

  git clone https://github.com/fleetbase/aws-marketplace.git
  cd aws-marketplace
  

• Install Dependencies:

  # Backend dependencies
  composer install
  
  # Frontend dependencies
  pnpm install
  

• Run Tests:

  # Backend tests
  composer test
  
  # Frontend tests
  pnpm test
  

Contributing

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Testing

Backend Testing

# Run all tests
composer test

# Run specific test suites
composer test:unit
composer test:integration
composer test:lint

Frontend Testing

# Run all tests
pnpm test

# Run specific tests
pnpm test:ember
pnpm test:lint

Deployment

Production Deployment

• Prepare Environment:

  # Optimize for production
  composer install --no-dev --optimize-autoloader
  php artisan config:cache
  php artisan route:cache
  

• Deploy Frontend:

  pnpm build --environment=production
  

• Run Migrations:

  php artisan migrate --force
  

For detailed deployment instructions, see the Deployment Guide.

Monitoring

Health Checks

The extension provides health check endpoints:

# Check overall health
curl https://your-domain.com/api/marketplace/health

# Check AWS connectivity
curl https://your-domain.com/api/marketplace/health/aws

# Check billing status
curl https://your-domain.com/api/marketplace/health/billing

Logging

Comprehensive logging is available:

• Application logs: storage/logs/marketplace.log
• Billing logs: storage/logs/marketplace-billing.log
• Error logs: storage/logs/laravel.log

Troubleshooting

Common Issues

AWS Credentials

• Verify IAM user permissions
• Check access key and secret key
• Ensure region is correctly configured

CloudFormation Templates

• Validate template syntax
• Check S3 bucket permissions
• Verify template URL accessibility

Webhook Issues

• Verify webhook URL accessibility
• Check SSL certificate validity
• Test webhook signature validation

For detailed troubleshooting, see the Troubleshooting Guide.

Support

Documentation

• Installation Guide
• Configuration Guide
• API Documentation
• Deployment Guide

Community

• GitHub Issues
• Discussions
• Discord Community

Professional Support

• Email: [e-mail]
• Enterprise Support: [e-mail]

License

This project is licensed under the AGPL-3.0-or-later License - see the LICENSE.md file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Fleetbase Team
• All Contributors

Related Projects

• Fleetbase Core
• Fleetbase Console
• Fleetbase CLI